Hurtig reference til GQL

Denne artikel er en hurtig reference til GQL-syntaks (Graph Query Language) for graph i Microsoft Fabric. Brug det til at huske syntaks og standardindstillinger. For en gennemgående forklaring, se GQL-sprogguiden; hver sektion linker til den fokuserede reference, der ejer alle detaljerne.

Notat

Denne artikel bruger primært grafdatasættet eksempel på sociale netværk. Den indeholder også et par eksempler, der bruger Adventure Works-datasættet fra grafens selvstudium.

Forespørgselsstruktur

GQL-forespørgsler bruger en sekvens af sætninger, der definerer, hvilke data der skal hentes fra grafen, hvordan de skal behandles, og hvordan resultaterne vises. Hver sætning har et bestemt formål, og sammen opretter de en lineær pipeline, der matcher data fra grafen og transformerer dem trinvist.

Typisk forespørgselsflow:
En GQL-forespørgsel starter normalt med at angive det diagrammønster, der skal matche. Derefter bruges valgfrie sætninger til oprettelse, filtrering, sortering, sideinddeling og resultatoutput.

Eksempel:

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

Udsagnsopbygning:

Vigtige oplysninger

Sætninger danner en ordnet pipeline og kan ikke omarrangeres vilkårligt. Se artiklen om aktuelle begrænsninger.

  • MATCH – Angiv diagrammønstre, der skal søges efter.
  • LET – Definer variabler fra udtryk.
  • FOR – Udvid en liste til rækker.
  • CALL – Kør en inline underforespørgsel og tilføj de returnerede kolonner.
  • FILTER – Bevar rækker, der matcher betingelser.
  • WHEN – Route hver inputrække til den første matchende betingede gren.
  • ORDER BY – Sortér resultater.
  • OFFSET – Spring mange rækker over.
  • LIMIT – Begræns antallet af rækker.
  • RETURN – Skriv de endelige resultater.
  • NEXT – Start et nyt forespørgselstrin ved at bruge de kolonner, der returneres af det foregående trin.

Hver sætning bygger på den forrige, så du trinvist finjustere og forme forespørgselsoutputtet. Brug UNION, UNION DISTINCT, eller UNION ALL til at kombinere komplette forespørgselsblokke. Du kan få flere oplysninger om hver enkelt sætning i følgende afsnit.

Forespørgselssætninger

TÆNDSTIK

Find grafmønstre i dine data.

Syntaks:

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

Eksempel:

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

Du kan få flere oplysninger om sætningen MATCH i Graph-mønstre.

TILLADE

Opret variabler ved hjælp af udtryk.

Syntaks:

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

Eksempel:

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

Du kan få flere oplysninger om sætningen LET i GQL-sprogvejledningen.

TIL

Udvider en liste til rækker og returnerer valgfrit hvert elements position.

Syntaks:

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

Eksempel:

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

WITH OFFSET starter ved 0. WITH ORDINALITY starter ved 1.

Du kan få flere oplysninger om sætningen FOR i GQL-sprogvejledningen.

RING OP

Kører en inline underforespørgsel for hver input-række. Variable, der allerede er inden for scope, er implicit tilgængelige inde i underforespørgslen.

Syntaks:

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

Af de variable, der oprettes inde i underforespørgslen, bliver kun kolonner fra dens endelige RETURN sætning tilgængelige udenfor. Ordinary CALL dropper en ydre række, når underforespørgslen ikke returnerer nogen rækker, og multiplicerer den, når underforespørgslen returnerer flere rækker. OPTIONAL CALL bevarer en ydre række med NULL underforespørgselskolonner, når underforespørgslen returnerer ingen rækker.

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

For mere information om inline subforespørgsler, se GQL-sprogguiden.

FILTER

Bevarer rækker, der matcher betingelser.

Syntaks:

FILTER [ WHERE ] <predicate>
...

Eksempel:

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

Du kan få flere oplysninger om sætningen FILTER i GQL-sprogvejledningen.

BESTIL EFTER

Sorterer resultaterne.

Syntaks:

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

Eksempel:

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

Nullplacering er uafhængig af sorteringsretningen. Standarden er NULLS LAST for både ASC og DESC; angiv NULLS FIRST at placere nullværdier før ikke-nulværdier.

Vigtige oplysninger

Den ønskede rækkefølge af rækker er kun garanteret at gælde umiddelbart efter en forudgående ORDER BY sætning. Følgende sætninger (hvis de findes) garanteres ikke at bevare en sådan rækkefølge.

Du kan få flere oplysninger om sætningen ORDER BY i GQL-sprogvejledningen.

FORSKYDNING/GRÆNSE

Spring rækker over, og begræns antallet af resultater.

Syntaks:

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

Eksempel:

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

Du kan få flere oplysninger om sætningerne OFFSET og LIMIT i GQL-sprogvejledningen.

RETURBILLET

Skriv de endelige resultater.

Syntaks:

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

Eksempel:

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

Du kan få flere oplysninger om sætningen RETURN i GQL-sprogvejledningen.

NÆSTE

Starter en ny forespørgselsfase. Kun kolonner, der returneres af det foregående trin, er tilgængelige efter NEXT.

Syntaks:

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

Eksempel:

RETURN 1 AS value
NEXT
RETURN value + 1 AS nextValue

Begge faser kan indeholde en union af forespørgselsblokke. Unionen evalueres inden for dette trin, før dens output krydser grænsen NEXT .

For mere information om NEXT, se GQL-sprogguiden.

Betingelsessætninger

Ruter hver inputrække til den første WHEN gren, hvis prædikat evaluerer til TRUE.

Syntaks:

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

Prædikater skal være boolske og evalueres i rækkefølge. FALSE og UNKNOWN falder igennem til næste gren. Hvis ingen gren matcher, og der ikke er nogen ELSE, udelades inputrækken. Prædikater efter det første match og uvalgte forgreningslegemer bliver ikke evalueret.

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

Alle grene skal returnere de samme kolonnenavne med kompatible datatyper. Omslutt en gren med bøjler, når den indeholder en indlejret procedure.

For mere information, se Betingede sætninger.

UNION

Kombinerer outputtet fra komplette forespørgselsblokke.

Syntaks:

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

Nøt UNION og UNION DISTINCT fjern dubletter rækker. UNION ALL bevarer dubletter rækker. Hver forespørgselsblok skal returnere det samme sæt kolonnenavne med kompatible datatyper.

For mere information om fagforeninger, se GQL-sprogguiden.

Grafmønstre

Grafmønstre beskriver den diagramstruktur, der skal matche.

Nodemønstre

I grafdatabaser skal du bruge noder til at repræsentere enheder, f.eks. personer, produkter eller steder.

Nodemønstre beskriver, hvordan du matcher noder i grafen. Du kan filtrere efter mærkat eller binde variabler.

(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

Du kan få flere oplysninger om nodemønstre i Grafmønstre.

Kantmønstre

Kantmønstre angiver relationer mellem noder, herunder retning og kanttype. I grafdatabaser repræsenterer en kant en forbindelse eller en relation mellem to 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

Du kan få flere oplysninger om kantmønstre i Grafmønstre.

Navneudtryk

Med navneudtryk kan du matche noder med bestemte navnekombinationer ved hjælp af logiske 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

Du kan få flere oplysninger om mærkatudtryk i Grafmønstre.

Stimønstre

Stimønstre beskriver gennemgange gennem grafen, herunder hopantal og variabelbindinger.

(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 er standardsti-tilstanden og tillader gentagne noder og kanter. TRAIL forhindrer gentagne kanter. SIMPLE forhindrer gentagne noder undtagen en lukkende første-til-sidste cyklus, og ACYCLIC forhindrer alle gentagne noder. Begge node-unikke tilstande forhindrer også gentagne kanter, fordi genbrug af kanter ville gentage endepunktsnoder. ALL er standardsti-søgningen. ANY SHORTEST returnerer én korteste sti for hvert kilde-destinationspar og vælger ikke deterministisk blandt bundne stier.

Understøttede kvantorer inkluderer faste {n}, begrænsede {m,n} og {,n}, samt ubegrænsede {m,}, *, og +. Ubegrænsede ALL WALK mønstre understøttes ikke; brug en terminerende sti-tilstand. Ubegrænset ANY SHORTEST WALK har yderligere form- og sti-værdibegrænsninger. For detaljer, se GQL-grafmønstre.

Du kan få flere oplysninger om stimønstre i Grafmønstre.

Flere mønstre

Brug flere mønstre til at matche komplekse, ikke-linede grafstrukturer i en enkelt forespørgsel.

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

Du kan få flere oplysninger om flere mønstre i Grafmønstre.

Værdier og værdityper

Grundlæggende typer

Grundlæggende typer er primitive dataværdier, f.eks. strenge, tal, booleske værdier og 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')

Eller D suffikset d danner et omtrentligt FLOAT64 bogstaveligt tal. En eksponent uden suffiks skaber også en FLOAT64 værdi. Og bogstavelige fF suffikser understøttes ikke i øjeblikket.

Du kan få flere oplysninger om grundlæggende typer under GQL-værdier og værdityper.

Referenceværdityper

Referenceværdityper er noder og kanter, som du bruger som værdier i forespørgsler.

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

Du kan få flere oplysninger om referenceværdityper under GQL-værdier og værdityper.

Samlingstyper

Samlingstyper grupperer flere værdier, f.eks. lister og stier.

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

Du kan få flere oplysninger om samlingstyper under GQL-værdier og værdityper.

Materiale- og null-typer

Hver værditype kan enten være null (indeholder null-værdien) eller materiale (udelader den). Typer kan som standard være null, medmindre du eksplicit angiver NOT NULL.

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

Udtryk & operatorer

Betinget

Simple CASE udtryk sammenligner et udtryk med en eller flere værdier.

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

Søgte CASE WHEN <predicate> udtryk understøttes ikke. Brug en betinget sætning til at rute rækker baseret på prædikater.

Du kan få flere oplysninger om betingede udtryk i GQL-udtryk og -funktioner.

Sammenligning

Sammenligningsoperatorer sammenligner værdier og kontrollerer, om der er lighed, rækkefølge eller null-værdier.

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

Du kan få flere oplysninger om sammenlignings prædikater i GQL-udtryk og -funktioner.

Logisk

Logiske operatorer kombinerer eller ophæver booleske betingelser i forespørgsler.

AND, OR, NOT, XOR               -- Boolean logic

Du kan få flere oplysninger om logiske udtryk i GQL-udtryk og -funktioner.

FINDES

Tester, om en procedureform-underforespørgsel returnerer mindst én række.

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

EXISTS returnerer en ikke-null boolesk værdi. Brug NOT EXISTS til at teste, at underforespørgslen ikke returnerer nogen rækker. Du kan bruge resultatet i WHERE eller FILTER, , LET, RETURN, ORDER BYog aggregere filter- eller kildeudtryk. EXISTS understøttes ikke i et listepredikatfilter.

Vigtige oplysninger

Grafmønstre-only former som EXISTS { (p)-[:knows]->(friend) } og EXISTS ((p)-[:knows]->(friend)) understøttes ikke. Brug procedureformen, som MATCH vist i det foregående eksempel.

Forsigtighed

Et ugrupperet aggregat som for eksempel RETURN count(*) returnerer én række, selv når intet mønster matcher. Fordi EXISTS tester for rækker, evaluerer den form til TRUE.

For mere information om EXISTS, se Eksistens-underforespørgsler.

Aritmetik

Aritmetiske operatorer udfører beregninger på tal.

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

Du kan få flere oplysninger om aritmetiske udtryk i GQL-udtryk og -funktioner.

Strengmønstre

Strengmønster prædikater matcher understrenge, præfikser eller suffikser i strenge.

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

Du kan få flere oplysninger om prædikater for strengmønster i GQL-udtryk og -funktioner.

Listehandlinger

Testmedlemskab for listehandlinger, adgangselementer og målingslistelængde.

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

Listeprædikatfunktioner returnerer TRUE, FALSE, eller UNKNOWN ifølge filterresultaterne. For en tom liste, ALL og NONE returner TRUE, mens ANY og SINGLE returnerer FALSE. En null-kilde liste returnerer UNKNOWN.

Elementbindingen er lokal i forhold til filteret og kan skygge en ydre variabel. Aggregater over den lokale binding og EXISTS subforespørgsler inde i filteret understøttes ikke.

For mere information, se Liste prædikatfunktioner.

Egenskabsadgang

Egenskabsadgang henter værdien af en egenskab fra en node eller kant.

n.firstName                      -- Property access

Du kan få flere oplysninger om egenskabsadgang i GQL-udtryk og -funktioner.

Functions

Brug indbyggede funktioner til at transformere værdier, inspicere grafelementer og aggregere rækker.

Numeriske funktioner

Numeriske funktioner beregner numeriske værdier eller producerer heltalsintervaller.

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

Andre understøttede trigonometriske funktioner er TAN, COT, , ATAN, SINH, COSH, og TANH. Bortset fra og ABSRANGE, returnerer DOUBLEdisse numeriske funktioner .

Lær mere om numeriske funktioner i GQL-udtryk og -funktioner.

Aggregeringsfunktioner

Aggregeringsfunktioner beregner oversigtsværdier for grupper af rækker (lodret aggregering) eller over elementerne på en gruppeliste (vandret sammenlægning).

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

Uden at gruppere kolonner returnerer 0 en aggregeret forespørgsel uden inputrækker for COUNT, en tom liste for COLLECT_LIST og COLLECT_ELEMENTS, og en nul for SUM, AVG, MIN, MAX, og COLLECT_ONE. Et gruppelisteargument gør aggreget horisontalt.

Få mere at vide om aggregeringsfunktioner i GQL-udtryk og -funktioner.

Streng funktioner

Med strengfunktioner kan du arbejde med og analysere strengværdier.

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ønstre, erstatninger og muligheder skal være bogstavelige. For signaturer, flag og null-adfærd, se Strengfunktioner.

Listefunktioner

Med listefunktioner kan du arbejde med lister, f.eks. kontrol af længde eller justeringsstørrelse.

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

Du kan få flere oplysninger om listefunktioner under GQL-udtryk og -funktioner.

Graf funktioner

Med graffunktioner kan du få oplysninger fra noder, stier og 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

Du kan få flere oplysninger om graffunktioner under GQL-udtryk og -funktioner.

Tidsmæssige funktioner

Med tidsmæssige funktioner kan du arbejde med dato- og klokkeslætsværdier.

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

Du kan få flere oplysninger om tidsmæssige funktioner under GQL-udtryk og -funktioner.

Generiske funktioner

Generiske funktioner gør det muligt at arbejde med data på almindelige måder.

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

Du kan få flere oplysninger om generiske funktioner under GQL-udtryk og -funktioner.

Opgaveorienterede eksempler

Brug vejledningsartiklerne, når du har brug for komplette, klar-til-at-tilpasse forespørgselsmønstre:

Relateret indhold

  • Sidst opdateret den