Snabbreferens för GQL

Den här artikeln är en snabbreferens för GQL-syntax (Graph Query Language) för graf i Microsoft Fabric. Använd den för att minnas syntax och standardinställningar. För en helhetsförklaring, se GQL:s språkguide; varje avsnitt länkar till den fokuserade referensen som innehåller alla detaljer.

Frågestruktur

GQL-frågor använder en sekvens med instruktioner som definierar vilka data som ska hämtas från grafen, hur du bearbetar dem och hur du visar resultatet. Varje instruktion har ett specifikt syfte och tillsammans skapar de en linjär pipeline som matchar data från grafen och transformerar den steg för steg.

Typiskt frågeflöde:
En GQL-fråga startar vanligtvis genom att ange det grafmönster som ska matchas. Sedan används valfria instruktioner för variabelskapande, filtrering, sortering, sidnumrering och resultatutdata.

Example:

MATCH (n:Person)-[:knows]->(m:Person) 
LET fullName = n.firstName || ' ' || n.lastName 
FILTER m.gender = 'female' 
ORDER BY fullName ASC 
OFFSET 10
LIMIT 5 
RETURN fullName, m.firstName

Uttalandesuppställning:

• MATCH – Ange diagrammönster som ska hittas.
• LET – Definiera variabler från uttryck.
• FOR – Utöka en lista till rader.
• CALL – Kör en inline-underfråga och lägg till dess returnerade kolumner.
• FILTER – Behåll radmatchningsvillkor.
• WHEN – Dirite varje indata rad till den första matchande villkorsgrenen.
• ORDER BY – Sortera resultat.
• OFFSET – Hoppa över många rader.
• LIMIT – Begränsa antalet rader.
• RETURN – Utdata för slutresultatet.
• NEXT – Starta ett nytt frågesteg genom att använda kolumnerna som returnerades av föregående steg.

Varje instruktion bygger på den föregående, så du förfinar och formar frågeutdata stegvis. Använd UNION, UNION DISTINCT, eller UNION ALL för att kombinera kompletta frågeblock. Mer information om varje instruktion finns i följande avsnitt.

Frågeformuleringar

MATCH

Hitta diagrammönster i dina data.

Syntax:

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

Example:

MATCH (n:Person)-[:knows]-(m:Person) WHERE n.birthday > 2000
RETURN *

Mer information om -instruktionen MATCH finns i Graph-mönstren.

LÅTA

Skapa variabler med hjälp av uttryck.

Syntax:

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

Example:

MATCH (n:Person)
LET fullName = n.firstName || ' ' || n.lastName
RETURN fullName

Mer information om -instruktionen LET finns i språkguiden för GQL.

FOR

Expanderar en lista till rader och returnerar valfritt varje elements position.

Syntax:

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

Example:

FOR value IN [10, 20] WITH OFFSET index
RETURN value, index

WITH OFFSET börjar vid 0. WITH ORDINALITY börjar vid 1.

Mer information om -instruktionen FOR finns i språkguiden för GQL.

CALL

Kör en inline-subquery för varje inmatad rad. Variabler som redan är inom scope är implicit tillgängliga inom delfrågan.

Syntax:

[ OPTIONAL ] CALL {
  <query statements>
  RETURN <columns>
}
...

Av de variabler som skapas i delfrågan blir endast kolumner från dess slutformulering RETURN tillgängliga utanför den. Ordinary CALL tar bort en yttre rad när delfrågan inte ger några rader och multiplicerar den när delfrågan returnerar flera rader. OPTIONAL CALL bevarar en yttre rad med NULL delfrågekolumner när delfrågan inte ger några rader.

MATCH (p:Person)
CALL {
  MATCH (p)-[:knows]->(friend:Person)
  RETURN count(*) AS friendCount
}
RETURN p.firstName, friendCount

För mer information om inline-subfrågor, se GQL:s språkguide.

FILTER

Behåller rader som matchar villkor.

Syntax:

FILTER [ WHERE ] <predicate>
...

Example:

MATCH (n:Person)-[:knows]->(m:Person)
FILTER WHERE n.birthday > m.birthday
RETURN *

Mer information om -instruktionen FILTER finns i språkguiden för GQL.

SORTERA EFTER

Sorterar resultatet.

Syntax:

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

Example:

MATCH (n:Person)
RETURN *
ORDER BY n.lastName ASC NULLS LAST, n.firstName ASC

Nullplacering är oberoende av sorteringsriktning. Standardvärdet är NULLS LAST för både ASC och DESC; ange NULLS FIRST att placera nollvärden före icke-nollvärden.

Mer information om -instruktionen ORDER BY finns i språkguiden för GQL.

OFFSET/LIMIT

Hoppa över rader och begränsa antalet resultat.

Syntax:

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

Example:

MATCH (n:Person)
ORDER BY n.birthday
OFFSET 10 LIMIT 20
RETURN n.firstName || ' ' || n.lastName AS name, n.birthday

Mer information om instruktionen OFFSET och LIMIT finns i språkguiden för GQL.

RETURN

Mata ut de slutliga resultaten.

Syntax:

RETURN [ DISTINCT ] <expression> [ AS <alias> ], ...

Example:

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

Mer information om -instruktionen RETURN finns i språkguiden för GQL.

NEXT

Startar ett nytt frågesteg. Endast kolumner som returneras av föregående steg är tillgängliga efter NEXT.

Syntax:

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

Example:

RETURN 1 AS value
NEXT
RETURN value + 1 AS nextValue

Båda stegen kan innehålla en union av frågeblock. Unionen utvärderas inom det steget innan dess utdata korsar gränsen NEXT .

För mer information om NEXT, se GQL:s språkguide.

Villkorsstyrda instruktioner

Leder varje indata rad till den första WHEN grenen vars predikat utvärderar till TRUE.

Syntax:

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

Predikat måste vara booleska och utvärderas i ordning. FALSE och UNKNOWN falla vidare till nästa gren. Om ingen gren matchar och det inte finns någon ELSE, utelämnas inmatningsraden. Predikat efter första matchningen och ovalda grenkroppar utvärderas inte.

RETURN 'Alice' AS name, 19900101u AS birthday
NEXT
WHEN birthday < 20000101u THEN
  RETURN name, 'Before 2000' AS era
ELSE
  RETURN name, '2000 or later' AS era

Alla grenar måste returnera samma kolumnnamn med kompatibla datatyper. Omslut en gren med tandställning när den innehåller en nästlad procedur.

För mer information, se Villkorssatser.

UNION

Kombinerar utdata från kompletta frågeblock.

Syntax:

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

Ta bort UNION dubbletter och UNION DISTINCT rader. UNION ALL bevarar dubblettrader. Varje frågeblock måste returnera samma uppsättning kolumnnamn med kompatibla datatyper.

För mer information om fackföreningar, se GQL:s språkguide.

Diagrammönster

Diagrammönster beskriver strukturen för grafen som ska matchas.

Nodmönster

I grafdatabaser använder du noder för att representera entiteter, till exempel personer, produkter eller platser.

Nodmönster beskriver hur du matchar noder i diagrammet. Du kan filtrera efter etikett eller bindningsvariabler.

(n)              -- Any node
(n:Person)       -- Node with Person label  
(n:City&Place)   -- Node with City AND Place label
(:Person)        -- Person node, don't bind variable

Mer information om nodmönster finns i Diagrammönster.

Kantmönster

Kantmönster anger relationer mellan noder, inklusive riktning och kanttyp. I grafdatabaser representerar en kant en anslutning eller relation mellan två noder.

<-[e]-             -- Incoming edge
-[e]->             -- Outgoing edge
-[e]-              -- Any edge
-[e:knows]->       -- Edge with label ("relationship type")
-[e:knows|likes]-> -- Edges with different labels
-[:knows]->        -- :knows edge, don't bind variable

Mer information om kantmönster finns i Diagrammönster.

Etikettuttryck

Med etikettuttryck kan du matcha noder med specifika etikettkombinationer med hjälp av logiska operatorer.

:Person&Company                  -- Both Person AND Company labels
:Person|Company                  -- Person OR Company labels
:!Company                        -- NOT Company label
:(Person|!Company)&Active        -- Complex expressions with parentheses

Mer information om etikettuttryck finns i Diagrammönster.

Sökvägsmönster

Sökvägsmönster beskriver blädderingar genom diagrammet, inklusive hoppantal och variabelbindningar.

(a)-[:knows|likes]->{1,3}(b)        -- 1-3 hops via knows/likes
p=()-[:knows]->()                   -- Bind a path variable
MATCH REPEATABLE ELEMENTS (a)->(b)  -- Explicit default match mode
MATCH DIFFERENT EDGES (a)->(b), (a)->(c)
MATCH ALL TRAIL (a)->{1,4}(b)       -- Every edge-unique path
MATCH p = ANY SHORTEST (a)->{1,4}(b) -- One shortest path per endpoint pair

WALK är standardvägsläget och tillåter upprepade noder och kanter. TRAIL förhindrar upprepade kanter. SIMPLE förhindrar upprepade noder utom en stängande första-to-sista cykel, och ACYCLIC förhindrar alla upprepade noder. Båda nodunika lägena förhindrar också upprepade kanter eftersom återanvändning av kanter skulle upprepa ändpunktsnoder. ALL är standardsökningen för väg. ANY SHORTEST returnerar en kortaste väg för varje käll-destinationspar och väljer inte deterministiskt bland bundna vägar.

Stödda kvantifikatorer inkluderar fasta {n}, begränsade {m,n} och {,n}, samt obundna {m,}, *, och +. Obegränsade ALL WALK mönster stöds inte; använd ett avslutande väg-läge. Unbounded ANY SHORTEST WALK har ytterligare form- och vägvärdesbegränsningar. För detaljer, se GQL-grafmönster.

Mer information om sökvägsmönster finns i Diagrammönster.

Flera mönster

Använd flera mönster för att matcha komplexa, icke-linjära grafstrukturer i en enda fråga.

(a)->(b), (a)->(c)               -- Multiple edges from same node
(a)->(b)<-(c), (b)->(d)          -- Nonlinear structures

Mer information om flera mönster finns i Diagrammönster.

Värden och värdetyper

Grundläggande typer

Grundläggande typer är primitiva datavärden som strängar, tal, booleska värden och datetimes.

STRING           -- 'hello', "world"
INT64            -- 42, -17
FLOAT64          -- 3.14, -2.5e10, -17d
BOOL             -- TRUE, FALSE, UNKNOWN
ZONED DATETIME   -- ZONED_DATETIME('2023-01-15T10:30:00Z')

Suffixet d eller D skapar en ungefärlig FLOAT64 literal. En exponent utan suffix skapar också ett FLOAT64 värde. Och F bokstavliga f suffix stöds inte för tillfället.

Mer information om grundläggande typer finns i GQL-värden och värdetyper.

Referensvärdetyper

Referensvärdetyper är noder och kanter som du använder som värden i frågor.

NODE             -- Node reference values
EDGE             -- Edge reference values

Mer information om referensvärdetyper finns i GQL-värden och värdetyper.

Samlingstyper

Samlingstyper grupperar flera värden, till exempel listor och sökvägar.

LIST<INT64>      -- [1, 2, 3]
LIST<STRING>     -- ['a', 'b', 'c']
PATH             -- Path values

Mer information om samlingstyper finns i GQL-värden och värdetyper.

Materiella och nullbara typer

Varje värdetyp är antingen nullbar (innehåller null-värdet) eller material (exkluderar det). Som standard kan typerna vara null om du inte uttryckligen anger NOT NULL.

STRING NOT NULL  -- Material (Non-nullable) string type
INT64            -- Nullable (default) integer type

Uttryck och operatorer

Conditional

Enkla CASE uttryck jämför ett uttryck med ett eller flera värden.

CASE expr WHEN val THEN val ELSE val END -- Simple CASE
NULLIF(a, b)                           -- NULL if a = b

Sökta CASE WHEN <predicate> uttryck stöds inte. Använd en villkorlig sats för att routa rader baserade på predikat.

Mer information om villkorsuttryck finns i GQL-uttryck och -funktioner.

Jämförelse

Jämförelseoperatorer jämför värden och söker efter likhet, ordning eller null.

=, <>, <, <=, >, >=              -- Standard comparison
IS NULL, IS NOT NULL             -- Null checks

Mer information om jämförelsepredikat finns i GQL-uttryck och -funktioner.

Logical

Logiska operatorer kombinerar eller negerar booleska villkor i frågor.

AND, OR, NOT, XOR               -- Boolean logic

Mer information om logiska uttryck finns i GQL-uttryck och -funktioner.

EXISTS

Testar om en procedurform-delfråga returnerar minst en rad.

EXISTS {
  MATCH (p)-[:knows]->(friend:Person)
  RETURN friend
}

EXISTS returnerar ett icke-null boolesk värde. Använd NOT EXISTS för att testa att delförfrågan inte ger några rader. Du kan använda resultatet i WHERE eller FILTER, LET, , RETURN, ORDER BYoch aggregera filter- eller källuttryck. EXISTS stöds inte i ett listpredikatfilter.

För mer information om EXISTS, se Existens-subfrågor.

Arithmetic

Aritmetiska operatorer utför beräkningar på tal.

+, -, *, /                       -- Basic arithmetic operations
1.00m / 8.00m                    -- Exact result: 0.1250m

Mer information om aritmetiska uttryck finns i GQL-uttryck och -funktioner.

Strängmönster

Strängmönsterpredikat matchar understrängar, prefix eller suffix i strängar.

n.firstName CONTAINS 'John'          -- Has substring
n.browserUsed STARTS WITH 'Chrome'   -- Starts with prefix
n.locationIP ENDS WITH '.1'          -- Ends with suffix
MSFT.REGEXP_LIKE(n.firstName, '^jo', 'i') -- RE2 regular expression

Mer information om strängmönsterpredikat finns i GQL-uttryck och -funktioner.

Liståtgärder

Lista åtgärder testar medlemskap, åtkomstelement och måttlistlängd.

n.gender IN ['male', 'female']    -- Membership test
n.tags[0]                        -- First element
size(n.tags)                     -- List length
ALL(x IN n.tags WHERE x <> '')   -- Every element matches
ANY(x IN n.tags WHERE x = 'gql') -- At least one element matches
NONE(x IN n.tags WHERE x = '')   -- No element matches
SINGLE(x IN n.tags WHERE x = 'gql') -- Exactly one element matches

Listpredikatfunktioner returnerar TRUE, FALSE, eller UNKNOWN enligt filterresultaten. För en tom lista, ALL och NONE returnera TRUE, medan ANY och SINGLE returnerar FALSE. En nollkälllista ger .UNKNOWN

Elementbindningen är lokal för filtret och kan skugga en yttre variabel. Aggregat över den lokala bindningen och EXISTS subfrågor inuti filtret stöds inte.

För mer information, se Lista predikatfunktioner.

Egenskapsåtkomst

Egenskapsåtkomst hämtar värdet för en egenskap från en nod eller kant.

n.firstName                      -- Property access

Mer information om egenskapsåtkomst finns i GQL-uttryck och funktioner.

Functions

Använd inbyggda funktioner för att transformera värden, inspektera grafelement och aggregera rader.

Numeriska funktioner

Numeriska funktioner beräknar numeriska värden eller ger heltalsintervall.

abs(value)                       -- Absolute value; preserves the numeric type
power(base, exponent)            -- Exponentiation; returns DOUBLE
sin(radians), cos(radians)       -- Trigonometric functions
asin(value), acos(value)         -- Inverse functions; value must be in [-1, 1]
degrees(radians)                 -- Convert radians to degrees
radians(degrees)                 -- Convert degrees to radians
range(start, end)                -- Integer range with step 1
range(start, end, step)          -- Integer range with a nonzero step

Andra stödda trigonometriska funktioner är TAN, COT, , ATAN, SINH, COSHoch TANH. Förutom och ABSRANGE, returnerar DOUBLEdessa numeriska funktioner .

Lär dig mer om numeriska funktioner i GQL-uttryck och funktioner.

Aggregatfunktioner

Sammanställda funktioner beräknar sammanfattningsvärden för grupper av rader (lodrät sammansättning) eller över elementen i en grupplista (vågrät sammansättning).

count(*)                         -- Count all rows
count(expr)                      -- Count non-null values
sum(p.birthday)                  -- Sum values
avg(p.birthday)                  -- Average
min(p.birthday), max(p.birthday) -- Minimum and maximum values
collect_list(p.firstName)        -- Collect inputs, including nulls
collect_one(p.firstName)         -- Select one non-null value
collect_elements(p.roles)        -- Concatenate list-valued inputs
count(DISTINCT expr)             -- Remove duplicate expression values
count(*) FILTER (WHERE predicate LIMIT 10) -- Filter and limit this aggregate

Utan att gruppera kolumner returnerar 0 en aggregerad fråga utan inmatningsrader för COUNT, en tom lista för COLLECT_LIST och COLLECT_ELEMENTS, och en noll för SUM, AVG, MIN, MAX, och COLLECT_ONE. Ett grupplistaargument gör aggregeringen horisontell.

Läs mer om mängdfunktioner i GQL-uttryck och -funktioner.

Strängfunktioner

Med strängfunktioner kan du arbeta med och analysera strängvärden.

char_length(s)                   -- String length
upper(s), lower(s)               -- Unicode case mapping
casefold(s)                      -- Unicode caseless form
normalize(s)                     -- Normalize a string to NFC
normalize(s, NFD)                -- Normalize a string to NFD
trim(s)                          -- Trim spaces
trim(leading '_' from s)         -- Trim one custom byte
string_join(list)                -- Join with ", "
string_join(list, delimiter)     -- Join with a custom delimiter
MSFT.REGEXP_COUNT(s, pattern)    -- Count RE2 matches
MSFT.REGEXP_INSTR(s, pattern)    -- Find a zero-based match position
MSFT.REGEXP_SUBSTR(s, pattern)   -- Return matching text
MSFT.REGEXP_REPLACE(s, pattern, replacement) -- Replace matches

Regex-mönster, ersättningar och alternativ måste vara bokstavliga. För signaturer, flaggor och nullbeteende, se Strängfunktioner.

Lista funktioner

Med listfunktioner kan du arbeta med listor som att kontrollera längd eller trimningsstorlek.

size(list)                       -- List length
trim(list, n)                    -- Trim a list to at most n elements

Mer information om listfunktioner finns i GQL-uttryck och funktioner.

Graph-funktioner

Med graffunktioner kan du hämta information från noder, sökvägar och kanter.

labels(node)                     -- Get node labels
element_id(node_or_edge)         -- Get an opaque element identifier
nodes(path)                      -- Get path nodes
edges(path)                      -- Get path edges
elements(path)                   -- Get all path nodes and edges
path_length(path)                -- Get number of edges in a path

Mer information om graffunktioner finns i GQL-uttryck och funktioner.

Temporala funktioner

Med tidsfunktioner kan du arbeta med datum- och tidsvärden.

CURRENT_TIMESTAMP                -- Get the current zoned datetime
ZONED_DATETIME(string)           -- Parse an ISO 8601 zoned datetime
DURATION(string)                 -- Parse an ISO 8601 day-time duration

Mer information om temporala funktioner finns i GQL-uttryck och funktioner.

Allmänna funktioner

Med allmänna funktioner kan du arbeta med data på vanliga sätt.

coalesce(expr1, expr2, ...)    -- Get the first non-null value
to_json_string(value)          -- Convert value to JSON string
nullif(a, b)                   -- NULL if a = b, else a

Mer information om allmänna funktioner finns i GQL-uttryck och funktioner.

Uppgiftsorienterade exempel

Använd instruktionsartiklarna när du behöver kompletta, färdiga frågemönster:

• Skriv gemensamma GQL-frågor för grannar, multihop-traversering, delade anslutningar och existenskontroller.
• Filtrera och aggregera grafdata för rader- och mönsterfiltrering, gruppering, samlingsaggregeringar och villkorlig routing.
• Skriv grafmönsterfrågor för väg-mod, sökvägar, mönsterkomposition och valfri matchning.

Relaterat innehåll

• Språkguide för GQL
• GQL-grafmönster
• GQL-uttryck, predikat och funktioner
• GQL-värden och värdetyper