Introduktion til siden, fx. "Siden beskriver..."
Sideinformation
Denne sektion går i dybden med, hvordan du som anvender kan overgå til fleksibel opslagslogik, og indeholder et eksempel på, hvordan en REST-tjeneste kan oversættes til en GraphQL-forespørgsel, der viser anvendelsen af fleksibel opslagslogik i praksis. Eksemplet kommer fra et dokument på Confluence, som Datafordeleren har lavet, for at vise, hvordan de top 10 mest anvendte REST-tjenester kan oversættes til GraphQL tjenester. Resten af oversættelserne kan findes her: [GraphQL-Queries].
Overgangen fra REST-tjenester til GraphQL-tjenester
Med entitetsbaseret GraphQL har det hidtil været vanskeligt at hente større mængder sammenhængende data ad gangen. Her har du som anvender skulle lave flere forskellige kald, for at få samme mængde data som i REST-tjenesterne. Med indførelsen af fleksibel opslagslogik bliver det nu muligt at oversætte REST-tjenester direkte til GraphQL. For nogle REST-kald, der anvender mere end 7 joins i dybden eller 17 joins i alt for at sammensætte data, vil det dog være nødvendigt at opdele forespørgslerne i flere GraphQL-queries. En væsentlig fordel ved GraphQL er, at du nu selv kan vælge præcis, hvilke felter og relationer, der skal returneres. Hvor REST-tjenester returnerer alle, kan du i GraphQL frit fravælge uønskede felter og relationer. Det betyder, at man kun henter den data, man reelt har brug for, hvilket kan minimere behovet for efterfølgende datarensning og øge effektiviteten i dataudtrækket.
Det er vigtigt at nævne, at planen er, at GraphQL-tjenesterne skal erstatte REST-tjenesterne, og at REST-tjenesterne vil blive udfaset og gjort utilgængelige i fremtiden. Planen for dette vil være, at der vil være paralleldrift med både REST og GraphQL-tjenester, hvorefter REST-tjenesten vil blive lukket. Du bør derfor allerede nu overveje at oversætte de tjenester, du benytter, til GraphQL. Hvis oversættelsen ikke sker i tide, vil dune risikere at miste adgang til de tjenester, du er afhængig af, hvilket kan få konsekvenser for systemer, der baserer sig på disse data.
For at gøre overgangen til GraphQL så enkel som mulig, anbefales det kraftigt, at dune anvender et GraphQL-klient. I afsnittet [4.2] om GraphQL-skemaer gennemgås, hvordan GraphQL-skemaerne læses, og hvorfor det er en fordel at benytte et GraphQL-klient.
Eksempel på oversættelse af REST-tjeneste til GraphQL-query
I dette afsnit gennemgås et eksempel på, hvordan en nuværende REST-tjeneste kan oversættes til GraphQL-queries. Formålet med eksemplet er at vise, hvordan du som anvender kan konvertere REST-tjenester til GraphQL-queries og dermed få inspiration til at udforme egne queries. Det er også vigtigt at fremhæve, at du ikke længere er bundet af REST-tjenesternes struktur. Så længe relationerne i relationsbilagene tillader det, kan du nu sammensætte queries, der præcist matcher dine behov. Det åbner mulighed for at opbygge 'egne' tjenester, hvilket ikke tidligere var muligt.
Alle oversættelserne i [GraphQL-Queries] er lavet baseret på pseudo-SQL'en fra Dataleverancespecifikationen (DLS). SQL'en kan findes på [DLS-Udstilling] i ZIP-filerne. Vil du oversætte en REST-tjeneste, som du anvender, kan du bruge SQL'en som udgangspunkt og oversætte så vidt muligt.
Eksempel: Oversættelse af REST-Tjenesten BBRSag
I figur [10.1] oversættes REST-tjenesten for BBRSag. For tjenesten BBRSag ser pseudo-SQL'en for tjenesten således ud:SELECT BBRSagSource.*, SagsniveauSource.* FROM BBRSag AS BBRSagSource
LEFT JOIN Sagsniveau AS SagsniveauSource ON SagsniveauSource.byggesag = BBRSagSource.id_lokalId
WHERE (@Id = NULL OR BBRSagSource.id_lokalId In @Id)
AND (@VirkningFra = NULL OR BBRSagSource.virkningTil = NULL OR @VirkningFra < BBRSagSource.virkningTil)
AND (@VirkningTil = NULL OR BBRSagSource.virkningFra = NULL OR @VirkningTil >= BBRSagSource.virkningFra)
AND (@Virkningsaktoer = NULL OR BBRSagSource.virkningsaktoer = @Virkningsaktoer)
AND (@RegistreringFra = NULL OR BBRSagSource.registreringTil = NULL OR @RegistreringFra < BBRSagSource.registreringTil)
AND (@RegistreringTil = NULL OR BBRSagSource.registreringFra = NULL OR @RegistreringTil >= BBRSagSource.registreringFra)
AND (@Registreringsaktoer = NULL OR BBRSagSource.registreringsaktoer = @Registreringsaktoer)
AND (@Status = NULL OR BBRSagSource.status IN @Status)
AND (@Forretningsproces = NULL OR BBRSagSource.forretningsproces = @Forretningsproces)
AND (@Forretningsomraade = NULL OR BBRSagSource.forretningsomraade = @Forretningsomraade)
AND (@Forretningshaendelse = NULL OR BBRSagSource.forretningshaendelse = @Forretningshaendelse)
AND (@Kommunekode = NULL OR BBRSagSource.Kommunekode = @Kommunekode)
AND (@DAFTimestampFra = NULL OR @DAFTimestampFra <= BBRSagSource.UpdateTimestamp())
AND (@DAFTimestampTil = NULL OR @DAFTimestampTil > BBRSagSource.UpdateTimestamp())
AND (@Bygning = NULL OR SagsniveauSource.stamdataBygning = @Bygning OR SagsniveauSource.sagsdataBygning = @Bygning)
AND (@Enhed = NULL OR SagsniveauSource.stamdataEnhed = @Enhed OR SagsniveauSource.sagsdataEnhed = @Enhed)
AND (@Etage = NULL OR SagsniveauSource.stamdataEtage = @Etage OR SagsniveauSource.sagsdataEtage = @Etage)
AND (@Grund = NULL OR SagsniveauSource.stamdataGrund = @Grund OR SagsniveauSource.sagsdataGrund = @Grund)
AND (@Opgang = NULL OR SagsniveauSource.stamdataOpgang = @Opgang OR SagsniveauSource.sagsdataOpgang = @Opgang)
AND (@TekniskAnlaeg = NULL OR SagsniveauSource.stamdataTekniskAnlaeg = @TekniskAnlaeg OR SagsniveauSource.sagsdataTekniskAnlaeg = @TekniskAnlaeg)
AND (
@PeriodeaendringFra = NULL
OR
@PeriodeaendringTil = NULL
OR (
BBRSagSource.Id_lokalId IN
(
SELECT DISTINCT BBRSagChanges.Id_lokalId FROM BBRSag AS BBRSagChanges
WHERE BBRSagChanges.Id_lokalId IN
(
SELECT DISTINCT BS.Id_lokalId FROM BBRSag AS BS
WHERE
(BS.registreringFra >= @PeriodeaendringFra AND BS.registreringFra <= @PeriodeaendringTil)
OR
(BS.registreringTil >= @PeriodeaendringFra AND BS.registreringTil <= @PeriodeaendringTil)
)
UNION
SELECT DISTINCT SagsniveauChanges.byggesag FROM Sagsniveau AS SagsniveauChanges
WHERE SagsniveauChanges.Id_lokalId IN
(
SELECT DISTINCT SN.id_lokalId FROM Sagsniveau AS SN
WHERE
(SN.registreringFra >= @PeriodeaendringFra AND SN.registreringFra <= @PeriodeaendringTil)
OR
(SN.registreringTil >= @PeriodeaendringFra AND SN.registreringTil <= @PeriodeaendringTil)
)
)
AND BBRSagSource.virkningTil = NULL
AND
(
(
@KunNyesteIPeriode = FALSE
AND
BBRSagSource.registreringFra <= @PeriodeaendringFra AND (BBRSagSource.registreringTil > @PeriodeaendringFra OR BBRSagSource.registreringTil = NULL)
AND
(
SagsniveauSource.id_lokalId = NULL OR
(
SagsniveauSource.virkningTil = NULL AND
SagsniveauSource.registreringFra <= @PeriodeaendringFra AND (SagsniveauSource.registreringTil > @PeriodeaendringFra OR SagsniveauSource.registreringTil = NULL)
)
)
)
OR
(
BBRSagSource.registreringFra <= @PeriodeaendringTil AND (BBRSagSource.registreringTil > @PeriodeaendringTil OR BBRSagSource.registreringTil = NULL)
AND
(
SagsniveauSource.id_lokalId = NULL OR
(
SagsniveauSource.virkningTil = NULL AND
SagsniveauSource.registreringFra <= @PeriodeaendringTil AND (SagsniveauSource.registreringTil > @PeriodeaendringTil OR SagsniveauSource.registreringTil = NULL)
)
)
)
)
))
Kode 10.1: Pseudo-SQL for REST-tjenesten BBRSag
I pseudo SQL-querien henter man alt fra tabellerne BBRSag og BBRSagsniveau og filtrerer på flere parametre. For simplificering er næsten alle disse parametre udeladt og de bitemporale felter håndteres af registreringstid og virkningstid parametrene i GraphQL.
Med entitetsbaseret GraphQL var du nødt til at lave to separate GraphQL-kald for at oversætte denne tjeneste. Et kald for at få BBR_BBRSag entiteten og et kald for at få BBR_Sagsniveau. Så skulle du selv manuelt sammensætte dataen i et system. Med fleksibel opslagslogik er det muligt at joine direkte på sin entitet.
For at lave dette join skal vi først i GraphQL-skemaet finde ud af, hvad relationen hedder. I dette eksempel har relationen et sigende navn, og den var derfor nem at finde. Relationen ser således ud i GraphQL-skemaet:
Bruger man i stedet et GraphQL-klient vil det fremstå under BBR_BBRSag entiteten. Da BBR entiteten indgår i flexible tjenesten kalder vi vores request fra følgende URL:
https://graphql.datafordeler.dk/
flexible/v1?apikey={apikey}
Nu hvor relationen kendes, kan GraphQL-querien opbygges.
{
BBR_BBRSag(
first: 10
registreringstid: "2025-03-28T22:12:56.184158Z"
virkningstid: "2025-11-14T11:28:27.184158Z"
where: {
status: { in
: \[ |
"11", "12"] }
kommunekode: { eq: "0101" }
}
)
Kode 10.2: Første del af BBRSag i GraphQL
Queries er opbygget sådan, at du tager udgangspunkt i overentiteten BBR_BBRSag. Du anvender "first"-parameteren for at begrænse søgningen til de første 10 resultater. Da du kalder flexible-tjenesten skal du benytte de bitemporale felter registreringstid og virkningstid til at filtrere data. Derudover tilføjes valgfrie klausuler, hvor du i dette tilfælde ønsker at hente alle resultater med statuskode 11 eller 12 med kommunekode 0101.
{
pageInfo {
hasNextPage
endCursor
}
Kode 10.3: Paging info
I næste del hentes paging informationer, hvilket gør det lettere for anvenderen at holde overblik over de hentede data. Da "first"-parameteren er sat til kun at vise 10 resultater, kan der være yderligere data på næste side, som ikke vises i det aktuelle udtræk. Det anbefales altid at medtage paginginformationer i sine queries.
nodes {
datafordelerOpdateringstid
datafordelerRegisterImportSequenceNumber
datafordelerRowId
datafordelerRowVersion
forretningshaendelse
forretningsomraade
forretningsproces
id_lokalId
id_namespace
kommunekode
registreringFra
registreringsaktoer
registreringTil
sag001Byggesagsnummer
sag002Byggesagsdato
sag003Byggetilladelsesdato
sag004ForventetPaabegyndelsesdato
sag005Paabegyndelsesdato
sag006IbrugtagningsTilladelse
sag007Henlaeggelse
sag008FaerdigtBygningsareal
sag009ForventetFuldfoertDato
sag010FuldfoerelseAfByggeri
sag012Byggesagskode
sag013AnmeldelseAfByggearbejde
sag016DelvisIbrugtagningsTilladelse
sag017ForeloebigFaerdiggjortBygningsareal
sag018ForeloebigFaerdiggjortAntalLejligheder
sag019Bygherreforhold
sag024DatoForModtagelseAfAnsoegningOmByggetilladelse
sag025DatoForFyldestgoerendeAnsoegning
sag026DatoForNaboorientering
sag027DatoForFaerdigbehandlingAfNaboorientering
sag032Litra
sag033ForeloebigFaerdiggjortAntalLejlighederUdenKoekken
status
virkningFra
virkningsaktoer
virkningTil
bbrSagErTilknyttetSagsniveau(
first: 10
) {
pageInfo {
hasNextPage
endCursor
}
nodes {
datafordelerOpdateringstid
byggesag
forretningshaendelse
forretningsomraade
forretningsproces
id_lokalId
id_namespace
kommunekode
niveautype
registreringFra
registreringsaktoer
registreringTil
sagsdataBygning
sagsdataEnhed
sagsdataEtage
sagsdataGrund
sagsdataOpgang
sagsdataTekniskAnlaeg
sagstype
stamdataBygning
stamdataEnhed
stamdataEtage
stamdataGrund
stamdataOpgang
stamdataTekniskAnlaeg
status
virkningFra
virkningsaktoer
virkningTil
}
}
Kode 10.4: Nodes til BBRSag i GraphQL
Så henter du alle nodes ind. Nodes er der, hvor der bør udfyldes, hvilke felter du ønsker returneret som svar. I pesudo-SQL'en er der "Select *" og du ønsker derfor alle felter ud. Som noget nyt i fleksibel opslagslogik kan du som nævnt lave joins og det vil ske i nodes. Her har vi joinet bbrSagErTilknyttetSagsniveau. Opstillingen af underentiteten vil være på præcis samme måde som opstillingen af en overentitet med undtagelse af, at du ikke kan indstille registreringstid eller virkningstid, da disse arves fra overentiteten. Den samlede query vil så ende med at se således ud:
{
BBR_BBRSag(
first: 10
registreringstid: "2025-03-28T22:12:56.184158Z"
virkningstid: "2025-11-14T11:28:27.184158Z"
where: {
status: { in
: \[ |
"11", "12"] }
kommunekode: { eq: "0101" }
}
) {
pageInfo {
hasNextPage
endCursor
}
nodes {
datafordelerOpdateringstid
datafordelerRegisterImportSequenceNumber
datafordelerRowId
datafordelerRowVersion
forretningshaendelse
forretningsomraade
forretningsproces
id_lokalId
id_namespace
kommunekode
registreringFra
registreringsaktoer
registreringTil
sag001Byggesagsnummer
sag002Byggesagsdato
sag003Byggetilladelsesdato
sag004ForventetPaabegyndelsesdato
sag005Paabegyndelsesdato
sag006IbrugtagningsTilladelse
sag007Henlaeggelse
sag008FaerdigtBygningsareal
sag009ForventetFuldfoertDato
sag010FuldfoerelseAfByggeri
sag012Byggesagskode
sag013AnmeldelseAfByggearbejde
sag016DelvisIbrugtagningsTilladelse
sag017ForeloebigFaerdiggjortBygningsareal
sag018ForeloebigFaerdiggjortAntalLejligheder
sag019Bygherreforhold
sag024DatoForModtagelseAfAnsoegningOmByggetilladelse
sag025DatoForFyldestgoerendeAnsoegning
sag026DatoForNaboorientering
sag027DatoForFaerdigbehandlingAfNaboorientering
sag032Litra
sag033ForeloebigFaerdiggjortAntalLejlighederUdenKoekken
status
virkningFra
virkningsaktoer
virkningTil
bbrSagErTilknyttetSagsniveau(
first: 10
) {
pageInfo {
hasNextPage
endCursor
}
nodes {
datafordelerOpdateringstid
byggesag
forretningshaendelse
forretningsomraade
forretningsproces
id_lokalId
id_namespace
kommunekode
niveautype
registreringFra
registreringsaktoer
registreringTil
sagsdataBygning
sagsdataEnhed
sagsdataEtage
sagsdataGrund
sagsdataOpgang
sagsdataTekniskAnlaeg
sagstype
stamdataBygning
stamdataEnhed
stamdataEtage
stamdataGrund
stamdataOpgang
stamdataTekniskAnlaeg
status
virkningFra
virkningsaktoer
virkningTil
}
}
}
}
}
Kode 10.5: Fulde query for BBRSag
Svaret på querien vil så have medtaget alle felter fra querien. Hvis underentiteten er tom, er det fordi, at der ikke er nogen data på denne. Ønsker du at kalde denne i flexibleCurrent, skal med fjerne registreringstids parameteren.
{
"data": {
"BBR_BBRSag": {
"pageInfo": {
"hasNextPage": true,
"endCursor": "TURBd05qVXlaVEl0WVRBNU9TMDBZbVUyTFdFellqWXRaV1pqTkRRM05XRXpNREZpO01qQXhPQzB3TWkweE5sUXhOem8xT0Rvd01DNHdNREF4TVRrd0t6QXdPakF3O01qQXhOaTB4TWkwd01WUXhNVG95TXpveU15NDFNVGN3TURBd0t6QXdPakF3"
},
"nodes": [
{
"datafordelerOpdateringstid": "2021-04-04T05:39:13.568817Z",
"datafordelerRegisterImportSequenceNumber": 1857504,
"datafordelerRowId": "5d7438ad-5415-4764-9602-eaab858134a6",
"datafordelerRowVersion": 1,
"forretningshaendelse": "Byggesag",
"forretningsomraade": "54.15.05.05",
"forretningsproces": "11",
"id_lokalId": "000652e2-a099-4be6-a3b6-efc4475a301b",
"id_namespace": "http://data.gov.dk/bbr/bbrsag",
"kommunekode": "0101",
"registreringFra": "2018-02-16T17:58:00.000119Z",
"registreringsaktoer": "BBR",
"registreringTil": null,
"sag001Byggesagsnummer": "443870",
"sag002Byggesagsdato": null,
"sag003Byggetilladelsesdato": null,
"sag004ForventetPaabegyndelsesdato": null,
"sag005Paabegyndelsesdato": null,
"sag006IbrugtagningsTilladelse": null,
"sag007Henlaeggelse": null,
"sag008FaerdigtBygningsareal": null,
"sag009ForventetFuldfoertDato": null,
"sag010FuldfoerelseAfByggeri": null,
"sag012Byggesagskode": "3",
"sag013AnmeldelseAfByggearbejde": null,
"sag016DelvisIbrugtagningsTilladelse": null,
"sag017ForeloebigFaerdiggjortBygningsareal": null,
"sag018ForeloebigFaerdiggjortAntalLejligheder": null,
"sag019Bygherreforhold": null,
"sag024DatoForModtagelseAfAnsoegningOmByggetilladelse": "2011-01-13T23:00:00.000000Z",
"sag025DatoForFyldestgoerendeAnsoegning": null,
"sag026DatoForNaboorientering": null,
"sag027DatoForFaerdigbehandlingAfNaboorientering": null,
"sag032Litra": "",
"sag033ForeloebigFaerdiggjortAntalLejlighederUdenKoekken": null,
"status": "11",
"virkningFra": "2016-12-01T11:23:23.517000Z",
"virkningsaktoer": "Konvertering2017",
"virkningTil": null,
"bbrSagErTilknyttetSagsniveau": {
"pageInfo": {
"hasNextPage": false,
"endCursor": "TWpRM01qY3dZamd0TldVMFpDMDBaRE0yTFdJMVkyWXRNVGhqWm1KbU56TTFZelZoO01qQXhOeTB3Tmkwd01sUXhNam95T1Rvek55NHdNREF3TURBd0t6QXdPakF3O01qQXhOaTB4TWkwd01WUXhNVG95TXpveU15NDFNVGN3TURBd0t6QXdPakF3"
},
"nodes": [
{
"datafordelerOpdateringstid": "2021-04-06T11:55:49.595558Z",
"byggesag": "000652e2-a099-4be6-a3b6-efc4475a301b",
"forretningshaendelse": "Byggesag",
"forretningsomraade": "54.15.05.05",
"forretningsproces": "0",
"id_lokalId": "247270b8-5e4d-4d36-b5cf-18cfbf735c5a",
"id_namespace": "http://data.gov.dk/bbr/sagsniveau",
"kommunekode": "0101",
"niveautype": "1",
"registreringFra": "2017-06-02T12:29:37.000000Z",
"registreringsaktoer": "BBR",
"registreringTil": null,
"sagsdataBygning": null,
"sagsdataEnhed": null,
"sagsdataEtage": null,
"sagsdataGrund": "304b8453-8212-407d-86d6-681c3faefd60",
"sagsdataOpgang": null,
"sagsdataTekniskAnlaeg": null,
"sagstype": "0",
"stamdataBygning": null,
"stamdataEnhed": null,
"stamdataEtage": null,
"stamdataGrund": "7e86c455-17d3-4d13-ae7f-24367d6966fc",
"stamdataOpgang": null,
"stamdataTekniskAnlaeg": null,
"status": "9",
"virkningFra": "2016-12-01T11:23:23.517000Z",
"virkningsaktoer": "BBR",
"virkningTil": null
}
]
}
}
]
}
}
}
Kode 10.6: Resultat fra query (begrænset til "first: 1")