Spørringer

Alle spørringer tar utgangspunkt i felt på Query-typen og har som hensikt å hente data fra grafen. Vi skiller mellom oppslag og søk. Oppslag krever at du allerede har identifiserende informasjon om det du ønsker å hente data om. Søk setter ingen slike begrensninger.

Du kan bruke GraphQL Voyager eller GraphiQL Explorer for å utforske hvilke data du kan spørre etter.

Oppslag

Oppslag bruker du til å hente informasjon om data du allerede har identifikatorene til. Oppslagsfelt vil ha navn som følger mønsteret {ønsket type}Gitt{identifikator}. Responsen inneholder data du etterspurte i den etterspurte rekkefølgen. null-verdier i resultatet betyr at identifikatoren ikke gir treff.

For eksempel kan vi hente versjon "1" og "2" av emnet med emnekode "FAH342" ved hjelp av følgende oppslagsspørring. Merk at siden emneinformasjon er institusjons-spesifikk trenger vi i tillegg å spesifisere eierInstitusjonsnummer.

query EmneOppslag {
  emnerGittEmnekoder(
    eierInstitusjonsnummer: "1234"
    emnekoder: [
      { emnekode: "FAH342", versjonskode: "2" }
      { emnekode: "FAH342", versjonskode: "1" }
    ]
  ) {
    kode
    versjonskode
  }
}

Dette gir følgende respons:

{
  "data": {
    "emnerGittEmnekoder": [
      null,
      {
        "kode": "FAH342",
        "versjonskode": "1"
      }
    ]
  }
}

Responsen gir som forventet en liste med to elementer: det første er null, mens det andre er versjon "1" av emnet. Nullverdien forteller oss at versjon "2" ikke finnes i databasen eller at brukeren ikke har tilgang til den. For oppslagsfelt kommer elementene i responsen alltid i samme rekkefølge som de ble etterspurt. Dette gjør det mulig å matche responsen mot forespørselen.

Søk

Søk har navn som følger mønsteret {ønsket type}, muligens kvalifisert med avgrensende prefikser. Det skal være enkelt å forstå hva dette prefikset innebærer gitt kjennskap til forretningsdomenet. For eksempel har vi feltene emner og publiseringsklareEmner.

Søkefelt vil kunne ta forskjellig input avhengig av behovet feltet tilrettelegger for. Input kan inkludere et eller flere disse elementene:

• Filtrering for målrettet uthenting av data
• Sortering av resultatetsettet
• Paginering når dette kreves

Merk at vi med "søk" også inkluderer felt som ikke tar input og at vi slik sett bruker dette begrepet noe utvidet.

Et typisk eksempel vil være det tidligere nevnte Query.emner, der et søk for eksempel kan se slik ut:

query EmneSok {
  emner(
    filter: {
      eierInstitusjonsnummer: "1234"
      ikkeUtloptITermin: { arstall: 2024, terminbetegnelse: VAR }
    }
  ) {
    nodes {
      kode
      versjonskode
    }
  }
}

Filtrering

Eventuelle filtreringer ligger som et eget argument som alltid heter filter. Hvilken filtreringsstøtte feltet har kan du se av input-typen til filter-argumentet. I GraphiQL vil du få kontekst-sensitiv informasjon i editoren. I Voyager vil du kunne se på typene i dokumentasjonen til venstre.

Sortering

Når et søkeresultat skal vises for brukere, er det ofte nyttig å kunne få resultatet i en spesifisert rekkefølge. Når dette er støttet vil man oppgi sortering ved input-argumentet orderBy.

Her er et eksempel på dette:

query PersonSok {
  personProfiler(
    filter: {
      eierOrganisasjonskode: "1234"
    }
    orderBy: {
      direction: ASC,
      orderByField: ETTERNAVN_FORNAVN
    }
  ) {
    edges {
      node {
        id
        navn {
          etternavn
          fornavn
        }
      }
    }
  }
}

Dersom du har behov for sortering utover det som allerede finnes ser vi gjerne at du sender inn en forespørsel om dette.

Paginering

I de fleste tilfeller vil et søkeresult være paginert. Her følger vi Relay-standarden for paginering.

Her er eksempel på en paginert spørring:

query EmneSok($after: String) {
  emner(
    first: 2
    after: $after
    filter: {
      eierInstitusjonsnummer: "1234",
      ikkeUtloptITermin: {arstall: 2024, terminbetegnelse: VAR}
    }
  ) {
    pageInfo {
      endCursor
      hasNextPage
    }
    nodes {
      kode
      versjonskode
    }
  }
}

first-parameteret brukes for å angi antall treff per side.

first-parameteret har standardverdier

Dersom du ikke oppgir noen veri for first-parameteret, blir følgende verdier brukt:

• For paginerte felter på Query-rota: 100
• For paginerte felter alle andre steder: 10 Dersom du ønsker flere treff per side en dette, må du angi det eksplisitt. Det er uansett en hard grense på 1000 treff per side.

Her er et eksempel på hvordan svaret kan se ut:

{
  "data": {
    "emner": {
      "pageInfo": {
        "endCursor": "MjA6MTIzNCwxNTAsRkxMLTM2NSwx",
        "hasNextPage": true
      },
      "nodes": [
        {
          "kode": "FAH342",
          "versjonskode": "1"
        },
        {
          "kode": "FLL-215",
          "versjonskode": "1"
        }
      ]
    }
  }
}

I resultatet ser vi at:

• nodes inneholder emnene fra selve resultatet
• pageInfo inneholder informasjon om pagineringen
  • endCursor: Bokmerke for det siste treffet i søkeresultatet
  • hasNextPage: Hvorvidt det finnes flere sider

For å bla til neste side, sender vi inn verdien vi fikk i endCursor i eksempelet over i after-argumentet.