Denne side gennemgår et længere eksempel på, hvordan en anvender kan sammensætte flere af elementerne fra GraphQL på Datafordeleren til at hente data ud fra Datafordeleren ved at bruge de entitetsbaserede GraphQL-tjenester. Eksemplet tager udgangspunkt i at anvenderen kender til Grunddata generelt, har læst vejledningen igennem og orienteret sig på datafordeler.dk, samt orienteret sig omkring den dokumentation som kan findes i Datafordelerens Dokumentation.

Eksemplet fokuserer på brugen af GraphQL på Datafordeleren og går dermed ikke i dybden angående indhentning af rettigheder til data på Datafordeleren.

Sammenhængende data mellem entiteterne BBR_Bygning og DAR_Husnummer

Eksemplet tager udgangspunkt i en anvender, som ønsker at få sammenhængende data mellem BBRs Bygning entitet og DARs Husnummer entitet. For at finde frem til hvilke data der er relevante for anvender, fremsøges relevante oplysninger, metadata, mm. ved de kilder som stilles til rådighed af både Datafordeleren og registrene. Følgende kilder er som udgangspunkt relevante i de fleste tilfælde:

1. Datafordelerens dokumentation: https://datafordeler.dk/vejledning/
2. Datafordelerens dataoversigt: https://datafordeler.dk/dataoversigt/
3. Grunddatamodellen, som beskriver registrenes data
   1. https://grunddatamodel.datafordeler.dk/objekttypekatalog/
   2. https://datafordeler.dk/vejledning/grunddata/datamodel/
4. GraphQL-skemaerne, som beskriver de faktiske data der kan forespørges på, samt hvilke muligheder en anvender har når der forespørges for det enkelte register. 
5. Datafordelerens dokumentation på Confluence

Det fremgår i Grunddatamodellen at BBR og DAR har en relation mellem deres entiteter blandet andet på https://datafordeler.dk/vejledning/grunddata/datamodel/. Det kan her ses at BBR hænger sammen med data i MAT, DAR og GeoDK.

Når BBR undersøges nærmere i Grunddatamodellen, fremgår det af registerets datamodel, at relationen findes mellem BBRs Bygning entitet og DARs Husnummer entitet.

Undersøges DARs Husnummer entitet nærmere, bekræfter registerets datamodel også at der er en relation mellem de to entiteter.

Da det nu er klart for anvender hvilke data der ønskes, samt at data mellem BBR og DAR har en relation, hentes nu de relevante GraphQL-skemaer for BBR og DAR. Dette gøres ved følgende queries:

• GET request til BBR v1 – https://graphql.datafordeler.dk/BBR/v1/schema?apiKey=placeholderNoegle. I dette skema kan BBRs Bygning entitet fremsøges ved ”BBR_Bygning”. Et uddrag af skemafilen kan ses nedenfor.

• GET request til DAR v1 - https://graphql.datafordeler.dk/DAR/v1/schema?apiKey=placeholderNoegle. I dette skema kan DARs Husnummer entitet fremsøges ved ”DAR_Husnummer”. Et uddrag af skemafilen kan ses nedenfor.

Anvenderen kan med fordel her vælge at indlæse skemafilerne i et program, som kan læse GraphQL-skemafiler for at gøre det nemmere at udlede hvilke entiteter der kan forespørges på, samt hvilke felter og filtre der er understøttet for hver entitet og felt.

Det kan i skemaet ses at BBR_Bygning har et felt ved navn ”husnummer”, som kan bruges til at sammensætte entitetens data med et tilhørende husnummer ovre i DAR. Anvenderen ved også at Grunddataregistre som hovedregel bruger ”id_lokalId” til identifikation af objekter over tid, således at det er muligt at fremfinde et objekt, sammen med eventuel historiske versioner af denne. I skemaerne fremsøger anvender de query-muligheder der er på BBR_Bygning og DAR_Husnummer.

Anvenderen kan udlede følgende fra skemaet:

• Parametrene ”first”, ”after”, ”registreringstid”, ”virkningstid” og ”where” kan angives.
• Når ”where” angives, er det påkrævet at bruge henholdsvis et ”BBR_BygningFilterInput” eller ”DAR_HusnummerFilterInput”. Det kan udledes i skemaet hvilke filtreringsmuligheder hver af disse filter inputs giver.

Anvenderen kender nu til de filtreringsmuligheder der er tilgængelige på BBR_Bygning og DAR_Husnummer. Anvender er nu klar til at sammensætte sine GraphQL-queries og hente relevante data ned.

Anvenderen laver nedenstående GraphQL-query på denne URL som en POST request: https://graphql.datafordeler.dk/BBR/v1?apiKey=placeholderNoegle.

Ovenstående GraphQL-query gør følgende:

• Henter data fra BBR_Bygning entiteten, som er angivet i BBR_Bygning.
• Henter pagings metadata som gør det muligt for anvender at page på dataen.
• Henter de første 5 resultater ved brug af “first” parameteret.
• Filtrerer på data således at det kun er data som er bitemporalt gældende d. 23/3/2025, ved at angive registreringstid og virkningstid parametrene.
• Filtrerer data således at det kun er resultater der er beliggende i Odense kommune som returneres, ved at angive “where” parameter med filter på kommunekode.

Fra GraphQL-querien fås følgende svar:

Svaret indeholder de 3 felter der blev spurgt om i forespørgslen for hver af de 5 resultater. Det bemærkes yderligere at der i svaret også fremgår en ”endCursor”. Anvenderen bruger nu værdien på ”endCursor” i sit næste kald til BBR_Bygning ved nu også at angive ”after” parameter:

Fra ovenstående query får anvenderen et svar tilbage der har samme struktur, dog med yderligere data. Anvenderen kan blive ved på denne måde, indtil den ønskede data er hentet. Anvenderen ved at alle resultater er hentet når feltet “hasNextPage” er sat til “false”.

Nu har anvenderen alle ønskede data fra BBR_Bygning, og kan kalde DAR_Husnummer for at hente de husnumre der hænger sammen med de bygningsobjekter der blev returneret fra BBR_Bygning. Dette gør anvender ved at lave en GraphQL-query til DAR_Husnummer som POST request til denne URL: https://graphql.datafordeler.dk/DAR/v1?apiKey=placeholderNoegle.

Ovenstående GraphQL-query gør følgende:

• Henter data fra DAR_Husnummer entiteten, som er angivet i DAR_Husnummer.
• Henter pagings metadata som gør det muligt for anvender at page på dataen.
• Henter de første 5 resultater ved brug af “first” parameteret.
• Filtrerer på data således at det kun er data som er bitemporalt gældende d. 23/3/2025, ved at angive registreringstid og virkningstid parametrene. Bemærk at identiske bitemporale filtre anvendes i querien til DAR_Husnummer, som der blev anvendt til filtreringen på BBR_Bygning. På denne måde sikres det at det er sammenhængende data, som er gældende på samme tidspunkt, som returneres.
• Filtrerer data således at det kun er resultatater som er relaterede til de bygninger som blev returneret i den første query til BBR_Bygning.

Svaret på ovenstående GraphQL-query ser ud som følger:

Anvenderen har nu hentet data fra BBR_Bygning og relateret data fra DAR_Husnummer.