GQL-språkguide för graf i Microsoft Fabric

GQL (Graph Query Language) är det ISO-standardiserade frågespråket för grafdatabaser. Använd GQL för att fråga, analysera och arbeta effektivt med grafdata med graf i Microsoft Fabric.

Samma ISO-arbetsgrupp som standardiserar SQL utvecklar GQL. Därför delar GQL många begrepp med SQL, inklusive uttryck, predikat och datatyper. Om du har SQL-erfarenhet kan du använda mycket av den kunskapen på GQL.

Den här artikeln är den kompletta guiden till GQL i graf. Den förklarar hur språket hänger ihop och länkar till fokuserade referenser för fullständiga syntax- och typografidetaljer. Den omfattar:

  • Grundläggande begrepp: Diagramdatastrukturer, mönster och frågegrunder
  • Väsentliga påståenden: MATCH, FILTER, LET, , ORDER BYWHEN, LIMIT, ochRETURN
  • Datatyper och uttryck: Värdetyper, operatorer och inbyggda funktioner
  • Avancerade tekniker: Komposition för flera instruktioner, variabelomfång och aggregeringsstrategier

Anmärkning

Den officiella internationella standarden för GQL är ISO/IEC 39075 Information Technology – Databasspråk – GQL.

Om du söker uppgiftsinriktad vägledning istället för en språklig genomgång, se instruktionsguiderna:

Använd de fokuserade referensartiklarna när du behöver fullständig information:

Information behövs Definitiv artikel
En snabbsyntax Snabbreferens för GQL
Syntax för nod, kant, väg och mönsterkomposition GQL-grafmönster
Operatorer, predikat och funktioner GQL-uttryck, predikat och funktioner
Bokstavlig syntax, värdebeteende och typkonverteringar GQL-värden och värdetyper
Graftypdefinitioner och begränsningar GQL-graftyper
Nuvarande ISO GQL-funktionstäckning GQL-standardkonformans
Nuvarande Fabric-specifika begränsningar och begränsningar Aktuella begränsningar

Förutsättningar

Kontrollera att du är bekant med de här begreppen innan du börjar:

  • Basic understanding of databases – Erfarenhet av alla databassystem som relationssystem (SQL), NoSQL eller diagram är till hjälp.
  • Diagrambegrepp – Förstå noder, kanter och relationer i anslutna data.
  • Frågegrunder – Kunskap om grundläggande frågebegrepp som filtrering, sortering och aggregering.

Rekommenderad bakgrund:

  • Erfarenhet av SQL- eller openCypher-språk gör det enklare att lära sig GQL-syntax (de är GQL:s rötter).
  • Kunskaper om datamodellering hjälper till med diagramschemadesign.
  • Förstå ditt specifika användningsfall för grafdata.

Vad du behöver:

  • Åtkomst till en grafarbetsyta med frågefunktioner.
  • Exempel på data eller vilja att arbeta med våra sociala nätverksexempel.
  • Grundläggande textredigerare för att skriva frågor.

Tips/Råd

Om du inte har använt grafdatabaser tidigare börjar du med översikten över diagramdatamodeller innan du fortsätter med den här guiden.

Vad gör GQL speciellt

GQL är specifikt utformad för grafdata, så dess syntax uttrycker direkt hur entiteter är sammankopplade. Där SQL vanligtvis uttrycker relationer genom joins mellan tabeller använder GQL grafmönster som liknar diagram över datan.

Till exempel hittar följande sökning par av personer som känner varandra och båda är födda före 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) visar relationsstrukturen som matchar. Variabler binder de två personerna så att frågan kan filtrera och returnera deras egenskaper.

Grunderna i GQL

Dessa begrepp utgör grunden för GQL:

  • Grafer innehåller noder och kanter med etiketter och egenskaper.
  • Graftyper definierar formellt nodtyper, kanttyper och begränsningar som tillåts i en graf.
  • Frågor använder satser som MATCH, FILTER, och RETURN för att bearbeta data och producera resultat.
  • Mönster beskriver grafstrukturerna för att matcha.
  • Uttryck beräknar, transformerar och jämför värden.
  • Predikat är booleska uttryck som används för att testa villkor.
  • Värdetyper definierar vilka typer av värden som frågor kan bearbeta och grafegenskaper kan lagra.

Förstå grafdata

För att arbeta med GQL behöver du förstå den märkta egenskapsgrafstrukturen som språket frågar i.

Noder och kanter: byggstenarna

En märkt egenskapsgraf innehåller två typer av grafelement:

  • Noder representerar vanligtvis enheter, såsom personer, organisationer, inlägg eller produkter.
  • Kanter representerar kopplingar mellan noder, såsom att en person känner en annan person eller arbetar på ett företag.

Varje grafelement har en intern identitet, en eller flera etiketter och en uppsättning egenskaper. Etiketter klassificerar element, såsom Person eller knows. Egenskaper är namn-värde-par, såsom firstName: 'Alice' eller birthday: 19730108u. I Graph har en kant alltid exakt en etikett.

Varje kant kopplar exakt två noder: ett ursprung och ett mål. Kantriktning är en del av grafens struktur. Till exempel kan en workAt kant koppla ett Person ursprung till ett Company mål.

Anmärkning

Graph stöder för närvarande inte att skapa oriktade kanter. Du kan fråga en befintlig riktad kant i båda riktningarna genom att använda ett valfritt riktat kantmönster såsom -[:knows]-.

Grafer är välformade: varje kant förbinder två noder som finns i samma graf.

Diagrammodeller och graftyper

En Fabric-grafmodell definierar nodtyper, kanttyper, egenskaper, källmappningar och nycklar som finns tillgängliga i en graf. Den specificerar vilka källtabellsrader som blir noder och kanter och hur dessa element hänger ihop. För vägledning om modellering, se Design ett grafschema.

GQL-standarden använder en graftyp för att formellt beskriva tillåtna nodtyper, kanttyper, egenskaper och begränsningar. Graftyper är språknivåns motsvarighet till strukturen som representeras av en Fabric-grafmodell, men Graph accepterar för närvarande inte GQL-graftypdeklarationer direkt. För formell syntax och begrepp, se GQL-graftyper.

Exempelgraf som används i denna guide

Exempel använder exempeldataset från sociala nätverk, som inkluderar personer, platser, organisationer, meddelanden, taggar och de kanter som kopplar ihop dem.

Exempelgrafen kopplar samman dessa områden:

  • Folk känner andra, jobbar på företag och studerar på universitet.
  • Städer, länder eller regioner och kontinenter bildar en geografisk hierarki.
  • Forum innehåller inlägg, och folk skapar inlägg och kommentarer.
  • Taggar kategoriserar innehåll och representerar människors intressen.

Diagram som visar schemat för det sociala nätverket.

För den kompletta exempelstrukturen, se exemplet med sociala nätverksscheman. För allmänna grafbegrepp, se Märkta egenskapsgrafer.

Dina första GQL-frågor

Nu när du förstår grunderna i grafer ska vi se hur du frågar efter grafdata med hjälp av GQL. De här exemplen bygger från enkelt till komplext och visar hur GQL:s metod gör graffrågor intuitiva och kraftfulla.

Börja enkelt: hitta alla personer

Börja med den mest grundläggande frågan som möjligt. Leta reda på namnen (förnamn, efternamn) för alla personer:Person i diagrammet.

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

Den här frågan körs på följande sätt:

  1. MATCH hittar alla noder med etiketten Person.
  2. RETURN visar deras för- och efternamn.

Lägg till filtrering: hitta specifika personer

Hitta nu personer med specifika egenskaper. I det här fallet hittar du alla som heter Alice och visar sina namn och födelsedagar.

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

Den här frågan körs på följande sätt:

  1. MATCH hittar alla noder (p) märkta Person.
  2. FILTER noder (p) vars förnamn är Alice.
  3. RETURN visar deras förnamn, efternamn och födelsedag.

Grundläggande frågestruktur

Grundläggande GQL-frågor följer alla ett konsekvent mönster: en sekvens med instruktioner som fungerar tillsammans för att hitta, filtrera och returnera data. De flesta frågor börjar med MATCH för att hitta mönster i grafen och slutar med RETURN för att specificera utdatan.

Här är en enkel sökning som hittar par av personer som känner varandra och delar samma födelsedag, och sedan returnerar det totala antalet vänpar.

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

Den här frågan körs på följande sätt:

  1. MATCH hittar alla par med Person noder som känner varandra.
  2. FILTER behåller bara de par där båda personerna har samma födelsedag.
  3. RETURN räknar hur många sådana vänpar som finns.

Tips/Råd

Du kan också filtrera direkt i ett mönster genom att lägga till en WHERE klausul. Till exempel MATCH (n:Person WHERE n.birthday < 19900101) matchar endast Person noder med ett birthday värde före 1990.

GQL har stöd för linjekommentarer i C-stil // , linjekommentarer i SQL-format -- och blockkommentarer i C-format /* */ .

Vanliga uttalanden

  • MATCH: Identifierar grafmönstret att söka efter—det är här du definierar strukturen för den data du är intresserad av.
  • LET: Tilldelar nya variabler eller beräknade värden baserat på matchad data—lägger till härledda kolumner till resultatet.
  • FOR: Expanderar en lista till rader, med en valfri nollbaserad offset eller enbaserad ordinal position.
  • CALL: Kör en inline-underfråga för varje inmatningsrad och lägger till kolumnerna som returneras av delfrågan.
  • FILTER: Minskar resultaten genom att tillämpa villkor—tar bort rader som inte uppfyller kriterierna.
  • ORDER BY: Sorterar den filtrerade datan—hjälper till att organisera utdata baserat på ett eller flera fält.
  • OFFSET och LIMIT: Begränsa antalet rader som returneras—användbart för paginering eller top-k-frågor.
  • RETURN: Specificerar slutresultatet—definierar vilken data som ska ingå i resultatuppsättningen och utför aggregering.
  • NEXT: Startar ett nytt frågesteg genom att använda kolumnerna som returnerades från föregående steg.

Så här fungerar instruktioner tillsammans

GQL-satser bildar en pipeline där varje sats bearbetar utdata från den föregående. Denna sekventiella exekvering gör frågor lätta att läsa och felsöka eftersom exekveringsordningen matchar läsordningen.

Viktiga punkter:

  • Satser exekveras effektivt sekventiellt.
  • Varje sats transformerar data och skickar den vidare till nästa.
  • Den här processen skapar ett tydligt och förutsägbart dataflöde som förenklar komplexa frågor.
  • NEXT Starter en ny frågefas. Endast kolumner som projiceras av föregående RETURN uttalande är tillgängliga i nästa steg.
  • UNION, UNION DISTINCT, och UNION ALL kombinerar resultaten av kompletta frågeblock.

Anmärkning

Satser har en definierad logisk ordning. Skriv frågor enligt detta dataflöde istället för att förlita dig på en särskild fysisk exekveringsstrategi.

Exempel på instruktionssammansättning

Följande GQL-sökning hittar de första 10 personerna som arbetar på företag med "Air" i namnet, sorterar dem efter fullständigt namn och returnerar deras fullständiga namn tillsammans med företagets namn.

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

Den här frågan körs på följande sätt:

  1. MATCH Hittar personer som jobbar på företag.
  2. LET skapar fullständiga namn genom att kombinera för- och efternamn.
  3. FILTER behåller endast anställda i företag med "Air" i företagets namn.
  4. ORDER BY sorterar efter fullständigt namn.
  5. LIMIT tar de första 10 resultaten.
  6. RETURN returnerar fullständiga namn och företagsnamn.

Variabler ansluter dina data

Variabler, till exempel p, coch fullName i föregående exempel, innehåller data mellan uttryck. När du återanvänder ett variabelnamn ser GQL automatiskt till att det refererar till samma data, vilket skapar kraftfulla kopplingsvillkor. Variabler kallas ibland även för bindningsvariabler.

Du kan kategorisera variabler på olika sätt:

Efter bindningskälla:

  • Mönstervariabler – bundna av matchande grafmönster
  • Vanliga variabler – bundna av andra språkkonstruktioner

Mönstervariabeltyper:

  • Elementvariabler – binda till referensvärden för grafelement
    • Nodvariabler – binda till enskilda noder
    • Kantvariabler – binda till enskilda kanter
  • Sökvägsvariabler – binda till sökvägsvärden som representerar matchade sökvägar

Efter referensexamen:

  • Singleton-variabler – binda till enskilda elementreferensvärden från mönster
  • Gruppvariabler – bind till listor med elementreferensvärden från mönster med variabel längd. För detaljer, se Aggregerade funktioner.

Körningsresultat och resultat

När du kör en fråga får du tillbaka ett körningsresultat som består av:

  • Ett resultat, normalt en resultattabell med data från ditt RETURN uttalande.
  • Statusinformation som visar om frågan lyckades eller inte.

Resultattabeller

Resultattabellen – om den finns – är det faktiska resultatet av frågekörningen.

En resultattabell innehåller information om namnet och typen av dess kolumner, en önskad kolumnnamnssekvens som ska användas för att visa resultat, om tabellen är ordnad och själva de faktiska raderna.

Anmärkning

Om körningen misslyckas ingår ingen resultattabell i körningsresultatet.

Utelämnade resultat

GQL definierar också ett utelämnat resultat för satser som aldrig producerar rader, oberoende av data eller utvärderingsresultat. Ett utelämnat resultat har statuskod 00001för lyckad komplettering .

Ett utelämnat resultat skiljer sig från en tom resultattabell. En tom tabell innebär att en radproducerande fråga utvärderades men inte producerade några rader. Query API kan representera ett utelämnat resultat med resultattypen NOTHING.

Grafreserver utelämnade resultat för framtida data definition language (DDL) och data manipulation language (DML) statement-stöd. Aktuella frågesatser ger tabellresultat, inklusive tomma tabeller.

Statusinformation

Under frågekörningen identifierar processen olika anmärkningsvärda villkor, till exempel fel eller varningar. Varje villkor registreras av ett statusobjekt i statusinformationen för körningsresultatet.

Statusinformationen består av ett primärt statusobjekt och en (eventuellt tom) lista över andra statusobjekt. Det primära statusobjektet finns alltid och anger om frågekörningen lyckades eller misslyckades.

Varje statusobjekt innehåller en femteckens alfanumerisk kod och en beskrivning av det registrerade tillståndet.

Query API använder följande primära statuskoder:

API-statuskod Meaning
00000 Lyckad slutförande med minst en rad.
00001 Lyckad slutförande med utelämnat resultat. Reserverat för framtida DDL- och DML-stöd.
01000 En varning eller informationsvillkor.
02000 Inga rader är för närvarande tillgängliga från en radproducerande fråga.
42000 Ett användarkorrigerbart fel.
50000 Ett system- eller icke-klassificerat fel.

API:et bevarar den kanoniska GQLSTATUS som rapporteras av frågemotorn i _graphaneGqlStatus medlemmen i diagnosposten. Till exempel använder numeriskt överflöd kanonisk GQLSTATUS 22003, medan division med noll använder 22012; båda representeras av 42000 i det publika status.code fältet.

Viktigt!

I applikationskod, använd status.code för bred framgång och felhantering. Använd den kanoniska GQLSTATUS-diagnostiken när du behöver särskilja ett specifikt frågevillkor. Testa inte beskrivningstexten eftersom den kan variera.

Dessutom kan statusobjekt innehålla ett underliggande orsaksstatusobjekt och en diagnostikpost med ytterligare information som kännetecknar det registrerade villkoret.

Se referensen för GQL-statuskoder

Viktiga begrepp och instruktioner

Det här avsnittet beskriver de grundläggande byggstenar som du behöver för att skriva effektiva GQL-frågor. Varje koncept bygger på praktiska frågeskrivningsfärdigheter.

Grafmönster: hitta struktur

Ett grafmönster beskriver noder, kanter och vägar som ska matchas. Bind variabler när senare satser behöver referera till matchade element:

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

Placera ett predikat i linje när det definierar vilken nod eller kant som kan delta i mönstret:

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

Återanvänd en variabel för att kräva två mönsterpositioner för att binda samma element. Separera mönster med kommatecken för att skapa större grafstrukturer. Använd en kvantifierare som {1,4} för att upprepa ett kantmönster och matcha banor med variabel längd.

Väglägen styr återanvändning av element inom en väg:

Sökvägsläge Behavior
WALK Tillåter upprepade noder och kanter. Det här läget är standard.
TRAIL Förhindrar upprepade kanter.
SIMPLE Förhindrar upprepade noder utom en gemensam första och sista nod.
ACYCLIC Förhindrar alla upprepade noder.

Ett sökvägsprefix styr vilka matchande vägar som returneras. ALL används som standard. ANY SHORTEST returnerar en kortaste väg för varje käll-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-predikater begränsar vägens behörighet innan vägval. Operationer på satsnivå MATCH ... WHERE och senare FILTER är postfilter. Denna skillnad kan förändra ANY SHORTEST resultat.

För definitiv semantik för nod, kant, väg, sammansättning, kvantifikator och predikatplacering, se GQL-grafmönster. För nuvarande vägbegränsningar, se Nuvarande begränsningar.

Kärninstruktioner

GQL innehåller specifika instruktionstyper som fungerar tillsammans för att bearbeta grafdata steg för steg. Det är viktigt att förstå dessa instruktioner för att skapa effektiva frågor.

MATCH uttalande

Syntax:

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

-instruktionen MATCH tar indata och hittar diagrammönster. Den kopplar indatavariabler med mönstervariabler och utdata som alla matchade kombinationer.

Indata- och 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å instruktionsnivå med hjälp av WHERE:

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

Du kan efterfiltrera alla matchningar med hjälp WHEREav . Den här metoden undviker en separat FILTER instruktion. Med ett sökvägsprefix som ANY SHORTEST, gäller satsnivån WHERE efter valet av väg. Inline-predikat begränsar istället vilka vägar som är valbara. För mer information, se Place-predikaten före eller efter val av väg.

Koppla med hjälp av indatavariabler:

När MATCH är inte den första instruktionen kopplas indata till mönstermatchningar:

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

Viktigt!

Graf stöder grundläggande och fullständig linjär satskomposition, inklusive NEXT. Du kan också kombinera frågeblock med UNION, UNION DISTINCT, och UNION ALL. , EXCEPTINTERSECT, och OTHERWISE mängdoperationerna stöds ännu inte. Mer information finns i artikeln om aktuella begränsningar.

Nyckelanslutningsbeteenden:

Så MATCH här hanterar du dataanslutning:

  • Variabeljämlikhet: Indatavariabler kopplas till mönstervariabler med hjälp av likhetsmatchning
  • Inre koppling: Indatarader utan mönstermatchningar ignoreras. Används OPTIONAL MATCH för vänster-yttre kopplingsbeteende.
  • Filtreringsordning: Filter på satsnivå WHERE efter mönstermatchning och vägval klart
  • Mönstersammansättning: Delade variabler begränsar mönster till samma element. Osammanhängande mönster bildar en kartesisk produkt.

Viktigt!

Ett osammanhängande mönster är giltigt, men dess kartesiska produkt kan skapa många rader. Använd delade variabler när mönstren ska hänvisa till samma grafelement.

Joina mönster med delade 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 uttalande

Syntax:

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

OPTIONAL MATCH fungerar som MATCH men använder vänster-yttre kopplingssemantik. Om mönstret inte hittar någon matchning för en indatarad behåller frågan raden med NULL värden för omatchade variabler i stället för att ta bort den.

Example:

-- 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 inte arbetar på något företag visas fortfarande i resultatet med NULL för company_name.

Tips/Råd

Använd OPTIONAL MATCH när du vill inkludera entiteter som kanske inte har en viss relation, som liknar en SQL LEFT JOIN.

LET uttalande

Syntax:

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

-instruktionen LET skapar beräknade variabler och aktiverar datatransformering i din frågepipeline.

Grundläggande variabelskapande:

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

Komplexa beräkningar:

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

Viktiga beteenden:

  • Frågemotorn utvärderar uttryck för varje indatarad.
  • Resultatet blir nya kolumner i utdatatabellen.
  • Variabler kan bara referera till befintliga variabler från tidigare instruktioner.
  • Flera tilldelningar i ett och samma LET sats använder samma inmatningsomfång, så en tilldelning kan inte referera till en annan tilldelning från det uttalandet.

FOR uttalande

Syntax:

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

Satsen FOR expanderar en lista till rader. För varje indatarad skickar den en utdatarad för varje listelement och binder det elementet till den angivna variabeln. Andra variabler från inmatningsraden finns kvar.

Använd WITH OFFSET för att binda ett nollbaserat index, eller använd WITH ORDINALITY för att binda en enbaserad position.

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

Denna fråga returnerar en rad för varje stad. Värdena position är 1, 2, och 3. Om du ersätter WITH ORDINALITY position med WITH OFFSET position, är 0värdena , 1, och 2.

Källuttrycket måste utvärderas till en lista. Ett icke-listvärde gör att frågan misslyckas.

CALL uttalande

Använd CALL för att köra en inline-delfråga för varje inmatad rad:

CALL {
  <query statements>
  RETURN <columns>
}

Variabler som redan är inom räckvidd är implicit tillgängliga inom delfrågan. Av de variabler som skapas i delfrågan blir endast kolumner från dess slutformulering RETURN tillgängliga utanför den. Variabler som skapas i underförfrågan men inte returneras förblir lokala.

Följande korrelerade delfråga beräknar en arbetsgivarantal för varje 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 fungerar som en beroende inre förening. Den producerar en utdatarad för varje rad som returneras av delfrågan. Om delförfrågan inte returnerar några rader returneras inte motsvarande yttre rad. Om den returnerar flera rader visas den yttre raden en gång för varje delfrågerad.

Föregående count(*) exempel returnerar alltid en delfrågerad eftersom det använder en ogrupperad aggregerad. En person utan matchande arbetsgivare har därför en employerCount av 0.

Använd OPTIONAL CALL som en beroende vänsterförening. När delfrågan inte returnerar några rader bevarar den en yttre rad och sätter de returnerade delfrågekolumnerna till NULL. När delfrågan returnerar flera rader producerar den en utdatarad för varje underfrågerad.

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

Du kan nesta inline-subfrågor CALL . En nästlad delfråga kan referera till variabler från sina omslutande frågeomfång.

Viktigt!

Avsluta varje inline-kropp CALL med RETURN. Graph stöder inte namngivna proceduranrop eller explicita variabelimportlistor såsom CALL (p) { ... }.

FILTER uttalande

Syntax:

FILTER [ WHERE ] <predicate>

-instruktionen FILTER ger exakt kontroll över vilka data som fortsätter via din frågepipeline.

Grundläggande filtrering:

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

Komplexa logiska villkor:

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

Null-medvetna filtreringsmönster:

Använd dessa mönster för att hantera null-värden på ett säkert sätt:

  • Sök efter värden: p.firstName IS NOT NULL – har ett förnamn
  • Verifiera data: p.id > 0 – giltigt ID
  • Hantera saknade data: NOT coalesce(p.locationIP, '10.x.x.x') STARTS WITH '10.x.x.x' – ansluter inte från det lokala nätverket
  • Kombinera villkor: Använd AND/OR med explicita null-kontroller för komplex logik

Försiktighet

Kom ihåg att villkor som omfattar null-värden returnerar UNKNOWN, vilket filtrerar bort dessa rader. Använd explicita IS NULL kontroller när du behöver null-inkluderande logik.

ORDER BY uttalande

Syntax:

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

Sortering på flera nivåer med beräknade uttryck:

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)

Null-hantering i sortering:

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

Information om sorteringsbeteende:

Förstå hur ORDER BY fungerar:

  • Frågemotorn utvärderar uttryck för varje rad och sedan fastställer resultaten radordningen.
  • Flera sorteringsnycklar skapar hierarkisk ordning (primär, sekundär, tertiär och så vidare).
  • NULLS FIRST placerar nollvärden före icke-nullvärden. NULLS LAST placerar dem efter icke-nullvärden.
  • Nullplacering är oberoende av sorteringsriktning. Om du inte specificerar nullordning NULLS LAST är standarden för både ASC och DESC.
  • ASC (stigande) är standardordningen och du måste uttryckligen ange DESC (fallande).
  • Du kan sortera efter beräknade värden, inte bara lagrade egenskaper.
Sorteringsspecifikation Resulterande ordning
ASC eller ASC NULLS LAST Icke-nollvärden i stigande ordning, följt av nollvärden.
ASC NULLS FIRST Nollvärden, följt av icke-nullvärden i stigande ordning.
DESC eller DESC NULLS LAST Icke-nollvärden i fallande ordning, följt av nollvärden.
DESC NULLS FIRST Nollvärden, följt av icke-nullvärden i fallande ordning.

Försiktighet

Endast följande instruktion omedelbart kan se den sorteringsordning som ORDER BY upprättas. ORDER BY Följt av RETURN * ger därför inte ett ordnat resultat.

Jämföra:

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

Den här skillnaden får omedelbara konsekvenser för "Top-k"-frågor: LIMIT måste alltid följa instruktionen ORDER BY som upprättar den avsedda sorteringsordningen.

OFFSET- och LIMIT-satser

Syntax:

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

Vanliga mönster:

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

Viktigt!

För förutsägbara sidnumreringsresultat använder ORDER BY du alltid före OFFSET och LIMIT för att säkerställa konsekvent radordning mellan frågor.

RETURN: grundläggande resultatprojektion

Syntax:

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

Instruktionen RETURN genererar frågans slutliga utdata genom att ange vilka data som visas i resultattabellen.

Grundläggande utdata:

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

Använda alias för tydlighetens skull:

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

Kombinera med sortering och 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

Duplicerad hantering med HJÄLP 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

Kombinera med sammansättning:

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

RETURN med GROUP BY: grupperad resultatprojektion

Syntax:

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

Använd GROUP BY för att gruppera rader efter delade värden och beräkningsaggregeringsfunktioner i varje grupp.

Grundläggande gruppering med sammansättning:

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 flera kolumner:

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

Anmärkning

För horisontell aggregering över mönster med variabel längd, se Aggregerade funktioner.

Värden och värdetyper

GQL-värden inkluderar booleska, sträng-, numeriska, temporal-, list-, nod-, kant-, väg-, null- och nothing-värden. Typer kan nullifieras om du inte specificerar NOT NULL. Egenskaper använder en stödd delmängd av hela frågevärdessystemet.

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

Jämförelser med null utvärderar till UNKNOWN; använd IS NULL och IS NOT NULL för nolltester. Numeriska operationer kan tillämpa implicita omvandlingar mellan kompatibla numeriska typer.

Anmärkning

Inte alla GQL-värdetyper stöds i varje grafkontext. För aktuella egenskaps- och frågebegränsningar, se Datatyper.

För literal syntax, jämförelsebeteende, typkonverteringar och typhierarkin, se GQL-värden och värdetyper.

Expressions

Uttryck beräknar, jämför, aggregör och transformerar värden. Vanliga former inkluderar egenskapsreferenser, aritmetiska och logiska operatorer, predikat, funktionsanrop, enkla CASE uttryck och delfrågor:

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 använder trevärd logik: Booleska uttryck kan utvärdera till TRUE, FALSE, eller UNKNOWN. A FILTER behåller endast rader för vilka dess predikat är TRUE.

Aggregera funktioner såsom COUNT, SUM, AVG, , MINoch MAX sammanfatta rader. Listpredikat såsom ALL, ANY, , NONEoch SINGLE utvärdera ett predikat för listelement. Procedurformsunderfrågor EXISTS testar om en nästlad fråga returnerar en rad.

För fullständig operator-, predikat-, agregations- och funktionsbeteende, se GQL-uttryck, predikat och funktioner. För exempel på uppgiftsorienterad filtrering och gruppering, se Filter och aggregera grafdata.

Avancerade frågetekniker

Det här avsnittet beskriver avancerade mönster och tekniker för att skapa komplexa, effektiva graffrågor. Dessa mönster går utöver grundläggande instruktionsanvändning för att hjälpa dig att skapa kraftfulla analysfrågor.

Komplex sammansättning för flera delstater

Viktigt!

Graph stöder grundläggande och fullständig linjär instruktionssammansättning. , EXCEPTINTERSECT, och OTHERWISE mängdoperationerna stöds ännu inte. Mer information finns i artikeln om aktuella begränsningar.

Det är viktigt att förstå hur du skapar komplexa frågor effektivt för avancerade graffrågor.

UNION och UNION ALL

Använd UNION, UNION DISTINCT, eller UNION ALL för att kombinera resultat från två eller flera linjära frågeblock:

<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 är ekvivalent med UNION DISTINCT; båda tar bort dubbletter rader. UNION ALL behåller alla rader, inklusive dubbletter.

Varje frågeblock måste returnera samma uppsättning kolumnnamn. Kolumnordningen kan skilja sig mellan block, och datatyperna måste vara kompatibla.

NEXT

Använd NEXT för att köra ett annat frågesteg mot tabellen som returneras av föregående steg:

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

Följande fråga hittar anställda och deras företag, och använder sedan de returnerade medarbetarnoderna i en annan mönstermatchning:

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

Endast kolumner som returneras av föregående steg är i omfattning efter NEXT. Du kan använda flera NEXT separatorer för att bygga en längre sekvens av frågesteg.

Båda stegen kan innehålla en union av frågeblock. En union utvärderas inom sitt steg innan stegets utdata passerar gränsen NEXT . Om , , och C representerar frågeblock, grupperas A UNION B NEXT C som (A UNION B) NEXT C, medan A NEXT B UNION C grupper som A NEXT (B UNION C). BA

Villkorsstyrda instruktioner

Använd en villkorlig sats för att routa varje inkommande rad till den första grenen vars predikat utvärderar till 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 }> ]

För att routa rader från ett föregående frågesteg, returnera de nödvändiga kolumnerna och använd NEXT före den villkorliga satsen:

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

Varje WHEN predikat måste vara booleskt. Frågemotorn utvärderar predikaten i ordning för varje inmatad rad. Ett predikat som utvärderar till FALSE eller UNKNOWN inte väljer sin gren. Efter att ett predikat utvärderar till TRUE, utvärderas inte senare predikat och ovalda grenkroppar. Om inget predikat utvärderar till TRUE och det inte finns något ELSE, returneras inte indataraden.

Predikat och grenkroppar kan referera till kolumner från föregående steg. En gren kan vara ett linjärt uttalande eller en nästlad procedur innesluten i klammer. Använd en nästlad procedur när en gren behöver flera steg eller satser 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

Varje avdelning har sitt eget lokala område. Syskongrenar ser inte variabler skapade av en annan gren, utan endast kolumner från den valda grenens slutliga RETURN fortsättning efter villkorssatsen. Varje gren måste returnera samma kolumnnamn, och motsvarande resultattyper måste vara kompatibla. Frågemotorn tvingar kompatibla typer till en gemensam utdatatyp. En returnerad grenkolumn kan använda samma namn som en inkommande kolumn; grenvärdet ersätter det inkommande värdet i den villkorliga utdatan.

Villkorliga satser skiljer sig från CASE uttryck. Graph stöder enkla CASE <expression> WHEN <value>, men inte sökta CASE WHEN <predicate> uttryck. För mer information, se Villkorsuttryck.

Variabelomfång och avancerad flödeskontroll

Variabler ansluter data mellan frågeinstruktioner och aktiverar komplexa diagramblädderingar. Genom att förstå regler för avancerat omfång kan du skriva avancerade frågor med flera instruktioner.

Mönster för variabelbindning och omfång

-- 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 återanvändning för kopplingar mellan uttryck

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

Viktiga omfångsregler och begränsningar

-- ✅ 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 komplexa frågor

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

Försiktighet

Variabler i samma instruktion kan inte referera till varandra, förutom i grafmönster. Använd separata instruktioner för att skapa beroende variabler.

Aggregerade rader och vägelement

GQL stöder två aggregeringskontexter:

  • Vertikal aggregering sammanfattar indatarader, valfritt uppdelade efter GROUP BY variabler.
  • Horisontell aggregering sammanfattar en grupplista begränsad av ett kantmönster med variabel längd inom en matchad väg.
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

För grupperade frågor, aggregatespecifika filter, samlingsaggregeringar och villkorlig routing, se Filter och aggregerad grafdata. För fullständiga regler för aggregerade resultat, se Aggregerade funktioner.

Hantera nollpunkter och frågefel

Använd explicita nolltester när saknade värden behöver olika hantering:

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

En jämförelse med null utvärderar till UNKNOWN, vilket a FILTER inte behåller. Använd coalesce() när du behöver ett reservvärde.

Frågeresultat inkluderar statusinformation för framgång, varningar, datafria tillstånd, användarkorrigerbara fel och systemfel. Använd den publika statuskoden för bred kontrollflöde och den kanoniska GQLSTATUS-diagnostiken för ett specifikt tillstånd. Se Execution outcomes and results samt GQL-statuskodsreferensen.

Reserverade ord

GQL reserverar vissa nyckelord som du inte kan använda som identifierare som variabler, egenskapsnamn eller etikettnamn. Se referensen för reserverade GQL-ord för den fullständiga listan.

Om du behöver använda reserverade ord som identifierare kan du undvika dem med backticks: `match`, `return`.

Använd den här namngivningskonventionen för att undvika reserverade ord:

  • För enordsidentifierare lägger du till ett understreck: :Product_
  • För identifierare med flera ord använder du camelCase eller PascalCase: :MyEntity, :hasAttribute, textColor

Nästa steg

Relaterat innehåll

  • Last updated on