GQL-sprogvejledning til graph i Microsoft Fabric

GQL (Graph Query Language) er det ISO-standardiserede forespørgselssprog for grafdatabaser. Brug GQL til at forespørge, analysere og arbejde effektivt med grafdata med graph i Microsoft Fabric.

Den samme ISO-arbejdsgruppe, der standardiserer SQL, udvikler GQL. Derfor deler GQL mange begreber med SQL, herunder udtryk, prædikater og datatyper. Hvis du har SQL-erfaring, kan du anvende meget af denne viden på GQL.

Denne artikel er den komplette guide til GQL i graf. Den forklarer, hvordan sproget hænger sammen, og linker til fokuserede referencer for fuldstændige syntaks- og typedetaljer. Den dækker:

  • Grundlæggende begreber: Grafér datastrukturer, mønstre og grundlæggende forespørgsler
  • Væsentlige udsagn:MATCH , FILTER, , LET, WHEN, ORDER BY, LIMIT, ogRETURN
  • Datatyper og udtryk: Værdityper, operatorer og indbyggede funktioner
  • Avancerede teknikker: Sammensætning af flere udsagn, variabeludformning og aggregeringsstrategier

Notat

Den officielle internationale standard for GQL er ISO/IEC 39075 Information Technology - Database Languages - GQL.

Hvis du leder efter opgaveorienteret vejledning i stedet for en sproggennemgang, så se vejledningerne til hvordan:

Brug de fokuserede referenceartikler, når du har brug for fuldstændige oplysninger:

Nødvendige oplysninger Definitiv artikel
Syntaks i et hurtigt blik GQL hurtigreference
Node-, kant-, sti- og mønsterkompositionssyntaks GQL-grafmønstre
Operatorer, prædikater og funktioner GQL-udtryk, prædikater og funktioner
Bogstavelig syntaks, værdiadfærd og typekonverteringer GQL-værdier og værdityper
Graftypedefinitioner og begrænsninger GQL-graftyper
Nuværende ISO GQL-funktionsdækning GQL-standardkonformitet
Nuværende Fabric-specifikke begrænsninger og begrænsninger Nuværende begrænsninger

Forudsætninger

Før du starter, skal du sørge for, at du er fortrolig med disse begreber:

  • Basic-forståelse af databaser – Erfaring med ethvert databasesystem, f.eks. relationelt (SQL), NoSQL eller graf, er nyttigt.
  • Grafbegreber – Forståelse af noder, kanter og relationer i forbundne data.
  • Grundlæggende spørgsmål – Viden om grundlæggende forespørgselsbegreber, f.eks. filtrering, sortering og aggregering.

Anbefalet baggrund:

  • Erfaring med SQL- eller openCypher-sprog gør det nemmere at lære GQL-syntaks (de er GQL's rødder).
  • Kendskab til datamodellering hjælper med diagramskemadesign.
  • Forståelse af din specifikke use case til grafdata.

Det har du brug for:

  • Adgang til et grafarbejdsområde med forespørgselsfunktioner.
  • Eksempeldata eller villighed til at arbejde med vores eksempler på sociale netværk.
  • Grundlæggende teksteditor til skrivning af forespørgsler.

Tips

Hvis du er ny bruger af grafdatabaser, skal du starte med oversigten over grafdatamodeller , før du fortsætter med denne vejledning.

Hvad gør GQL speciel

GQL er designet specifikt til grafdata, så dens syntaks udtrykker direkte, hvordan enheder er forbundet. Hvor SQL ofte udtrykker relationer gennem joins mellem tabeller, bruger GQL grafmønstre, der ligner diagrammer af dataene.

For eksempel finder følgende forespørgsel par af personer, der kender hinanden 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ønstret (person:Person)-[:knows]-(friend:Person) viser, at relationsstrukturen matcher. Variabler binder de to personer, så forespørgslen kan filtrere og returnere deres egenskaber.

Grundlæggende om GQL

Disse begreber udgør grundlaget for GQL:

  • Grafer indeholder noder og kanter med etiketter og egenskaber.
  • Graftyper definerer formelt nodetyper, kanttyper og begrænsninger, der er tilladt i en graf.
  • Forespørgsler bruger sætninger som MATCH, FILTER, og RETURN til at behandle data og producere resultater.
  • Mønstre beskriver grafstrukturerne, der matcher.
  • Udtryk beregner, transformerer og sammenligner værdier.
  • Prædikater er booleske udtryk, der bruges til at teste betingelser.
  • Værdityper definerer de typer værdier, som forespørgsler kan behandle, og grafegenskaber kan gemme.

Forstå grafdata

For at arbejde med GQL skal du forstå den mærkede egenskabsgrafstruktur, som sproget forespørger.

Noder og kanter: byggestenene

En mærket egenskabsgraf indeholder to slags grafelementer:

  • Noder repræsenterer typisk enheder, såsom personer, organisationer, opslag eller produkter.
  • Kanter repræsenterer forbindelser mellem noder, såsom at en person kender en anden person eller arbejder i en virksomhed.

Hvert grafelement har en intern identitet, en eller flere etiketter og et sæt egenskaber. Etiketter klassificerer elementer som Person eller knows. Egenskaber er navn-værdi-par, såsom firstName: 'Alice' eller birthday: 19730108u. I Graph har en kant altid præcis én label.

Hver kant forbinder præcis to noder: en oprindelse og et mål. Kantretningen er en del af grafstrukturen. For eksempel kan en workAt kant forbinde en Person oprindelse til et Company mål.

Notat

Graph understøtter i øjeblikket ikke oprettelse af uorienterede kanter. Du kan forespørge en eksisterende rettet kant i begge retninger ved at bruge et vilkårligt rettet kantmønster såsom -[:knows]-.

Grafer er veldannede: hver kant forbinder to noder, der findes i samme graf.

Grafmodeller og graftyper

En Fabric-grafmodel definerer nodetyper, kanttyper, egenskaber, kildekortlægninger og nøgler, der er tilgængelige i en graf. Den specificerer, hvilke rækker i kildetabellen der bliver til noder og kanter, og hvordan disse elementer forbindes. For vejledning i modellering, se Design et grafskema.

GQL-standarden bruger en graftype til formelt at beskrive tilladte nodetyper, kanttyper, egenskaber og begrænsninger. Graftyper er sprogniveau-modstykket til strukturen, som repræsenteres af en Fabric-grafmodel, men Graph accepterer i øjeblikket ikke GQL-graftype-deklarationer direkte. For den formelle syntaks og begreber, se GQL graftyper.

Eksempelgraf brugt i denne guide

Eksempler bruger det sociale netværks eksempeldatasæt, som inkluderer personer, steder, organisationer, beskeder, tags og de kanter, der forbinder dem.

Eksempelgrafen forbinder disse områder:

  • Folk kender andre, arbejder i virksomheder og studerer på universiteter.
  • Byer, lande eller regioner og kontinenter danner et geografisk hierarki.
  • Fora indeholder indlæg, og folk opretter opslag og kommentarer.
  • Tags kategoriserer indhold og repræsenterer folks interesser.

Diagram, der viser skemaet for det sociale netværk.

For den komplette eksempelstruktur, se eksemplet på det sociale netværksskema. For generelle grafbegreber, se Mærkede egenskabsgrafer.

Dine første GQL-forespørgsler

Nu, hvor du forstår grundlæggende grafer, kan vi se, hvordan du forespørger grafdata ved hjælp af GQL. Disse eksempler bygges fra enkle til komplekse og viser dig, hvordan GQL's tilgang gør grafforespørgsler intuitive og effektive.

Start enkelt: Find alle personer

Begynd med den mest grundlæggende forespørgsel, der er mulig. Find navnene (fornavn, efternavn) på alle personerne:Person i diagrammet.

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

Denne forespørgsel kører på følgende måde:

  1. MATCH finder alle noder, der er navngivet Person.
  2. RETURN viser deres for- og efternavne.

Tilføj filtrering: Find bestemte personer

Find nu personer med specifikke egenskaber. I dette tilfælde skal du finde alle med navnet Alice og vise deres navne og fødselsdage.

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

Denne forespørgsel kører på følgende måde:

  1. MATCH finder alle noder (p) med navnet Person.
  2. FILTER noder (p), hvis fornavn er Alice.
  3. RETURN viser deres fornavn, efternavn og fødselsdag.

Grundlæggende forespørgselsstruktur

Grundlæggende GQL-forespørgsler følger alle et ensartet mønster: en sekvens af sætninger, der arbejder sammen om at finde, filtrere og returnere data. De fleste forespørgsler starter med MATCH at finde mønstre i grafen og slutter med RETURN at specificere outputtet.

Her er en simpel forespørgsel, der finder par af personer, der kender hinanden og deler samme fødselsdag, og derefter returnerer det samlede antal af disse vennepar.

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

Denne forespørgsel kører på følgende måde:

  1. MATCH finder alle nodepar Person , der kender hinanden.
  2. FILTER holder kun de par, hvor begge mennesker har samme fødselsdag.
  3. RETURN tæller, hvor mange sådanne vennepar der findes.

Tips

Du kan også filtrere direkte i et mønster ved at tilføje en WHERE klausul. For eksempel matcher MATCH (n:Person WHERE n.birthday < 19900101) kun Person noder med en birthday værdi før 1990.

GQL understøtter linjekommentarer i C-format // , kommentarer i SQL-stil -- og blokkommentarer i C-format /* */ .

Almindelige udsagn

  • MATCH: Identificerer grafmønsteret, der skal søges efter—det er her, du definerer strukturen af de data, du er interesseret i.
  • LET: Tildeler nye variable eller beregnede værdier baseret på matchede data – tilføjer afledte kolonner til resultatet.
  • FOR: Udvider en liste til rækker med en valgfri nulbaseret offset eller ét-baseret ordinal position.
  • CALL: Kører en inline underforespørgsel for hver inputrække og tilføjer de kolonner, som underforespørgslen returnerer.
  • FILTER: Indsnævrer resultaterne ved at anvende betingelser—fjerner rækker, der ikke opfylder kriterierne.
  • ORDER BY: Sorterer de filtrerede data—hjælper med at organisere outputtet baseret på et eller flere felter.
  • OFFSET og LIMIT: Begræns antallet af returnerede rækker – nyttigt til paginering eller top-k forespørgsler.
  • RETURN: Specificerer det endelige output—definerer, hvilke data der skal inkluderes i resultatsættet, og udfører aggregering.
  • NEXT: Starter en ny forespørgselsfase ved at bruge de kolonner, der blev returneret fra det forrige trin.

Sådan arbejder sætninger sammen

GQL-udsagn danner en pipeline, hvor hver sætning behandler outputtet fra den foregående. Denne sekventielle eksekvering gør forespørgsler nemme at læse og fejlfinde, fordi eksekveringsrækkefølgen matcher læserækkefølgen.

Nøglepunkter:

  • Sætninger udføres effektivt sekventielt.
  • Hver sætning transformerer data og sender dem videre til den næste.
  • Denne proces opretter et klart, forudsigeligt dataflow, der forenkler komplekse forespørgsler.
  • NEXT starter en ny forespørgselsfase. Kun kolonner, der projiceres af den foregående RETURN sætning, er tilgængelige i næste fase.
  • UNION, UNION DISTINCT, og UNION ALL kombinerer resultaterne af komplette forespørgselsblokke.

Notat

Udsagn har en defineret logisk rækkefølge. Skriv forespørgsler i henhold til denne datastrøm i stedet for at stole på en bestemt fysisk eksekveringsstrategi.

Eksempel på sætningskomposition

Følgende GQL-forespørgsel finder de første 10 personer, der arbejder i virksomheder med "Air" i deres navn, sorterer dem efter fuldt navn og returnerer deres fulde navn sammen med navnet på deres virksomheder.

-- 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 forespørgsel kører på følgende måde:

  1. MATCH finder folk, der arbejder i virksomheder.
  2. LET opretter fulde navne ved at kombinere for- og familienavne.
  3. FILTER holder kun medarbejdere i virksomheder med "Air" i firmanavnet.
  4. ORDER BY sorterer efter fulde navn.
  5. LIMIT tager de første 10 resultater.
  6. RETURN returnerer fulde navne og firmanavne.

Variabler forbinder dine data

Variabler, f.eks p. , cog fullName i de forrige eksempler, indeholder data mellem sætninger. Når du genbruger et variabelnavn, sikrer GQL automatisk, at det refererer til de samme data, hvilket skaber effektive joinbetingelser. Variabler kaldes nogle gange også bindingsvariabler.

Du kan kategorisere variabler på forskellige måder:

Efter bindingskilde:

  • Mønstervariabler – bundet af matchende grafmønstre
  • Almindelige variabler – bundet af andre sprogkonstruktioner

Variabeltyper for mønster:

  • Elementvariabler – bind til referenceværdier for grafelementer
    • Nodevariabler – bind til individuelle noder
    • Kantvariabler – bind til individuelle kanter
  • Stivariabler – bind til stiværdier, der repræsenterer tilsvarende stier

Efter referencegrad:

  • Singleton-variabler – bind til individuelle elementreferenceværdier fra mønstre
  • Gruppevariabler - bind til lister over elementreferenceværdier fra mønstre med variabel længde. For detaljer, se Samlede funktioner.

Udførelsesresultater og -resultater

Når du kører en forespørgsel, får du et udførelsesresultat tilbage, der består af:

  • Et resultat, normalt en resultattabel med dataene fra din RETURN kontoudtog.
  • Statusoplysninger , der viser, om forespørgslen lykkedes eller ej.

Resultattabeller

Resultattabellen – hvis den findes – er det faktiske resultat af udførelsen af forespørgslen.

En resultattabel indeholder oplysninger om navnet og typen af kolonnerne, en foretrukken sekvens af kolonnenavne, der skal bruges til at vise resultater, om tabellen er sorteret, og selve de faktiske rækker.

Notat

Hvis udførelsen mislykkes, medtages der ingen resultattabel i udførelsesresultatet.

Udeladte resultater

GQL definerer også et udeladt resultat for udsagn, der aldrig producerer rækker, uafhængigt af dataene eller evalueringsresultatet. Et udeladt resultat har statuskode 00001for succesfuld fuldførelse .

Et udeladt resultat adskiller sig fra en tom resultattabel. En tom tabel betyder, at en rækkeproducerende forespørgsel blev evalueret, men ikke producerede nogen rækker. Query API'en kan repræsentere et udeladt resultat med resultattype NOTHING.

Grafreserver udeladte resultater til understøttelse af fremtidige datadefinitionsprog (DDL) og datamanipulationssprog (DML) sætninger. Aktuelle forespørgselsudsagn giver tabelresultater, inklusive tomme tabeller.

Statusoplysninger

Under udførelse af forespørgsler registrerer processen forskellige bemærkelsesværdige betingelser, f.eks. fejl eller advarsler. Hver betingelse registreres af et statusobjekt i statusoplysningerne for udførelsesresultatet.

Statusoplysningerne består af et primært statusobjekt og en (muligvis tom) liste over andre statusobjekter. Det primære statusobjekt findes altid og angiver, om udførelsen af forespørgslen lykkedes eller mislykkedes.

Hvert statusobjekt indeholder en fem-tegns alfanumerisk kode og en beskrivelse af den registrerede tilstand.

Query API'en bruger følgende primære statuskoder:

API-statuskode Betydning
00000 Vellykket gennemførelse med mindst én række.
00001 Vellykket gennemførelse med udeladt resultat. Reserveret til fremtidig DDL- og DML-support.
01000 En advarsel eller informationsbetingelse.
02000 Der er i øjeblikket ingen rækker tilgængelige fra en rækkeproducerende forespørgsel.
42000 En brugerkorrigerbar forespørgselsfejl.
50000 En system- eller ikke-klassificeret fejl.

API'et bevarer den kanoniske GQLSTATUS, som forespørgselsmotoren rapporterer i _graphaneGqlStatus medlemmet af diagnoseposten. For eksempel bruger numerisk overflow kanonisk GQLSTATUS 22003, mens division med nul bruger 22012; begge repræsenteres ved 42000 i det offentlige status.code felt.

Vigtigt

I applikationskode, brug status.code for bred succes og fejlhåndtering. Brug den kanoniske GQLSTATUS-diagnose, når du skal skelne mellem en specifik forespørgselsbetingelse. Test ikke beskrivelsesteksten, for den kan variere.

Derudover kan statusobjekter indeholde et underliggende årsagsstatusobjekt og en diagnosticeringspost med yderligere oplysninger, der karakteriserer den registrerede betingelse.

Se GQL-statuskodernes reference

Vigtige begreber og sætninger

I dette afsnit beskrives de kernekomponenter, du skal bruge for at skrive effektive GQL-forespørgsler. Hvert koncept bygger på praktiske færdigheder inden for forespørgselsskrivning.

Grafmønstre: find struktur

Et grafmønster beskriver de noder, kanter og stier, der skal matches. Bind variabler, når senere udsagn skal referere til matchede elementer:

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

Placer et prædikat i linjen, når det definerer, hvilken node eller kant der kan deltage i mønsteret:

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

Genanvend en variabel, så to mønsterpositioner kan binde det samme element. Adskil mønstre med kommaer for at danne større grafstrukturer. Brug en kvantor, såsom {1,4} til at gentage et kantmønster og matche baner med variabel længde.

Sti-tilstande styrer elementets genbrug inden for en sti:

Stitilstand Adfærd
WALK Tillader gentagne noder og kanter. Denne tilstand er standard.
TRAIL Forhindrer gentagne kanter.
SIMPLE Forhindrer gentagne noder undtagen for en delt første og sidste node.
ACYCLIC Forhindrer alle gentagne noder.

Et sti-søgepræfiks styrer, hvilke matchende stier der returneres. ALL er standarden. ANY SHORTEST returnerer én korteste vej for hvert kilde-destinationspar:

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

Inline-prædikater begrænser sti-berettigelse før stivalg. Sætningsniveau MATCH ... WHERE - og senere FILTER operationer er postfiltre. Denne sondring kan ændre ANY SHORTEST resultaterne.

For definitiv semantik for node-, kant-, sti-, sammensætnings-, kvantor- og prædikatplacerings-semantik, se GQL-grafmønstre. For nuværende stibegrænsninger, se Nuværende begrænsninger.

Kernesætninger

GQL indeholder specifikke sætningstyper, der arbejder sammen om at behandle dine grafdata trin for trin. Det er vigtigt at forstå disse udsagn for at oprette effektive forespørgsler.

MATCH erklæring

Syntaks:

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

Sætningen MATCH tager inputdata og finder grafmønstre. Den joinforbinder inputvariabler med mønstervariabler og output alle matchede kombinationer.

Input- og outputvariabler:

-- 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å sætningsniveau ved hjælp af WHERE:

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

Du kan efterfiltrer alle forekomster ved hjælp WHEREaf . Denne fremgangsmåde undgår en separat FILTER sætning. Med et sti-søgepræfiks som ANY SHORTEST, gælder sætningsniveauet WHERE efter stivalg. Inline-prædikater begrænser i stedet, hvilke stier der er egnede til udvælgelse. For mere information, se Place-prædikater før eller efter stivalg.

Sammenføjning ved hjælp af inputvariabler:

Når MATCH ikke er den første sætning, joinforbinder den inputdata med mønsterforekomster:

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

Vigtigt

Graf understøtter grundlæggende og fuld lineær sætningssammensætning, inklusive NEXT. Du kan også kombinere forespørgselsblokke med UNION, UNION DISTINCT, og UNION ALL. , EXCEPTINTERSECT, og OTHERWISE mængdeoperationerne understøttes endnu ikke. Du kan få flere oplysninger i artiklen om aktuelle begrænsninger.

Funktionsmåder for nøgletilføjelser:

Sådan MATCH håndterer du datatilføjning:

  • Variabel lighed: Inputvariabler joinforbinder med mønstervariabler ved hjælp af lighedsmatch
  • Indre joinforbindelse: Inputrækker uden mønsterforekomster kasseres. Bruges OPTIONAL MATCH til venstre-ydre-join-funktionsmåde.
  • Filtreringsrækkefølge: Sætningsniveau-filtre WHERE efter mønstergenkendelse og stivalg er gennemført
  • Mønsterkomposition: Delte variable begrænser mønstre til det samme element. Usammenhængende mønstre danner et kartesisk produkt.

Vigtigt

Et usammenhængende mønster er gyldigt, men dets kartesiske produkt kan skabe mange rækker. Brug delte variabler, når mønstrene skal referere til de samme grafelementer.

Sammensæt 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 erklæring

Syntaks:

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

OPTIONAL MATCH fungerer som MATCH , men bruger semantik med venstre ydre joinforbindelse. Hvis mønsteret ikke finder et match for en inputrække, bevarer forespørgslen rækken med NULL værdier for variabler, der ikke stemmer overens, i stedet for at kassere 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, der ikke arbejder i en virksomhed, vises stadig i resultaterne med NULL for company_name.

Tips

Bruges OPTIONAL MATCH , når du vil medtage objekter, der muligvis ikke har en bestemt relation, på samme måde som en SQL LEFT JOIN.

LET erklæring

Syntaks:

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

Sætningen LET opretter beregnede variabler og muliggør datatransformation i din forespørgselspipeline.

Oprettelse af grundlæggende 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

Nøglefunktioner:

  • Forespørgselsprogrammet evaluerer udtryk for hver inputrække.
  • Resultaterne bliver til nye kolonner i outputtabellen.
  • Variabler kan kun referere til eksisterende variabler fra tidligere sætninger.
  • Flere tildelinger i én LET sætning bruger samme inputscope, så en assignment kan ikke referere til en anden assignment fra den sætning.

FOR erklæring

Syntaks:

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

Udsagnet FOR udvider en liste til rækker. For hver inputrække udsendes én outputrække for hvert listeelement og binder dette element til den angivne variabel. Andre variable fra inputrækken forbliver tilgængelige.

WITH OFFSET Brug til at binde et nulbaseret indeks, eller brug WITH ORDINALITY til at binde en en-baseret position.

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

Denne forespørgsel returnerer én række for hver by. Værdierne position er 1, 2, og 3. Hvis du erstatter WITH ORDINALITY position med WITH OFFSET position, er 0værdierne , 1, og 2.

Kildeudtrykket skal evaluere til en liste. En ikke-listeværdi får forespørgslen til at fejle.

CALL erklæring

Brug CALL til at køre en inline underforespørgsel for hver input-række:

CALL {
  <query statements>
  RETURN <columns>
}

Variable, der allerede er inden for scope, er implicit tilgængelige inde i delforespørgslen. Af de variable, der oprettes inde i underforespørgslen, bliver kun kolonner fra dens endelige RETURN sætning tilgængelige udenfor. Variable, der oprettes inde i underforespørgslen, men ikke returneres, forbliver lokale.

Følgende korrelerede delforespørgsel beregner antallet af arbejdsgivere 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 almindelig CALL fungerer som en afhængig indre join. Den producerer én outputrække for hver række, der returneres af underforespørgslen. Hvis underforespørgslen ikke returnerer nogen rækker, returneres den tilsvarende ydre række ikke. Hvis den returnerer flere rækker, vises den yderste række én gang for hver underforespørgselsrække.

Det foregående count(*) eksempel returnerer altid én underforespørgselsrække, fordi det bruger en ugrupperet aggregation. En person uden en matchende arbejdsgiver har derfor en employerCount af 0.

Brug OPTIONAL CALL som en afhængig venstre-join. Når underforespørgslen ikke returnerer nogen rækker, bevarer den én ydre række og sætter de returnerede underforespørgselskolonner til .NULL Når underforespørgslen returnerer flere rækker, producerer den én outputrække for hver underforespørgselsrække.

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

Du kan indlejre inline CALL subforespørgsler. En indlejret underforespørgsel kan referere til variabler fra sine omsluttende forespørgselsområder.

Vigtigt

Afslut hver inline-krop CALL med RETURN. Graph understøtter ikke navngivne procedurekald eller eksplicitte variabelimportlister såsom CALL (p) { ... }.

FILTER erklæring

Syntaks:

FILTER [ WHERE ] <predicate>

Sætningen FILTER giver præcis kontrol over, hvilke data der overføres via din forespørgselspipeline.

Grundlæggende 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 *

Filtreringsmønstre, der er null-opmærksomme:

Brug disse mønstre til at håndtere null-værdier sikkert:

  • Kontrollér, om der er værdier: p.firstName IS NOT NULL - har et fornavn
  • Valider data: p.id > 0 - gyldigt id
  • Håndter manglende data: NOT coalesce(p.locationIP, '10.x.x.x') STARTS WITH '10.x.x.x' - der blev ikke oprettet forbindelse fra det lokale netværk
  • Kombiner betingelser: Bruges AND/OR sammen med eksplicit null-kontrol for kompleks logik

Advarsel

Husk, at betingelser, der involverer null-værdier, returnerer UNKNOWN, som filtrerer disse rækker ud. Brug eksplicitte IS NULL kontroller, når du har brug for logik, der omfatter null.

ORDER BY erklæring

Syntaks:

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

Sortering på flere niveauer med beregnede udtryk:

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)

Håndtering af Null i sortering:

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

Oplysninger om funktionsmåde for sortering:

Om, hvordan ORDER BY fungerer:

  • Forespørgselsprogrammet evaluerer udtryk for hver række, hvorefter resultaterne bestemmer rækkerækkefølgen.
  • Flere sorteringsnøgler opretter hierarkisk rækkefølge (primær, sekundær, tertiær osv.).
  • NULLS FIRST placerer nullværdier før ikke-nulværdier. NULLS LAST placerer dem efter ikke-nulværdier.
  • Nullplacering er uafhængig af sorteringsretningen. Hvis du ikke specificerer nullorden, NULLS LAST er standarden for både ASC og DESC.
  • ASC (stigende) er standardrækkefølgen, og du skal eksplicit angive DESC (faldende).
  • Du kan sortere efter beregnede værdier og ikke kun gemte egenskaber.
Sort-specifikation Resulterende orden
ASC eller ASC NULLS LAST Ikke-nulværdier i stigende rækkefølge, efterfulgt af nulværdier.
ASC NULLS FIRST Nulværdier, efterfulgt af ikke-nulværdier i stigende rækkefølge.
DESC eller DESC NULLS LAST Ikke-nulværdier i faldende rækkefølge, efterfulgt af nulværdier.
DESC NULLS FIRST Nullværdier, efterfulgt af ikke-nulværdier i faldende rækkefølge.

Advarsel

Det er kun den umiddelbart følgende sætning, der kan se den sorteringsrækkefølge, der ORDER BY fastlægges. ORDER BY Efterfulgt af RETURN * resulterer derfor ikke i et sorteret 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 forskel har øjeblikkelige konsekvenser for "Top-k"-forespørgsler: LIMIT Skal altid følge den ORDER BY sætning, der fastlægger den tilsigtede sorteringsrækkefølge.

OFFSET og LIMIT -sætninger

Syntaks:

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

Almindelige mønstre:

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

Vigtigt

Hvis du vil have forudsigelige sideinddelingsresultater, skal du altid bruge ORDER BY før OFFSET og LIMIT sikre ensartet rækkerækkefølge på tværs af forespørgsler.

RETURN: basisresultatprojektion

Syntaks:

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

Sætningen RETURN producerer forespørgslens endelige output ved at angive, hvilke data der vises i resultattabellen.

Grundlæggende output:

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

Brug af aliasser til klarhed:

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 top-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

Dupliker håndtering ved hjælp af 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 sammenlægning:

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

RETURN med GROUP BY: grupperet resultatprojektion

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> ]

Bruges GROUP BY til at gruppere rækker efter delte værdier og beregne aggregeringsfunktioner i hver gruppe.

Grundlæggende gruppering med sammenlægning:

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

Notat

For horisontal aggregering over mønstre med variabel længde, se Aggregerede funktioner.

Værdier og værdityper

GQL-værdier inkluderer Booleske, streng-, numeriske, temporal-, liste-, node-, kant-, sti-, null- og nothing-værdier. Typer kan annulleres, medmindre du specificerer NOT NULL. Egenskaber bruger et understøttet delmængde af det fulde forespørgselsværdisystem.

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

Sammenligninger med null evaluerer til UNKNOWN; brug IS NULL og IS NOT NULL for nulltests. Numeriske operationer kan anvende implicitte konverteringer mellem kompatible numeriske typer.

Notat

Ikke alle GQL-værdityper understøttes i alle grafkontekster. For nuværende egenskaber og forespørgselsbegrænsninger, se Datatyper.

For litteral syntaks, sammenligningsadfærd, typekonverteringer og typehierarkiet, se GQL-værdier og værdityper.

Udtryk

Udtryk beregner, sammenligner, aggregerer og transformerer værdier. Almindelige former omfatter egenskabsreferencer, aritmetiske og logiske operatorer, prædikater, funktionskald, simple CASE udtryk og delforespørgsler:

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 bruger tre-værdi logik: Booleske udtryk kan evaluere til TRUE, FALSE, eller UNKNOWN. A FILTER beholder kun rækker, hvor dens prædikat er TRUE.

Aggregér funktioner som COUNT, SUM, AVG, , MINog MAX opsummerer rækker. Listprædikater såsom ALL, ANY, NONE, og SINGLE evaluerer et prædikat for listeelementer. Procedureform-underforespørgsler EXISTS tester, om en indlejret forespørgsel returnerer en række.

For komplet operator-, prædikat-, aggregat- og funktionsadfærd, se GQL-udtryk, prædikater og funktioner. For eksempler på opgaveorienteret filtrering og gruppering, se Filter og aggreger grafdata.

Avancerede forespørgselsteknikker

I dette afsnit beskrives avancerede mønstre og teknikker til oprettelse af komplekse, effektive grafforespørgsler. Disse mønstre går ud over grundlæggende brug af sætningen for at hjælpe dig med at oprette effektive analyseforespørgsler.

Kompleks multistatementkomposition

Vigtigt

Graph understøtter grundlæggende og fuld lineær sætningskomposition. , EXCEPTINTERSECT, og OTHERWISE mængdeoperationerne understøttes endnu ikke. Du kan få flere oplysninger i artiklen om aktuelle begrænsninger.

Det er afgørende for avanceret grafforespørgsler, hvordan du opretter komplekse forespørgsler effektivt.

UNION Og UNION ALL

Brug UNION, UNION DISTINCT, eller UNION ALL til at kombinere resultater fra to eller flere lineære forespørgselsblokke:

<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 svarer til UNION DISTINCT; begge fjerner dubletter rækker. UNION ALL bevarer alle rækker, herunder dubletter.

Hver forespørgselsblok skal returnere det samme sæt kolonnenavne. Kolonnerækkefølgen kan variere mellem blokke, og datatyperne skal være kompatible.

NEXT

Brug NEXT til at køre et andet forespørgselstrin mod den tabel, der returneres af det foregående trin:

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

Følgende forespørgsel finder medarbejdere og deres virksomheder og bruger derefter de returnerede medarbejdernoder i et andet 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, der returneres af det foregående trin, er i omfanget efter NEXT. Du kan bruge flere NEXT separatorer til at bygge en længere sekvens af forespørgselsfaser.

Begge faser kan indeholde en union af forespørgselsblokke. En union evalueres inden for sit trin, før trinnets output krydser grænsen NEXT . Hvis A, , og C repræsenterer forespørgselsblokke, grupperes A UNION B NEXT C som (A UNION B) NEXT C, mens A NEXT B UNION C grupperer som A NEXT (B UNION C)B.

Betingelsessætninger

Brug en betinget sætning til at rute hver indkommende række til den første gren, hvis prædikat 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 at rute rækker fra et forudgående forespørgselstrin, returner du de nødvendige kolonner og brug NEXT før den betingede sætning:

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 prædikat skal være booleskt. Forespørgselsmotoren evaluerer prædikaterne i rækkefølge for hver inputrække. Et prædikat, der evaluerer til FALSE eller UNKNOWN ikke vælger sin gren. Efter at et prædikat evaluerer til TRUE, vurderes senere prædikater og ikke-udvalgte forgreningslegemer ikke. Hvis intet prædikat evaluerer til TRUE og der ikke er noget ELSE, returneres inputrækken ikke.

Prædikater og forgreningslegemer kan referere til kolonner fra det foregående trin. En gren kan være én lineær sætning eller en indlejret procedure indkapslet i klammer. Brug en indlejret procedure, når en gren har brug for flere faser eller sætninger så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 sit eget lokale område. Søskendegrene ser ikke variabler oprettet af en anden gren, og kun kolonner fra den valgte grens endelige RETURN fortsættelse efter den betingede sætning. Hver gren skal returnere de samme kolonnenavne, og tilsvarende resultattyper skal være kompatible. Forespørgselsmotoren tvinger kompatible typer til en fælles outputtype. En returneret grenkolonne kan bruge samme navn som en indkommende kolonne; grenværdien erstatter den indkommende værdi i det betingede output.

Betingede udsagn adskiller sig fra CASE udtryk. Graph understøtter simple CASE <expression> WHEN <value>, men ikke søgte CASE WHEN <predicate> udtryk. For mere information, se Betingede udtryk.

Styring af variabelt omfang og avanceret flow

Variabler forbinder data på tværs af forespørgselssætninger og aktiverer komplekse grafer. Hvis du forstår avancerede områderegler, kan du skrive avancerede forespørgsler med flere udsagn.

Variable bindings- og scoping-mø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)

Genbrug af variabler for joinforbindelser på tværs af sætninger

-- 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 regler og begrænsninger for områder

-- ✅ 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 synlighed i komplekse forespørgsler

-- 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

Advarsel

Variabler i den samme sætning kan ikke referere til hinanden, undtagen i grafmønstre. Brug separate sætninger til oprettelse af afhængige variabler.

Aggregerede rækker og sti-elementer

GQL understøtter to aggregeringskontekster:

  • Vertikal aggregering opsummerer inputrækker, eventuelt opdelt efter GROUP BY variable.
  • Horisontal aggregering opsummerer en gruppeliste bundet af et kantmønster med variabel længde inden for é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 grupperede forespørgsler, aggregate-specifikke filtre, samlingsaggregater og betinget routing, se Filter og aggregerede grafdata. For komplette regler for aggregerede resultater, se Aggregerede funktioner.

Håndter nuller og forespørgselsfejl

Brug eksplicitte nulltests, når manglende værdier kræver særskilt behandling:

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

En sammenligning med null evaluerer til UNKNOWN, som a FILTER ikke fastholder. Brug coalesce() den, når du har brug for en fallback-værdi.

Forespørgselsresultater inkluderer statusinformation for succes, advarsler, datafri tilstande, brugerrettede fejl og systemfejl. Brug den offentlige statuskode til bred kontrolflow og den kanoniske GQLSTATUS-diagnostik for en specifik tilstand. Se Udførelsesresultater og -resultater samt GQL-statuskodernes reference.

Reserverede ord

GQL reserverer visse nøgleord, som du ikke kan bruge som identifikatorer, f.eks. variabler, egenskabsnavne eller navne på navne. Se referencen til reserverede GQL-ord for at få en komplet liste.

Hvis du har brug for at bruge reserverede ord som identifikatorer, skal du undgå dem med backticks: `match`, `return`.

Hvis du vil undgå at undslippe reserverede ord, skal du bruge denne navngivningskonvention:

  • Ved identifikatorer med et enkelt ord skal du tilføje et understregningstegn: :Product_
  • Til identifikatorer med flere ord skal du bruge camelCase eller PascalCase: :MyEntity, , :hasAttributetextColor

Næste trin

Relateret indhold

  • Sidst opdateret den