Fleksibel opslagslogik er en ny GraphQL-tjeneste på Datafordeleren, der gør det muligt at udstille data gennem brug af joins i GraphQL.

Da det er nødvendigt at have en grundlæggende forståelse af GraphQL for at anvende fleksibel opslagslogik, henvises der til GraphQL på Datafordeleren.

Begreber

I nedenstående tabel er der en begrebsliste for guiden.

Hvad er fleksibel opslagslogik

Fleksibel opslagslogik er en viderebygning af de entitetsbaserede GraphQL-tjenester, der muliggør joins inden for og mellem registre, hvilket giver mulighed for mere komplekse datarelationer og forespørgsler. I fleksibel opslagslogik indarbejdes alle relationer, der er defineret i Grunddatamodellen. Grunddatamodellen giver et samlet overblik over samtlige registre og deres indbyrdes relationer, på tværs af alle tabeller.

Det er vigtigt at nævne, at Grunddatamodel-dokumentionen, som er tilgængelig på Grunddatamodellen, viser den logiske datamodel hvori mod Datafordelerens tjenester udstiller den fysiske datamodel, som registrene har indsendt. Dette kan betyde, at der kan forekomme forskelle og dermed flere eller færre relationer i fleksibel opslagslogik. Med fleksibel opslagslogik bliver det muligt at slå op på alle disse relationer.

Forskellen mellem entitetsbaserede entiteter og fleksibel opslagslogik

Med de entitetsbaserede GraphQL-tjenester er det kun muligt at hente en entitet fra Grunddatamodellen ad gangen. Dette gør at du skal lave flere kald, hvis du har brug for data fra flere forskellige entiteter for så selv at sammensætte entiteterne. I stedet for at udføre flere kald for at få den nødvendige data, gør fleksibel opslagslogik det muligt at hente fra flere entiteter ad gangen, alt imens de bliver sammensat.

Med udgangspunkt i diagrammet nedenfor vil det blive belyst, hvordan du kan bruge diagrammerne fra Grunddatamodellen til at finde disse relationer.

I diagrammet er der en relation fra DAR_Postnummer til DAGI_Postnummerinddeling. I de entitetsbaserede GraphQL-tjenester ville du skulle udføre to separate forespørgsler for denne relation. Først ville du lave en forespørgsel (Se kode DAR_Postnummer) for at hente DAR_Postnummer, og derefter en ny forespørgsel (Se kode DAGI_Postnummerinddeling) for at hente DAGI_Postnummerinddelingen. Herefter skal resultaterne sammensættes for at skabe relationen mellem de to datasæt.

Med fleksibel opslagslogik er det muligt at udføre én samlet forespørgsel, hvor både overentiteten og den relaterende underentitet hentes. Dette eliminerer behovet for flere separate queries og efterfølgende sammensætning. (Se eksempel på kode nedenfor.)

Left Joins i GraphQL

I fleksibel opslagslogik sammensættes forespørgslerne baseret på relationer mellem entiteter. Alle registre har indsendt deres relationsbilag, som definerer, hvilke relationer det er muligt at foretage i fleksibel opslagslogik. Disse relationer danner grundlaget for, hvordan queries konstrueres – nemlig ved hjælp af 'left joins'. Left joins fungerer på samme måde som i SQL, dog med den forskel, at de værdier, der joines på, allerede er foruddefinerede i datamodellen. Det eneste, man som anvender af left joins bør være opmærksom på, er, at du maksimalt må joine op til 17 entiteter i alt og 7 entiteter i dybden (joins inde i joins) ad gangen.

På figuren ovenfor vises det, hvordan left joins fungerer i SQL: Her sammensætter du to tabeller, så alle rækker fra den første tabel vises, og kun de matchende rækker fra den anden tabel inkluderes. I GraphQL fungerer det på samme måde, dog med den forskel, at den værdi, der joines på, som nævnt, er forudbestemt i GraphQL-skemaet og ikke angives direkte i forespørgslen.

Alle relevante join-værdier kan findes i GraphQL-skemaerne for fleksibel opslagslogik, som er tilgængelige på:

• https://graphql.datafordeler.dk/<tjeneste>/v<version>/schema.

Et eksempel på en udfyldt URL kunne være:

• https://graphql.datafordeler.dk/flexible/v1/schema

Her refererer "flexible" til tjenesten med bitemporal filtrering, og "v1" angiver, at systemet på tidspunktet var i version 1.

Når du har downloadet det relevante GraphQL-skema, kan man finde relationerne på to måder. Én mulighed er at åbne GraphQL-skemafilen i et vilkårligt kode- eller tekstredigeringsprogram og manuelt gennemgå indholdet for at identificere de relevante relationer. Da anvenderen typisk ikke kender relationsnavnet på forhånd, kan det være nødvendigt at læse sig frem til den ønskede relation. Relationerne kan have sigende navne, men de kan også være autogenererede og derfor sværere at identificere. Det anbefales derfor at bruge et GraphQL-klient, som gør det nemmere at undersøge, hvilke relationer der findes, og hvor de peger hen. Det kan f.eks. være et værktøj som Altair eller Nitro.

Et tredje alternativ vil være at downloade enten mermaid-filen eller visualiseringen af mermaid-filerne i den konverterede HTML-fil. I mermaid-filen kan man for hver entitet se deres relationer. I den konverterede HTML-fil for mermaid-fil kan man se et diagram over alle entiteter og deres relationer. Man skal zoome langt ind, før det er stort nok til, at man kan se indholdet.

Eksempel med left join

I dette afsnit gennemgås et eksempel på, hvordan left joins fungerer i praksis.

Eksempel: Left join til underentitet fra samme register uden filtrering

I første eksempel er use-casen, at du har en specifik adresse, og du ønsker at finde det tilhørende husnummer.

I denne query starter du i entiteten DAR_Adresse. Som det fremgår af diagrammet fra Grunddatamodellen, kan man, hvis man ønsker husnummeret til en given adresse, gå direkte fra adressen til husnummeret.

GraphQL-skemaet for flexible-tjenesten, som findes på https://graphql.datafordeler.dk/flexible/v1/schema, kan du finde navnet på denne relation. I dette tilfælde hedder relationen adresseHarHusnummer, og derfor bruges det i ovenstående eksempel.

Da relationen er defineret sådan, at husnummer fra DAR_Adresse matches med id_lokalId i DAR_Husnummer, returneres alle relevante resultater for hver adresse med matchende id_lokalId. Det er derfor vigtigt at filtrere i overentiteten (DAR_Adresse) for at begrænse resultatsættet – eksempelvis til en enkelt adresse.

Du kan også angive adressebetegnelsen i filteret og få alle tilhørende husnumre for den pågældende adresse.

Begrænsninger for fleksibel opslagslogik

I fleksibel opslagslogik er der indført begrænsninger for at sikre optimal ydeevne og stabilitet af systemet. I denne sektion vil disse blive gennemgået. Disse begrænsninger adskiller blandt andet også GraphQL-queries fra klassiske SQL-queries.

Inner joins og unions understøttes ikke

Som den første begrænsning understøtter fleksibel opslagslogik ikke "inner join"-operationer, som ellers er mulige i SQL. Datafordeleren understøtter kun left joins, da det returnerer mere data ad gangen end inner joins, og du skal selv filtrere de returnerede resultater efter behov. I nogle tilfælde kan inner-joins dog håndteres ved at omstrukturere rækkefølgen af joins i en GraphQL-forespørgsel. Hvis der filtreres på en entitet med et inner-join, kan dette join i nogle tilfælde flyttes til toppen af GraphQL-forespørgslen og derved ændre på sammensætningen af joins fra REST-tjenesten. For et eksempel på dette se BBRSag på Udvalgte REST-tjenester omsat til GraphQL-queries.

En anden begrænsning er, at set-operatoren "union" fra SQL heller ikke understøttes i fleksibel opslagslogik. Dette skyldes det modsatte af begrundelsen for ikke at understøtte inner joins: Unions kan resultere i meget store datamængder, hvilket kan belaste serveren væsentligt og dermed påvirke alle anvenderne af endepunktet negativt. I situationer, hvor unions er relevante, anbefales det i stedet at udføre flere enkeltstående queries for hver enkelt entitet som ønskes. På den måde fordeles belastningen mere hensigtsmæssigt.

Begrænsning på antal left joins

Selvom left joins er understøttet i Datafordelerens GraphQL, er der en begrænsning på, hvor mange left joins du kan inkludere i en enkelt query. Denne er sat til 17 entiteter i alt og 7 entiteter i dybden (joins inde i joins). Det betyder, at visse REST-tjenester, som tidligere returnerede mange relaterede entiteter i én forespørgsel, ikke altid kan oversættes direkte til én GraphQL-query. I sådanne tilfælde skal forespørgslerne opdeles i flere separate queries.

Det anbefales derfor at overveje, om du reelt har behov for alle de underentiteter, som REST-tjenesten tidligere har returneret. Ofte kan der være data, som ikke er relevante for den konkrete brugssituation, og som med fordel kan frasorteres. Dette kan reducere både datamængde og behovet for efterfølgende filtrering og behandling lokalt.

Eksisterende relationer

I fleksibel opslagslogik er det på forhånd defineret, hvilke relationer der er mulige, og det er derfor ikke muligt for anvederen selv at oprette nye relationer. Hvis en ønsket relation ikke findes, kan man i stedet forsøge at opnå den ønskede sammenhæng ved at joine gennem andre entiteter. For eksempel er det ikke muligt at joine direkte fra DAR_Adresse til BBR_Etage; i stedet kan du opbygge en relation fra DAR_Adresse til BBR_Enhed og derfra videre til BBR_Etage.

Versionering

Det nye i fleksibel opslagslogik er, at alle registre nu er samlet i samme endepunkt. Det betyder, at hvis ét register – for eksempel DAR – får foretaget en ændring, skal alle anvendere, også dem der kun benytter andre registre såsom EJF, skifte til den nye version. Som tidligere gælder det, at der ikke vil blive foretaget breaking changes til en version, der allerede er i drift. Hvis et register indberetter en manglende relation til Datafordeleren, og denne håndteres, træder ændringen først i kraft, når næste version af den eller de pågældende tjenester idriftsættes. Dette skyldes, at flexible- og flexibleCurrent-tjenesterne er fælles for alle registre, og derfor skal alle ændringer samles og implementeres samtidig i en ny version.

I ovenstående eksempel starter tjenesten og alle relationsbilag på version v1.

• I række 2 opdaterer BBR til version v2, og hele tjenesten opdateres til v2.
• I række 3 opdaterer DAGI til version v2, og tjenesten opdateres til v3.
• I række 4 opdaterer DAGI til version v3 og CVR til version v2 samtidig, og systemet opdateres derfor kun én gang og forbliver på v4.

Til sidst vil systemet således have version v4. 

Opbygning af forespørgsler til fleksibel opslagslogik

URL-opbygning

I fleksibel opslagslogik er URL'er opbygget på to måder: Enten som en flexible-tjeneste, hvor der kan filtreres på bitemporalitet og alle registre kan tilgås, undtagen CVR, EJFCustom_PersonSimpelAlt og EJFCustom_PersonSimpelBegrænset, eller som en flexibleCurrent-tjeneste, hvor registreringstid er sat til dags dato.

Det anbefales, at du altid inkluderer en Accept-header med værdien application/graphql-response+json i deres forespørgsler. På den måde tilvælges moderne HTTP-statuskoder, så man får korrekte statuskoder tilbage fra serveren. Uden denne header returneres der altid statuskode 200, også hvis der opstår fejl.

Opsætning af endepunkter

For entitetsbaseret GraphQL er det nødvendigt at hente GraphQL-skemaer for hvert enkelt register for at få en forståelse for, hvordan registrenes data er opbygget. I fleksibel opslagslogik kan man hente et samlet GraphQL-skema, som giver et overblik over alle registres relationer – også på tværs af hinanden. I nedenstående eksempel kan man se, hvordan dette GraphQL-skema hentes ned via en GET request:

• https://graphql.datafordeler.dk/{tjeneste}/{version}/schema?apikey={apikey}

Hvor {tjeneste} erstattes med enten flexibleCurrent eller flexible, {version} erstattes med den nuværende version, som i skrivende stund er v1 og {apikey} erstattes med egen API-key. URL'en kan indtastes i en vilkårlig browser og filen vil automatisk blive downloadet. Den korrekte fil vil hedde "FLEX_CURRENTV001.schema.graphql" eller "FLEXV001.schema.graphql" alt afhængigt af version og tjeneste.

For så at lave specifikke GraphQL-kald vil URL'en næsten se ud på samme måde. Det eneste, der ikke medtages er "schema" parameteren.

• https://graphql.datafordeler.dk/{tjeneste}/{version}?apikey={apikey}

Hvor parameterne igen udskiftes med den korrekte tjeneste, version og API-key. Alternativt kan autentificering opsættes ved hjælp af andre metoder, som forklares i i sektion [5]. Det er ikke et krav at anvende en API-nøgle. Dette gør sig gældende både for GraphQL-skema hentning og -forespørgsler.

GraphQL-skemaer for fleksibel opslagslogik

Tidligere afsnit har både forklaret GraphQL-skemaer og hvordan de hentes ned. Dette afsnit vil afklare hvordan disse bør læses og bruges.

Uden GraphQL-klient

Hvis du ikke ønsker at anvende GrapQL-værktøjer og i stedet vil udforme dine GraphQL-queries manuelt, kan GraphQL-skemaet åbnes i et vilkårligt tekstredigeringsprogram. Her skal du selv finde de ønskede relationer. I tilfælde af du ikke vælger at bruge et GraphQL-klienter, kan du bruge [Grunddatamodellen] for visualisering.

Ovenfor ses et eksempel på, hvordan et join vil fremgå i et GraphQL-skema. Her joines fra DAR_Adresse til BBR_Enhed, hvor relationen sker mellem DAR_Adresse's id_lokalId-værdi og BBR_Enhed's adresseIdentificerer-felt. For de fleste mulige joins vil der kunne findes et tilsvarende felt, der angiver join-betingelsen. Da GraphQL-skemaets tekst ofte er tæt og kompakt, kan det være vanskeligt at overskue eller finde de relevante felter. Et godt råd er at benytte 'CTRL + F' til at søge efter fra- eller til-entiteten i dokumentet.

Som nævnt i afsnit [3.1.2], så kan du som alternativ hente mermaid-filen ned og den konverterede HTML-fil for mermaid-filen ned. Mermaid-filen giver et let læseligt overblik over hvilke relationer, der er understøttet for hver entitet og den konverterede HTML-fil giver et diagram overblik over alle entiteter og deres tilhørende relationer. Du skal som nævnt zoome langt ind i HTML-filen for at se indholdet, da det er meget småt.

Med GraphQL-klient

Det anbefales at benytte en GraphQL-klient til at læse GraphQL-skemaerne, da det gør arbejdet med GraphQL-tjenesterne enklere at læse. Med en GraphQL-klient som Altair eller Nitro bliver sammensætningen af queries gjort enklere.

Eksempel på visning i GraphQL klient

Altair fungerer både som API-klient og GraphQL-klient. Med Altair kan du indlæse det hentede GraphQL-skema for den ønskede tjeneste ved at klikke på "Docs", derefter på "..."-knappen og vælge den relevante fil. Når GraphQL-skemaet er åbnet, kan man frit søge i dokumentationen på en let læselig måde. 

 I eksemplet på figuren neden for ønskes det at finde en relation fra DAR_Adresse til BBR_Enhed. For at gøre dette i Altair søger du på "DAR_Adresse" i Docs-vinduet.

Derefter åbner du entiteten med typen QUERY og klikker på nodes for at se alle felter og relationer, som DAR_Adresse indeholder. Her kan du se, at der findes en relation til BBR_Enhed ved navn AdresseHarEnhed. 

Alternativt kan du holde musen til højre for entitetsnavnet, hvor en "ADD QUERY"-knap vises. Ved at klikke på denne knap udfyldes alle felter automatisk, og der genereres en gyldig query. Det eneste, der herefter skal tilpasses, er valg af underentiteter, registrerings- og virkningstid samt paging.

Oversigt over registre

I nedenstående tabel er der en oversigt over hvilke registre der er tilgængelige i de forskellige tjenester samt om de er adgangsbegrænset. Denne oversigt er er god at bruge til beslutningen om hvilken tjeneste, du vil kalde, samt hvilke der kræver særtilladelser.

Autentifikation til fleksibel opslagslogik

Alle der vil bruge fleksibel opslagslogik skal være autentificeret. For opsætning af autentifikation til fleksibel opslagslogik se Autentifikation og autorisation for GraphQL-tjenester.

Specielt for fleksibel opslagslogik

Da nogle entiteter har begrænset adgang, er det nødvendigt at ansøge om adgang til disse. Du kan både ansøge om adgang og se, hvilke entiteter der er adgangsbegrænsede, under "Dataadgang" i IT-systemet i Datafordeler Administration.

Her vælger du det ønskede register samt de specifikke entiteter, du ønsker adgang til. Følgende registre indeholder entiteter med adgangsbegrænsning: CPR, CVR, EJF, EJFCustom og SVR. Dette krav om adgangsgodkendelse gjaldt også i den entitetsbaserede opslagslogik. Forskellen er, at det nu er muligt at joine mellem både ubegrænsede og begrænsede entiteter, så længe du har den nødvendige adgang til samtlige relevante entiteter. Skal du tilgå disse registre, kan dette ikke gøres ved brug af en API-key. Grundet øget sikkerhedskrav, skal der anvendes Shared Secret.

Bitemporalitet i fleksibel opslagslogik

Bitemporalitet i fleksibel opslagslogik fungerer næsten på samme måde som i entitetsbaseret GraphQL.

Læs mere om bitemporalitet på Datafordeleren - introduktion til bitemporalitet. 

I fleksibel opslagslogik er det ikke er muligt at anvende relationer til CVR, EJFCustom_PersonSimpelAlt og EJFCustom_PersonSimpelBegrænset i det almindelige flexible-miljø, da disse entiteter ikke understøtter filtrering på registreringstid på grund af krav fra registrene. De kan derfor udelukkende tilgås via flexibleCurrent-tjenesten.

Paging

For fleksibel opslagslogik fungerer paging på præcis samme måde som i de entitetbaserede GraphQL-tjenester. Der henvises derfor til GraphQL på Datafordeleren for en dybdegående forklaring af paging. Dette afsnit vil kun tage udgangspunkt i, hvad der er nyt for fleksibel opslagslogik.

PageInfo for underentiteter

GraphQL på Datafordeleren nævner, at du kan hente pageInfo på entiteter med én-til-mange-relationer. Det samme gælder for underentiteter. Det anbefales stærkt at benytte pageInfo både for over- og underentiteter, da det giver det bedst mulige overblik over data og paging.

Querien nedenfor er lavet uden filtrering (where-klausul) for at understrege vigtigheden af pageInfo. I querien hentes der 10 resultater fra overentiteten DAR_Adresse og kun 1 resultat fra underentiteten BBR_Enhed gennem én-til-mange joinet AdresseHarEnhed.

Hvis du så forestiller dig, at man gerne vil have alle resultaterne ud, hvor der er mere end én enhed på en adresse, så giver denne query ikke nok resultater. Du vil i dit resultat kun få ét resultat pr. adresse, og det vil derfor ikke være det korrekte resultat, som du henter ud.

Nedenfor kan du se, hvordan pageInfo belyser dette.

Fordi du bruger pageinfo på underentiteten, kan du se, at "hasNextPage" er true. Det vil sige, at der findes flere resultater, end der er vist. Var pageInfo ikke blevet inkluderet i querien, så ville du ikke vide, at du manglede resultater.

Fejlkoder

Dette afsnit vil gennemgå de fejlkoder, en anvender af fleksibel opslagslogik vil kunne støde på og dermed skabe en forståelse for hvilke type fejl, du kan møde samt hvordan disse løses.

Det bør nævnes, at hvis du som anvender ikke har lavet opt-in på moderne HTTP koder i din API- eller GraphQL-klient eller din browser, vil du ikke altid modtage en fejlkode på din forespørgsel. Du vil i stedet modtage HTTP-kode OK-200.

Korrekte fejlkoder er vigtige, da det er sådan systemer bygget på fleksibel opslagslogik vil kunne flage, at der er en fejl.

Maksimalt antal joins overskredet

En ny type fejl anvendere kan møde er 400 Bad Request med beskrivelsen: "The request exceeds the max allowed number of joins. The max allowed number of joins in a single request is 20." (Se eksempel nedenunder)

Denne fejl opstår, fordi der som nævnt – på trods af muligheden for at lave joins og sammensætte data i fleksibel opslagslogik – er indført en begrænsning for at undgå overbelastning af systemet og sikre god ydeevne. Som tidligere nævnt er grænsen sat til 17 joins i alt eller 7 joins i dybden. Hvis du modtager denne fejl, skyldes det, at man har overskredet det tilladte antal joins i en enkelt request. Der er to løsninger på dette problem:

1. Du kan konsekvent fjerne unødvendige joins.
2. Du kan opdele forespørgslen i flere mindre forespørgsler.

Det bør altid vurderes for hver request om anvenderne har brug for al dataen og om nogle dele kan udelades.

Anvender har ikke adgang til denne ressource

I entitetsbaseret GraphQL kan du kun tilgå en entitet ad gangen, hvilket gjorde det tydeligt, om du havde adgang til en given entitet eller ej. Med fleksibel opslagslogik er det nu muligt at joine til entiteter, som du ikke nødvendigvis har adgang til. Hvis dette sker, vil en query ikke altid resultere i en 401 Unauthorized-fejl, men kan i stedet returnere en 200 OK-status med beskeden: "The current user is not authorized to access this resource." Se eksempel nedenfor:

Den returnerer kun HTTP kode OK-200, hvis ikke man har lavet opt-in til moderne HTTP koder.

Specielt for flexibleCurrent tjenesten

I entitetsbaseret GraphQL har du tidligere kunnet foretage forespørgsler direkte mod hvert registers egne endepunkter.

I fleksibel opslagslogik skal man være opmærksom på forskellen mellem flexible- og flexibleCurrent-tjenesterne. I flexible-tjenesten skal der filtreres både på registreringstid og virkningstid. 

Forsøger du at anvende queries fra flexible-tjenesten direkte på flexibleCurrent-tjenesten, vil du få fejlen: "The argument 'registreringstid' does not exist". (Se eksempel nedenfor).

I eksemplet forsøges der at blive kaldt en query for DAR_Adresse, på flexibleCurrent-tjenesten med registreringstid udfyldt, da man vil joine til en CVR entitet.

Da parameteren registreringstid ikke findes i flexibleCurrent, svarer serveren med HTTP-status 400 Bad Request. Løsningen på dette problem er blot at fjerne parameteren registreringstid fra forespørgslen.

Specielt for flexible tjenesten

I flexible-tjenesten er det ikke muligt at forespørge på alle CVR-entiteter samt EJFCustom_PersonSimpelAlt og EJFCustom_PersonSimpelBegrænset. Dette er tidligere nævnt, men dette afsnit beskriver, hvilken fejlmeddelelse du vil få i sådanne tilfælde. I eksemplet nedenfor forsøges det at kalde en query for CVR på flexible-endepunktet i stedet for flexibleCurrent:

Her vil man modtage en HTTP 400 Bad Request med beskeden: "The field '{entitet}' does not exist on the type 'Query'." Som løsning bør du altid først kontrollere, om entitetens navn er stavet korrekt, da entitetsnavne er case sensitive og selv små stavefejl kan forårsage fejl. Hvis du er sikker på, at queryen er korrekt skrevet, bør du derefter sikre sig, at du kalder den rette tjeneste. Er du sikker på, at du kalder den korrekte tjeneste, bør du undersøge om, at dit kald er tilladt. Dette kan du finde ud af i den givne tjenestes GraphQL-skema.