GQL-språkveiledning for graf i Microsoft Fabric

GQL (Graph Query Language) er det ISO-standardiserte spørringsspråket for grafdatabaser. Bruk GQL til å spørre, analysere og arbeide med grafdata effektivt med graf i Microsoft Fabric.

Den samme ISO-arbeidsgruppen som standardiserer SQL utvikler GQL. Som et resultat deler GQL mange konsepter med SQL, inkludert uttrykk, predikater og datatyper. Hvis du har SQL-erfaring, kan du bruke mye av denne kunnskapen på GQL.

Denne artikkelen er den komplette guiden til GQL i graf. Den forklarer hvordan språket henger sammen og lenker til fokuserte referanser for fullstendige syntaks- og typedetaljer. Den dekker:

  • Kjernekonsepter: Diagramdatastrukturer, mønstre og grunnleggende spørringer
  • Essensielle utsagn:MATCH , FILTER, LET, , WHEN, ORDER BY, LIMIT, ogRETURN
  • Datatyper og uttrykk: Verdityper, operatorer og innebygde funksjoner
  • Avanserte teknikker: Komposisjon med flere setninger, variabel omfang og aggregasjonsstrategier

Note

Den offisielle internasjonale standarden for GQL er ISO/IEC 39075 Information Technology - Database Languages - GQL.

Hvis du er ute etter oppgaveorientert veiledning i stedet for en språkgjennomgang, se veiledningene for hvordan du gjør det:

Bruk fokuserte referanseartikler når du trenger fullstendige detaljer:

Nødvendig informasjon Definitiv artikkel
Syntaks i et blikk GQL hurtigreferanse
Node-, kant-, sti- og mønsterkomposisjonssyntaks GQL-grafmønstre
Operatorer, predikater og funksjoner GQL-uttrykk, predikater og funksjoner
Bokstavelig syntaks, verdiatferd og typekonverteringer GQL-verdier og verdityper
Graftypedefinisjoner og begrensninger GQL-graftyper
Nåværende ISO GQL-funksjonsdekning GQL-standardkonformitet
Nåværende Fabric-spesifikke restriksjoner og grenser Nåværende begrensninger

Forutsetninger

Før du begynner, må du kontrollere at du er kjent med disse konseptene:

  • Basic understanding of databases – Erfaring med alle databasesystem som relasjons (SQL), NoSQL eller graf er nyttig.
  • Grafkonsepter – Forståelse av noder, kanter og relasjoner i tilkoblede data.
  • Grunnleggende spørringer – Kunnskap om grunnleggende spørringskonsepter som filtrering, sortering og aggregasjon.

Anbefalt bakgrunn:

  • Erfaring med SQL- eller openCypher-språk gjør det enklere å lære GQL-syntaks (de er GQLs røtter).
  • Kjennskap til datamodellering hjelper med diagramskjemautforming.
  • Forståelse av det spesifikke brukstilfellet for grafdata.

Det du trenger:

  • Tilgang til et diagramarbeidsområde med spørringsfunksjoner.
  • Eksempeldata eller vilje til å arbeide med eksempler på sosiale nettverk.
  • Grunnleggende tekstredigeringsprogram for å skrive spørringer.

Tips

Hvis du ikke har brukt grafdatabaser før du fortsetter med denne veiledningen, begynner du med oversikten over grafdatamodeller .

Hva gjør GQL spesielt

GQL er spesielt designet for grafdata, så syntaksen uttrykker direkte hvordan entiteter er koblet sammen. Der SQL vanligvis uttrykker relasjoner gjennom joins mellom tabeller, bruker GQL grafmønstre som ligner diagrammer av dataene.

For eksempel finner følgende søk par av personer som kjenner hverandre og begge er født før 1999:

MATCH (person:Person)-[:knows]-(friend:Person)
WHERE person.birthday < 19990101
  AND friend.birthday < 19990101
RETURN person.firstName || ' ' || person.lastName AS person_name,
       friend.firstName || ' ' || friend.lastName AS friend_name

Mønsteret (person:Person)-[:knows]-(friend:Person) viser relasjonsstrukturen som matcher. Variabler binder de to personene slik at spørringen kan filtrere og returnere egenskapene deres.

GQL grunnleggende

Disse konseptene danner grunnlaget for GQL:

  • Grafer inneholder noder og kanter med etiketter og egenskaper.
  • Graftyper definerer formelt nodetyper, kanttyper og begrensninger som er tillatt i en graf.
  • Spørringer bruker setninger som MATCH, FILTER, og RETURN for å behandle data og produsere resultater.
  • Mønstre beskriver grafstrukturene slik at de matcher.
  • Uttrykk beregner, transformerer og sammenligner verdier.
  • Predikater er boolske uttrykk som brukes til å teste betingelser.
  • Verdityper definerer hvilke typer verdier spørringer kan behandle og grafegenskaper kan lagre.

Forstå grafdata

For å jobbe med GQL må du forstå den merkede egenskapsgrafstrukturen som språket spør om.

Noder og kanter: byggesteinene

En merket egenskapsgraf inneholder to typer grafelementer:

  • Noder representerer vanligvis enheter, som personer, organisasjoner, innlegg eller produkter.
  • Kanter representerer forbindelser mellom noder, for eksempel at en person kjenner en annen person eller jobber i et selskap.

Hvert grafelement har en intern identitet, én eller flere etiketter, og et sett med egenskaper. Etiketter klassifiserer elementer som Person eller knows. Egenskaper er navn-verdi-par, som firstName: 'Alice' eller birthday: 19730108u. I graf har en kant alltid nøyaktig én etikett.

Hver kant forbinder nøyaktig to noder: et opprinnelsespunkt og et mål. Kantretningen er en del av grafstrukturen. For eksempel kan en workAt kant koble et Person origo til et Company mål.

Note

Graph støtter for øyeblikket ikke å lage urettede kanter. Du kan spørre en eksisterende rettet kant i begge retninger ved å bruke et vilkårlig rettet kantmønster som -[:knows]-.

Grafer er veldannede: hver kant forbinder to noder som finnes i samme graf.

Grafmodeller og graftyper

En Fabric-grafmodell definerer nodetyper, kanttyper, egenskaper, kildekartlegginger og nøkler som er tilgjengelige i en graf. Den spesifiserer hvilke rader i kildetabellen som blir noder og kanter, og hvordan disse elementene kobles sammen. For veiledning om modellering, se Design et grafskjema.

GQL-standarden bruker en graftype for formelt å beskrive tillatte nodetyper, kanttyper, egenskaper og begrensninger. Graftyper er språknivåmotstykket til strukturen representert av en Fabric-grafmodell, men Graph aksepterer for øyeblikket ikke GQL-graftypeerklæringer direkte. For formell syntaks og konsepter, se GQL-graftyper.

Eksempelgraf brukt i denne guiden

Eksempler bruker eksempeldatasett for sosiale nettverk, som inkluderer personer, steder, organisasjoner, meldinger, tagger og kantene som knytter dem sammen.

Eksempelgrafen kobler sammen disse områdene:

  • Folk kjenner andre, jobber i selskaper og studerer ved universiteter.
  • Byer, land eller regioner, og kontinenter danner et geografisk hierarki.
  • Forum inneholder innlegg, og folk lager innlegg og kommentarer.
  • Tagger kategoriserer innhold og representerer folks interesser.

Diagram som viser det sosiale nettverksskjemaet.

For den komplette eksempelstrukturen, se eksempelet på sosialt nettverksskjema. For generelle grafkonsepter, se Merkede egenskapsgrafer.

Dine første GQL-spørringer

Nå som du forstår grunnleggende grafer, kan vi se hvordan du spør etter grafdata ved hjelp av GQL. Disse eksemplene bygger fra enkelt til komplekst, og viser deg hvordan GQLs tilnærming gjør grafspørringer intuitive og kraftige.

Start enkelt: finn alle personer

Begynn med den mest grunnleggende spørringen som er mulig. Finn navnene (fornavn, etternavn) for alle personene (:Persone) i grafen.

MATCH (p:Person)
RETURN p.firstName, p.lastName

Denne spørringen kjører som følger:

  1. MATCH finner alle noder merket Person.
  2. RETURN viser for- og etternavn.

Legg til filtrering: finn bestemte personer

Finn nå personer med spesifikke egenskaper. I dette tilfellet finner du alle som heter Alice og viser navn og fødselsdager.

MATCH (p:Person)
FILTER p.firstName = 'Alice'
RETURN p.firstName, p.lastName, p.birthday

Denne spørringen kjører som følger:

  1. MATCH finner alle noder (p) merket person.
  2. FILTER noder (p) hvis fornavn er Alice.
  3. RETURN viser fornavnet, etternavnet og fødselsdagen.

Grunnleggende spørringsstruktur

Grunnleggende GQL-spørringer følger alle et konsekvent mønster: en sekvens av setninger som arbeider sammen for å finne, filtrere og returnere data. De fleste spørringer starter med MATCH å finne mønstre i grafen og avsluttes med RETURN for å spesifisere resultatet.

Her er et enkelt søk som finner par av personer som kjenner hverandre og har samme bursdag, og deretter returnerer det totale antallet vennepar.

MATCH (n:Person)-[:knows]-(m:Person)
FILTER n.birthday = m.birthday
RETURN count(*) AS same_age_friends

Denne spørringen kjører som følger:

  1. MATCH finner alle parene Person med noder som kjenner hverandre.
  2. FILTER beholder bare parene der begge har samme fødselsdag.
  3. RETURN teller hvor mange slike vennepar som finnes.

Tips

Du kan også filtrere direkte i et mønster ved å legge til en WHERE klausul. For eksempel MATCH (n:Person WHERE n.birthday < 19900101) matcher kun Person noder med en birthday verdi før 1990.

GQL støtter linjekommentarer i C-stil // , linjekommentarer i SQL-stil -- og blokkeringskommentarer i C-stil /* */ .

Vanlige utsagn

  • MATCH: Identifiserer grafmønsteret du skal søke etter—her definerer du strukturen til dataene du er interessert i.
  • LET: Tildeler nye variabler eller beregnede verdier basert på matchede data—legger til avledede kolonner til resultatet.
  • FOR: Utvider en liste til rader, med en valgfri nullbasert offset eller en-basert ordinal posisjon.
  • CALL: Kjører en inline underspørring for hver inndata-rad og legger til kolonnene som returneres av underspørringen.
  • FILTER: Snevrer inn resultatene ved å bruke betingelser—fjerner rader som ikke oppfyller kriteriene.
  • ORDER BY: Sorterer de filtrerte dataene – hjelper til med å organisere utdataene basert på ett eller flere felt.
  • OFFSET og LIMIT: Begrens antall rader som returneres—nyttig for paginering eller top-k spørringer.
  • RETURN: Spesifiserer den endelige utdataen—definerer hvilke data som skal inkluderes i resultatsettet og utfører aggregering.
  • NEXT: Starter et nytt spørringsstadium ved å bruke kolonnene returnert fra forrige fase.

Slik fungerer setninger sammen

GQL-setninger danner en pipeline, hvor hver setning behandler utdataene fra den forrige. Denne sekvensielle utførelsen gjør spørringer enkle å lese og feilsøke fordi utførelsesrekkefølgen samsvarer med leserekkefølgen.

Nøkkelpunkter:

  • Setninger utføres effektivt sekvensielt.
  • Hver setning transformerer data og sender dem videre til neste.
  • Denne prosessen oppretter en klar, forutsigbar dataflyt som forenkler komplekse spørringer.
  • NEXT Starter en ny spørringsfase. Kun kolonner projisert av den foregående RETURN setningen er tilgjengelige i neste fase.
  • UNION, UNION DISTINCT, og UNION ALL kombinerer resultatene av komplette spørringsblokker.

Note

Utsagn har en definert logisk rekkefølge. Skriv spørringer i henhold til denne dataflyten i stedet for å stole på en bestemt fysisk utførelsesstrategi.

Eksempel på setningssammensetning

Følgende GQL-søk finner de første 10 personene som jobber i selskaper med "Air" i navnet, sorterer dem etter fullt navn, og returnerer deres fulle navn sammen med navnet på selskapene sine.

-- Data flows: Match → Let → Filter → Order → Limit → Return
MATCH (p:Person)-[:workAt]->(c:Company)           -- Input: unit table, Output: (p, c) table
LET fullName = p.firstName || ' ' || p.lastName   -- Input: (p, c) table, Output: (p, c, fullName) table
FILTER c.name CONTAINS 'Air'                      -- Input: (p, c, fullName) table, Output: filtered table
ORDER BY fullName                                 -- Input: filtered table, Output: sorted table
LIMIT 10                                          -- Input: sorted table, Output: top 10 rows table
RETURN fullName, c.name AS companyName            -- Input: top 10 rows table
                                                  -- Output: projected (fullName, companyName) result table

Denne spørringen kjører som følger:

  1. MATCH Finner folk som jobber i selskaper.
  2. LET oppretter fullstendige navn ved å kombinere fornavn og familienavn.
  3. FILTER beholder kun ansatte i selskaper med "Air" i firmanavnet.
  4. ORDER BY sorterer etter fullt navn.
  5. LIMIT tar de første 10 resultatene.
  6. RETURN returnerer fulle navn og firmanavn.

Variabler kobler sammen dataene dine

Variabler, for eksempel p, cog fullName i de forrige eksemplene, overfører data mellom setninger. Når du bruker et variabelnavn på nytt, sikrer GQL automatisk at det refererer til de samme dataene, noe som skaper kraftige sammenføyningsbetingelser. Variabler kalles noen ganger også bindingsvariabler.

Du kan kategorisere variabler på forskjellige måter:

Ved bindingskilde:

  • Mønstervariabler – bundet av samsvarende grafmønstre
  • Vanlige variabler – bundet av andre språkkonstruksjoner

Mønstervariabeltyper:

  • Elementvariabler – binde til referanseverdier for grafelement
    • Nodevariabler – binde til individuelle noder
    • Edge-variabler – binde til individuelle kanter
  • Banevariabler – binde til baneverdier som representerer samsvarende baner

Etter referansegrad:

  • Singleton-variabler – binde til individuelle elementreferanseverdier fra mønstre
  • Gruppevariabler – bind til lister med elementreferanseverdier fra mønstre med variabel lengde. For detaljer, se Aggregerte funksjoner.

Resultater og resultater for kjøring

Når du kjører en spørring, får du tilbake et utførelsesresultat som består av:

  • Et resultat, vanligvis en resultattabell med dataene fra uttalelsen din RETURN .
  • Statusinformasjon som viser om spørringen var vellykket eller ikke.

Resultattabeller

Resultattabellen – hvis den finnes – er det faktiske resultatet av kjøring av spørring.

En resultattabell inneholder informasjon om navnet og typen til kolonnene, en foretrukket kolonnenavnsekvens som skal brukes til å vise resultater, om tabellen er bestilt og selve radene.

Note

Hvis kjøring mislykkes, inkluderes ingen resultattabell i utførelsesresultatet.

Utelatte resultater

GQL definerer også et utelatt resultat for setninger som aldri produserer rader, uavhengig av dataene eller evalueringsresultatet. Et utelatt resultat har statuskode 00001for vellykket fullføring .

Et utelatt resultat skiller seg fra en tom resultattabell. En tom tabell betyr at en radproduserende spørring ble evaluert, men ikke produserte noen rader. Query API kan representere et utelatt resultat med resultattype NOTHING.

Grafreserver utelatte resultater for fremtidig støtte for datadefinisjonsspråk (DDL) og datamanipulasjonsspråk (DML) setningsstøtte. Nåværende spørringssetninger gir tabellresultater, inkludert tomme tabeller.

Statusinformasjon

Under kjøring av spørring oppdager prosessen ulike bemerkelsesverdige betingelser, for eksempel feil eller advarsler. Hver betingelse registreres av et statusobjekt i statusinformasjonen for utførelsesresultatet.

Statusinformasjonen består av et primærstatusobjekt og en (muligens tom) liste over andre statusobjekter. Det primære statusobjektet finnes alltid, og angir om spørringskjøringen var vellykket eller mislykket.

Hvert statusobjekt inkluderer en femtegns alfanumerisk kode og en beskrivelse av den registrerte tilstanden.

Query API bruker følgende primære statuskoder:

API-statuskode Betydning
00000 Vellykket fullføring med minst én rad.
00001 Vellykket fullføring med utelatt resultat. Reservert for fremtidig DDL- og DML-støtte.
01000 En advarsel eller informasjonsbetingelse.
02000 Ingen rader er for øyeblikket tilgjengelige fra en radproduserende spørring.
42000 En brukerkorrigerbar spørringsfeil.
50000 En system- eller uklassifisert feil.

API-et bevarer den kanoniske GQL-statusen rapportert av spørringsmotoren i _graphaneGqlStatus medlemmet av diagnoseposten. For eksempel bruker numerisk overløp kanonisk GQLSTATUS 22003, mens divisjon med null bruker 22012; begge representeres av 42000 i det offentlige status.code feltet.

Viktig!

I applikasjonskode, bruk status.code for bred suksess og feilhåndtering. Bruk den kanoniske GQLSTATUS-diagnosen når du trenger å skille en spesifikk forespørselsbetingelse. Ikke test beskrivelsesteksten fordi den kan variere.

I tillegg kan statusobjekter inneholde et underliggende årsaksstatusobjekt og en diagnosepost med ytterligere informasjon som karakteriserer den registrerte betingelsen.

Se referansen til GQL-statuskoder

Viktige konsepter og setninger

Denne delen dekker kjernebyggeblokkene du trenger for å skrive effektive GQL-spørringer. Hvert konsept bygger mot praktiske ferdigheter for spørringsskriving.

Grafmønstre: finn struktur

Et grafmønster beskriver nodene, kantene og stiene som skal matches. Bind variabler når senere utsagn må referere til matchede elementer:

MATCH (person:Person)-[employment:workAt]->(company:Company)
RETURN person.firstName, company.name, employment.workFrom

Plasser et predikat i linje når det definerer hvilken node eller kant som kan delta i mønsteret:

MATCH (person:Person WHERE person.firstName = 'Alice')
      -[:knows]->(friend:Person)
RETURN friend.firstName, friend.lastName

Gjenbruk en variabel for å kreve to mønsterposisjoner for å binde det samme elementet. Separer mønstre med kommaer for å lage større grafstrukturer. Bruk en kvantifikator for {1,4} eksempel for å gjenta et kantmønster og matche baner med variabel lengde.

Stimoduser kontrollerer gjenbruk av elementer innenfor en sti:

Banemodus Virkemåte
WALK Tillater gjentatte noder og kanter. Denne modusen er standard.
TRAIL Forhindrer gjentatte kanter.
SIMPLE Forhindrer gjentatte noder bortsett fra en delt første og siste node.
ACYCLIC Forhindrer alle gjentatte noder.

Et stisøkeprefiks styrer hvilke matchende stier som returneres. ALL er standarden. ANY SHORTEST returnerer én korteste vei for hvert kilde-destinasjonspar:

MATCH path = ANY SHORTEST
  (source:Person WHERE source.id = 123u)-[:knows]->{1,4}(target:Person)
RETURN target.id, path_length(path) AS hopCount

Inline-predikater begrenser sti-egnethet før stivalg. Setningsnivå- MATCH ... WHERE og senere FILTER operasjoner er postfiltre. Dette skillet kan endre ANY SHORTEST resultatene.

For definitiv semantikk for node-, kant-, bane-, sammensetnings-, kvantifikator- og predikatplasserings-, se GQL-grafmønstre. For gjeldende stibegrensninger, se Nåværende begrensninger.

Kjernesetninger

GQL inneholder bestemte setningstyper som arbeider sammen for å behandle grafdataene trinn for trinn. Det er viktig å forstå disse setningene for å bygge effektive spørringer.

MATCH uttalelse

Syntaks:

MATCH <graph pattern>, <graph pattern>, ... [ WHERE <predicate> ]

Setningen MATCH tar inndata og finner grafmønstre. Den slår sammen inndatavariabler med mønstervariabler og utdata som alle samsvarer med kombinasjoner.

Inndata- og utdatavariabler:

-- Input: unit table (no columns, one row)
-- Pattern variables: p, c  
-- Output: table with (p, c) columns for each person-company match
MATCH (p:Person)-[:workAt]->(c:Company)

Filtrering på setningsnivå ved hjelp av WHERE:

-- Filter pattern matches
MATCH (p:Person)-[:workAt]->(c:Company) WHERE p.lastName = c.name

Du kan filtrere alle treff etter filtrering ved hjelp WHEREav . Denne fremgangsmåten unngår en egen FILTER setning. Med et sti-søk-prefiks som ANY SHORTEST, gjelder setningsnivået WHERE etter valg av sti. Inline-predikater begrenser i stedet hvilke stier som er kvalifisert for valg. For mer informasjon, se Plasser-predikater før eller etter valg av sti.

Sammenføyning ved hjelp av inndatavariabler:

Når MATCH det ikke er den første setningen, kobles inndata sammen med mønstersamsvar:

...
-- Input: table with 'targetCompany' column
-- Implicit join: targetCompany (equality join)
-- Output: table with (targetCompany, p, r) columns
MATCH (p:Person)-[r:workAt]->(targetCompany)

Viktig!

Graf støtter grunnleggende og full lineær setningskomposisjon, inkludert NEXT. Du kan også kombinere spørringsblokker med UNION, UNION DISTINCT, og UNION ALL. , EXCEPTINTERSECT, og OTHERWISE set-operasjonene støttes ennå ikke. Hvis du vil ha mer informasjon, kan du se artikkelen om gjeldende begrensninger.

Virkemåter for nøkkelkobling:

Slik MATCH håndterer du datakobling:

  • Variabel likhet: Inndatavariabler kobles sammen med mønstervariabler ved hjelp av likhetssamsvar
  • Indre sammenføyning: Inndatarader uten mønstersamsvar forkastes. Brukes OPTIONAL MATCH til venstre-ytre sammenføyningsvirkemåte.
  • Filtreringsrekkefølge: Setningsnivå-filtre WHERE etter mønstergjenkjenning og stivalg fullført
  • Mønsterkomposisjon: Delte variabler begrenser mønstre til samme element. Usammenhengende mønstre danner et kartesisk produkt.

Viktig!

Et frakoblet mønster er gyldig, men dets kartesiske produkt kan lage mange rader. Bruk delte variabler når mønstrene skal referere til de samme grafelementene.

Koble sammen mønstre med delte variabler:

-- Shared variable 'p' joins the two patterns
-- Output: people with both workplace and residence data
MATCH (p:Person)-[:workAt]->(c:Company), 
      (p)-[:isLocatedIn]->(city:City)

OPTIONAL MATCH uttalelse

Syntaks:

OPTIONAL MATCH <graph pattern> [ WHERE <predicate> ]

OPTIONAL MATCH fungerer som MATCH , men bruker venstre-ytre-bli semantikk. Hvis mønsteret ikke finner noen treff for en inndatarad, beholder spørringen raden med NULL verdier for uovertruffen variabler i stedet for å forkaste den.

Eksempel:

-- Find all people and, if available, their workplace
MATCH (p:Person)
OPTIONAL MATCH (p)-[:workAt]->(c:Company)
RETURN p.firstName, p.lastName, c.name AS company_name

Personer som ikke jobber i noen bedrift, vises fremdele i resultatene med NULL for company_name.

Tips

Bruk OPTIONAL MATCH når du vil inkludere enheter som kanskje ikke har en bestemt relasjon, på samme måte som en SQL LEFT JOIN.

LET uttalelse

Syntaks:

LET <variable> = <expression>, <variable> = <expression>, ...

Setningen LET oppretter beregnede variabler og muliggjør datatransformasjon i spørringssamlebåndet.

Grunnleggende oppretting av variabel:

MATCH (p:Person)
LET fullName = p.firstName || ' ' || p.lastName
RETURN *
LIMIT 1000

Komplekse beregninger:

MATCH (p:Person)
LET adjustedAge = 2000 - (p.birthday / 10000),
    fullProfile = p.firstName || ' ' || p.lastName || ' (' || p.gender || ')'
RETURN *
LIMIT 1000

Viktige virkemåter:

  • Spørringsmotoren evaluerer uttrykk for hver inndatarad.
  • Resultatene blir nye kolonner i utdatatabellen.
  • Variabler kan bare referere til eksisterende variabler fra tidligere setninger.
  • Flere tildelinger i én LET setning bruker samme inndataomfang, så en tildeling kan ikke referere til en annen tildeling fra den setningen.

FOR uttalelse

Syntaks:

FOR <variable> IN <list_expression>
  [ WITH OFFSET <offset_variable> | WITH ORDINALITY <ordinality_variable> ]

Uttalelsen FOR utvider en liste til rader. For hver inputrad sender den ut én outputrad for hvert listeelement og binder dette elementet til den spesifiserte variabelen. Andre variabler fra inngangsraden forblir tilgjengelige.

Bruk WITH OFFSET for å binde en nullbasert indeks, eller bruk WITH ORDINALITY for å binde en en-basert posisjon.

LET cities = ['Seattle', 'London', 'Tokyo']
FOR city IN cities WITH ORDINALITY position
RETURN city, position

Denne spørringen returnerer én rad for hver by. Verdiene position er 1, 2, og 3. Hvis du erstatter WITH ORDINALITY position med WITH OFFSET position, er 0verdiene , 1, og 2.

Kildeuttrykket må evalueres til en liste. En ikke-listeverdi får spørringen til å feile.

CALL uttalelse

Bruk CALL til å kjøre en inline underspørring for hver inndatarad:

CALL {
  <query statements>
  RETURN <columns>
}

Variabler som allerede er innenfor omfanget er implisitt tilgjengelige inne i delspørringen. Av variablene som opprettes inne i underspørringen, er det kun kolonner fra dens endelige RETURN setning som blir tilgjengelige utenfor den. Variabler opprettet i underspørringen, men ikke returnert, forblir lokale.

Følgende korrelerte delspørsel beregner arbeidsgiverantallet for hver person:

MATCH (p:Person)
CALL {
  MATCH (p)-[:workAt]->(company:Company)
  RETURN count(*) AS employerCount
}
RETURN p.firstName, p.lastName, employerCount
ORDER BY employerCount DESC

En vanlig CALL oppfører seg som en avhengig indre join. Den produserer én utdatarad for hver rad som returneres av delspørringen. Hvis delspørringen ikke returnerer noen rader, returneres ikke den tilsvarende ytre raden. Hvis den returnerer flere rader, vises den ytre raden én gang for hver underspørringsrad.

Det foregående count(*) eksempelet returnerer alltid én underspørringsrad fordi det bruker en ugruppert aggregering. En person uten matchende arbeidsgiver har derfor en employerCount av 0.

Bruk OPTIONAL CALL som en avhengig venstre-join. Når delspørringen returnerer ingen rader, bevarer den én ytre rad og setter de returnerte underspørringskolonnene til NULL. Når underspørringen returnerer flere rader, produserer den én utdatarad for hver underspørringsrad.

MATCH (p:Person)
OPTIONAL CALL {
  MATCH (p)-[:workAt]->(company:Company)
  RETURN company.name AS companyName
}
RETURN p.firstName, p.lastName, companyName

Du kan legge inn inline-underforespørsler CALL . En nestret underspørring kan referere til variabler fra sine omsluttende spørringsomfang.

Viktig!

Avslutt hver inline-kropp CALL med RETURN. Graph støtter ikke navngitte prosedyrekall eller eksplisitte variabelimportlister som CALL (p) { ... }.

FILTER uttalelse

Syntaks:

FILTER [ WHERE ] <predicate>

Erklæringen FILTER gir nøyaktig kontroll over hvilke data som går gjennom spørringssamlebåndet.

Grunnleggende filtrering:

MATCH (p:Person)
FILTER p.birthday < 19980101 AND p.gender = 'female'
RETURN *

Komplekse logiske betingelser:

MATCH (p:Person)
FILTER (p.gender = 'male' AND p.birthday < 19940101) 
  OR (p.gender = 'female' AND p.birthday < 19990101)
  OR p.browserUsed = 'Edge'
RETURN *

Nullavhengige filtreringsmønstre:

Bruk disse mønstrene til å håndtere nullverdier på en trygg måte:

  • Se etter verdier: p.firstName IS NOT NULL - har et fornavn
  • Valider data: p.id > 0 – gyldig ID
  • Håndtere manglende data: NOT coalesce(p.locationIP, '10.x.x.x') STARTS WITH '10.x.x.x' – ble ikke koblet til fra lokalt nettverk
  • Kombiner betingelser: Bruk AND/OR med eksplisitte nullkontroller for kompleks logikk

Forsiktig!

Husk at betingelser som involverer nullverdier returnerer UNKNOWN, som filtrerer ut disse radene. Bruk eksplisitte IS NULL kontroller når du trenger null-inkluderende logikk.

ORDER BY uttalelse

Syntaks:

ORDER BY <expression> [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ],
         <expression> [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ], ...

Sortering på flere nivåer med beregnede uttrykk:

MATCH (p:Person)
RETURN *
ORDER BY p.firstName DESC,               -- Primary: by first name (Z-A)
         p.birthday ASC,                 -- Secondary: by age (oldest first)
         p.id DESC                       -- Tertiary: by ID (highest first)

Nullhåndtering i sortering:

MATCH (p:Person)
RETURN p.firstName, p.birthday
ORDER BY p.birthday DESC NULLS LAST, p.firstName ASC

Detaljer for sorteringsvirkemåte:

Forstå hvordan ORDER BY fungerer:

  • Spørringsmotoren evaluerer uttrykk for hver rad, og resultatene bestemmer radrekkefølgen.
  • Flere sorteringstaster oppretter hierarkisk rekkefølge (primær, sekundær, tertiær og så videre).
  • NULLS FIRST plasserer nullverdier før ikke-nullverdier. NULLS LAST plasserer dem etter ikke-nullverdier.
  • Nullplassering er uavhengig av sorteringsretning. Hvis du ikke spesifiserer nullorden, NULLS LAST er standard for både ASC og DESC.
  • ASC (stigende) er standardrekkefølgen, og du må eksplisitt angi DESC (synkende).
  • Du kan sortere etter beregnede verdier, ikke bare lagrede egenskaper.
Sorteringsspesifikasjon Resulterende rekkefølge
ASC Eller ASC NULLS LAST Ikke-nullverdier i stigende rekkefølge, etterfulgt av nullverdier.
ASC NULLS FIRST Nullverdier, etterfulgt av ikke-nullverdier i stigende rekkefølge.
DESC Eller DESC NULLS LAST Ikke-nullverdier i synkende rekkefølge, etterfulgt av nullverdier.
DESC NULLS FIRST Nullverdier, etterfulgt av ikke-nullverdier i synkende rekkefølge.

Forsiktig!

Bare den umiddelbart følgende setningen kan se sorteringsrekkefølgen som ORDER BY etableres. Derfor, ORDER BY etterfulgt av RETURN * , gir ikke et bestilt resultat.

Sammenligne:

MATCH (a:Person)-[r:knows]->(b:Person)
LET aName = a.firstName || ' ' || a.lastName
LET bName = b.firstName || ' ' || b.lastName
ORDER BY r.creationDate DESC
/* intermediary result _IS_ guaranteed to be ordered here */
RETURN aName, bName, r.creationDate AS since
/* final result _IS_ _NOT_ guaranteed to be ordered here  */

med:

MATCH (a:Person)-[r:knows]->(b:Person)
LET aName = a.firstName || ' ' || a.lastName
LET bName = b.firstName || ' ' || b.lastName
/* intermediary result _IS_ _NOT_ guaranteed to be ordered here */
RETURN aName, bName, r.creationDate AS since
ORDER BY r.creationDate DESC
/* final result _IS_ guaranteed to be ordered here              */

Denne forskjellen har umiddelbare konsekvenser for «Top-k»-spørringer: LIMIT må alltid følge setningen ORDER BY som etablerer den tiltenkte sorteringsrekkefølgen.

OFFSET og LIMIT setninger

Syntaks:

  OFFSET <offset> [ LIMIT <limit> ]
| LIMIT <limit>

Vanlige mønstre:

-- Basic top-N query
MATCH (p:Person)
RETURN *
ORDER BY p.id DESC
LIMIT 10                                 -- Top 10 by ID

Viktig!

Bruk alltid ORDER BY før OFFSET og LIMIT for å sikre konsekvent radrekkefølge på tvers av spørringer for forutsigbare pagineringsresultater.

RETURN: grunnleggende resultatprojeksjon

Syntaks:

RETURN [ DISTINCT ] <expression> [ AS <alias> ], <expression> [ AS <alias> ], ...
[ ORDER BY <expression> [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ], ... ]
[ OFFSET <offset> ]
[ LIMIT <limit> ]

Setningen RETURN produserer spørringens endelige utdata ved å angi hvilke data som vises i resultattabellen.

Grunnleggende utdata:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName || ' ' || p.lastName AS name, 
       p.birthday, 
       c.name

Bruke aliaser for klarhet:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName AS first_name, 
       p.lastName AS last_name,
       c.name AS company_name

Kombiner med sortering og topp-k:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName || ' ' || p.lastName AS name, 
       p.birthday AS birth_year, 
       c.name AS company
ORDER BY birth_year ASC
LIMIT 10

Dupliser håndtering ved hjelp av DISTINCT:

-- Remove duplicate combinations
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN DISTINCT p.gender, p.browserUsed, p.birthday AS birth_year
ORDER BY p.gender, p.browserUsed, birth_year

Kombiner med aggregasjon:

MATCH (p:Person)-[:workAt]->(c:Company)
RETURN count(DISTINCT p) AS employee_count

RETURN med GROUP BY: gruppert resultatprojeksjon

Syntaks:

RETURN [ DISTINCT ] <expression> [ AS <alias> ], <expression> [ AS <alias> ], ...
GROUP BY <variable>, <variable>, ...
[ ORDER BY <expression> [ ASC | DESC ], <expression> [ ASC | DESC ], ... ]
[ OFFSET <offset> ]
[ LIMIT <limit> ]

Brukes GROUP BY til å gruppere rader etter delte verdier og beregne mengdefunksjoner i hver gruppe.

Grunnleggende gruppering med aggregasjon:

MATCH (p:Person)-[:workAt]->(c:Company)
LET companyId = c.id, companyName = c.name
RETURN companyId,
       companyName,
       count(*) AS employeeCount,
       avg(p.birthday) AS avg_birth_year
GROUP BY companyId, companyName
ORDER BY employeeCount DESC

Gruppering med flere kolonner:

MATCH (p:Person)
LET gender = p.gender
LET browser = p.browserUsed
RETURN gender,
       browser,
       count(*) AS person_count,
       avg(p.birthday) AS avg_birth_year,
       min(p.creationDate) AS first_joined,
       max(p.id) AS highest_id
GROUP BY gender, browser
ORDER BY avg_birth_year DESC
LIMIT 10

Note

For horisontal aggregering over mønstre med variabel lengde, se Aggregerte funksjoner.

Verdier og verdityper

GQL-verdier inkluderer boolske, streng-, numerisk-, temporal-, liste-, node-, kant-, sti-, null- og ingenting-verdier. Typer kan nulles med mindre du spesifiserer NOT NULL. Eiendommer bruker et støttet delsett av det fullstendige spørringsverdisystemet.

RETURN 42 AS integerValue,
       'Alice' AS stringValue,
       TRUE AS booleanValue,
       [1, 2, 3] AS listValue

Sammenligninger med null evaluerer til UNKNOWN; bruk IS NULL og IS NOT NULL for nulltester. Numeriske operasjoner kan anvende implisitte konverteringer mellom kompatible numeriske typer.

Note

Ikke alle GQL-verdityper støttes i alle grafkontekster. For nåværende egenskaps- og spørringsbegrensninger, se Datatyper.

For bokstavelig syntaks, sammenligningsatferd, typekonverteringer og typehierarkiet, se GQL-verdier og verdityper.

Uttrykk

Uttrykk beregner, sammenligner, aggregerer og transformerer verdier. Vanlige former inkluderer egenskapsreferanser, aritmetiske og logiske operatorer, predikater, funksjonskall, enkle CASE uttrykk og delforespørsler:

MATCH (person:Person)
FILTER person.birthday < 19900101
RETURN person.firstName,
       CASE person.gender
         WHEN 'female' THEN 'F'
         WHEN 'male' THEN 'M'
         ELSE 'Other'
       END AS genderCode

GQL bruker treverdilogikk: Booleske uttrykk kan evaluere til TRUE, FALSE, eller UNKNOWN. A FILTER beholder kun rader hvor predikatet TRUEer .

Aggreger funksjoner som COUNT, SUM, AVG, , MINog MAX oppsummerer rader. Liste predikater som ALL, ANY, , NONEog SINGLE evaluere et predikat for listeelementer. Prosedyreform-underspørringer EXISTS tester om en nestelt spørring returnerer en rad.

For fullstendig operator-, predikat-, aggregat- og funksjonsatferd, se GQL-uttrykk, predikater og funksjoner. For eksempler på oppgaveorientert filtrering og gruppering, se Filter og aggregere grafdata.

Avanserte spørringsteknikker

Denne delen dekker avanserte mønstre og teknikker for å bygge komplekse, effektive grafspørringer. Disse mønstrene går utover grunnleggende uttrykksbruk for å hjelpe deg med å skrive kraftige analytiske spørringer.

Kompleks sammensetning med flere setninger

Viktig!

Graph støtter grunnleggende og fullstendig lineær setningssammensetning. , EXCEPTINTERSECT, og OTHERWISE set-operasjonene støttes ennå ikke. Hvis du vil ha mer informasjon, kan du se artikkelen om gjeldende begrensninger.

Å forstå hvordan du oppretter komplekse spørringer effektivt er avgjørende for avansert grafspørring.

UNION Og UNION ALL

Bruk UNION, UNION DISTINCT, eller UNION ALL for å kombinere resultater fra to eller flere lineære spørringsblokker:

<query block>
UNION [ DISTINCT | ALL ]
<query block>

-- Combine results from two separate pattern matches
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName AS name, c.name AS affiliation
UNION DISTINCT
MATCH (p:Person)-[:studyAt]->(u:University)
RETURN p.firstName AS name, u.name AS affiliation

Bare UNION tilsvarer UNION DISTINCT; begge fjerner dupliserte rader. UNION ALL beholder alle rader, inkludert duplikater.

Hver spørringsblokk må returnere det samme settet med kolonnenavn. Kolonnerekkefølgen kan variere mellom blokker, og datatypene må være kompatible.

NEXT

Bruk NEXT til å kjøre et nytt spørringstrinn mot tabellen som returneres av forrige trinn:

<query stage>
RETURN <columns>
NEXT
<query stage>

Følgende spørring finner ansatte og deres selskaper, og bruker deretter de returnerte ansattnodene i et annet mønstermatch:

MATCH (person:Person)-[:workAt]->(company:Company)
RETURN person, company.name AS companyName
NEXT
MATCH (person)-[:isLocatedIn]->(city:City)
RETURN person.firstName AS employee, companyName, city.name AS city

Kun kolonner returnert av det foregående stadiet er i omfanget etter NEXT. Du kan bruke flere NEXT separatorer for å bygge en lengre sekvens av spørringstrinn.

Begge trinn kan inneholde en union av spørringsblokker. En union evalueres innenfor sitt trinn før trinnets utgang krysser grensen NEXT . Hvis A, B, og C representerer spørringsblokker, grupperes A UNION B NEXT C som (A UNION B) NEXT C, mens A NEXT B UNION C grupper som A NEXT (B UNION C).

Betingelsessetninger

Bruk en betinget setning for å rute hver innkommende rad til den første grenen hvis predikat evaluerer til TRUE:

WHEN <predicate> THEN <linear query statement or { query statements }>
[ WHEN <predicate> THEN <linear query statement or { query statements }> ... ]
[ ELSE <linear query statement or { query statements }> ]

For å rute rader fra et foregående spørringsstadium, returner de nødvendige kolonnene og bruk NEXT før den betingede setningen:

MATCH (p:Person)
RETURN p.firstName AS name, p.birthday AS birthday
NEXT
WHEN birthday < 19800101u THEN
  RETURN name, 'Before 1980' AS era
WHEN birthday < 20000101u THEN
  RETURN name, '1980-1999' AS era
ELSE
  RETURN name, '2000 or later' AS era

Hvert WHEN predikat må være boolsk. Spørringsmotoren evaluerer predikatene i rekkefølge for hver inndatarad. Et predikat som evaluerer til FALSE eller UNKNOWN ikke velger sin gren. Etter at et predikat evaluerer til TRUE, vurderes ikke senere predikater og uvalgte greinlegemer. Hvis ingen predikat evaluerer til TRUE og det ikke finnes noe ELSE, returneres ikke inndataraden.

Predikater og grenlegemer kan referere til kolonner fra det foregående stadiet. En gren kan være én lineær setning, eller en nestet prosedyre innelukket i klammer. Bruk en nestet prosedyre når en gren trenger flere trinn eller setninger som CALL:

MATCH (p:Person)
RETURN p, p.firstName AS name
NEXT
WHEN p.gender = 'female' THEN {
  CALL {
    MATCH (p)-[:knows]->(friend:Person)
    RETURN count(*) AS friendCount
  }
  RETURN name, friendCount
}
ELSE
  RETURN name, 0u AS friendCount

Hver gren har sitt eget lokale omfang. Søskengrener ser ikke variabler opprettet av en annen gren, og kun kolonner fra den valgte grenens endelige RETURN fortsettelse etter den betingede setningen. Hver gren må returnere de samme kolonnenavnene, og tilsvarende resultattyper må være kompatible. Spørringsmotoren tvinger kompatible typer til en felles utdatatype. En returnert grenkolonne kan bruke samme navn som en innkommende kolonne; grenverdien erstatter den innkommende verdien i den betingede utdataen.

Betingede setninger er forskjellige fra CASE uttrykk. Graph støtter enkle CASE <expression> WHEN <value>, men ikke søkte CASE WHEN <predicate> uttrykk. For mer informasjon, se Betingede uttrykk.

Variabel omfang og avansert flytkontroll

Variabler kobler sammen data på tvers av spørringssetninger og aktiverer komplekse graf-traverseringer. Ved å forstå avanserte omfangsregler kan du skrive avanserte spørringer med flere setninger.

Variable bindings- og omfangsmønstre

-- Variables flow forward through subsequent statements 
MATCH (p:Person)                                    -- Bind p 
LET fullName = p.firstName || ' ' || p.lastName     -- Bind concatenation of p.firstName and p.lastName as fullName
FILTER fullName CONTAINS 'Smith'                    -- Filter for fullNames with “Smith” substring (p is still bound)
RETURN p.id, fullName                               -- Only return p.id and fullName (p is dropped from scope)

Variabel gjenbruk for sammenføyninger på tvers av setninger

-- Multi-statement joins using variable reuse
MATCH (p:Person)-[:workAt]->(:Company)          -- Find people with jobs
MATCH (p)-[:isLocatedIn]->(:City)               -- Same p: people with both job and residence
MATCH (p)-[:knows]->(friend:Person)             -- Same p: their social connections
RETURN *

Kritiske omfangsregler og begrensninger

-- ✅ Backward references work
MATCH (p:Person)
LET adult = p.birthday < 20061231  -- Can reference p from previous statement
RETURN *

-- ❌ Forward references don't work  
LET adult = p.birthday < 20061231  -- Error: p not yet defined
MATCH (p:Person)
RETURN *

-- ❌ Variables in same LET statement can't reference each other
MATCH (p:Person)
LET name = p.firstName || ' ' || p.lastName,
    greeting = 'Hello, ' || name     -- Error: name not visible yet
RETURN *

-- ✅ Use separate statements for dependent variables
MATCH (p:Person)
LET name = p.firstName || ' ' || p.lastName
LET greeting = 'Hello, ' || name     -- Works: name now available
RETURN *

Variabel synlighet i komplekse spørringer

-- Variables remain visible until overridden or query ends
MATCH (p:Person)                     -- p available from here
LET gender = p.gender                -- gender available from here  
MATCH (p)-[:knows]->(e:Person)       -- p still refers to original person
                                     -- e is a new variable for the friend
RETURN p.firstName AS manager, e.firstName AS friend, gender

Forsiktig!

Variabler i samme setning kan ikke referere til hverandre, bortsett fra i grafmønstre. Bruk separate setninger for oppretting av avhengig variabel.

Aggregerte rader og sti-elementer

GQL støtter to aggregeringskontekster:

  • Vertikal aggregering oppsummerer inngangsrader, eventuelt delt opp etter GROUP BY variabler.
  • Horisontal aggregering oppsummerer en gruppeliste avgrenset av et kantmønster med variabel lengde innenfor én matchet sti.
MATCH (person:Person)-[:workAt]->(company:Company)
LET companyId = company.id, companyName = company.name
RETURN companyId, companyName, count(*) AS employeeCount
GROUP BY companyId, companyName

MATCH (:Person)-[connections:knows]->{1,4}(:Person)
RETURN count(connections) AS pathLength

For grupperte spørringer, aggregatspesifikke filtre, samlingsaggregater og betinget ruting, se Filter og aggregert grafdata. For fullstendige aggregerte resultatregler, se Aggregerte funksjoner.

Håndter nullpunkter og spørringsfeil

Bruk eksplisitte nulltester når manglende verdier trenger særskilt håndtering:

MATCH (person:Person)
FILTER person.browserUsed IS NULL
RETURN person.firstName

En sammenligning med null evaluerer til UNKNOWN, som a FILTER ikke beholder. Bruk coalesce() når du trenger en reserveverdi.

Spørringsresultater inkluderer statusinformasjon for suksess, advarsler, datafrie tilstander, brukerkorrigerbare feil og systemfeil. Bruk den offentlige statuskoden for bred kontrollflyt og den kanoniske GQLSTATUS-diagnostikken for en spesifikk tilstand. Se Execution outcomes and results og GQL-statuskodereferansen.

Reserverte ord

GQL forbeholder seg bestemte nøkkelord som du ikke kan bruke som identifikatorer som variabler, egenskapsnavn eller etikettnavn. Se referansen for reserverte ord for GQL for den fullstendige listen.

Hvis du trenger å bruke reserverte ord som identifikatorer, kan du unnslippe dem med backticks: `match`, `return`.

Hvis du vil unngå å fjerne reserverte ord, kan du bruke denne navnekonvensjonen:

  • For enkeltordidentifikatorer tilføyer du et understrekingstegn: :Product_
  • Bruk camelCase eller PascalCase for flerordsidentifikatorer: :MyEntity, , :hasAttributetextColor

Neste trinn

Beslektet innhold

  • Last updated on