Bemærk
Adgang til denne side kræver godkendelse. Du kan prøve at logge på eller ændre mapper.
Adgang til denne side kræver godkendelse. Du kan prøve at ændre mapper.
Notat
Denne funktion er i øjeblikket tilgængelig som offentlig prøveversion. Denne prøveversion leveres uden en serviceniveauaftale og anbefales ikke til produktionsarbejdsbelastninger. Visse funktioner understøttes muligvis ikke eller kan have begrænsede funktioner. Du kan finde flere oplysninger under Supplerende vilkår for anvendelse af Microsoft Azure Previews.
GQL Graph Query Language er det ISO-standardiserede forespørgselssprog for grafdatabaser. Det hjælper dig med at forespørge og arbejde effektivt med grafdata.
GQL udvikles af den samme ISO-arbejdsgruppe, der standardiserer SQL og sikrer konsistens og stringens. Hvis du er bekendt med SQL, vil du finde mange ligheder i GQL (udtryk, prædikater, typer) – hvilket gør det nemmere at komme i gang. Denne vejledning hjælper både nybegyndere med at lære GQL fundamentals og erfarne brugere, der søger avancerede teknikker og omfattende referenceoplysninger.
Notat
Den officielle internationale standard for GQL er ISO/IEC 39075 Information Technology - Database Languages - GQL.
Forudsætninger
Før du dykker ned i GQL, skal du være fortrolig med disse begreber:
- Grundlæggende forståelse af databaser – Erfaring med ethvert databasesystem (såsom relationel (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 som filtrering, sortering og sammenlægning
Anbefalet baggrund:
- Erfaring med SQL eller openCypher-sprog gør det lettere 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 skal du bruge:
- Adgang til Microsoft Fabric med graffunktioner
- Eksempeldata eller vilje 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 udviklet specielt til grafdata. Det gør det naturligt og intuitivt at arbejde med forbundne oplysninger.
I modsætning til SQL, som er afhængig af tabeljoins for at udtrykke relationer, bruger GQL visuelle grafmønstre, som direkte spejler, hvordan entiteter er forbundet, hvilket gør forespørgsler lettere at læse og ræsonnere om.
Lad os sige, at du vil finde folk og deres venner (folk, der kender hinanden), som begge er født før 1999. Sådan udtrykker GQL det ved hjælp af et visuelt grafmønster:
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
Denne forespørgsel finder venner (personer, der kender hinanden), som begge er født før 1999. Mønsteret (person:Person)-[:knows]-(friend:Person) viser visuelt den relationsstruktur, du leder efter – på samme måde som at tegne et diagram over dine data.
Grundlæggende om GQL
Før du dykker ned i forespørgsler, skal du forstå disse kernebegreber, der udgør grundlaget for GQL:
- Grafer gemmer dine data som noder (entiteter) og kanter (relationer), hver med etiketter og egenskaber
- Graftyper fungerer som skemaer og definerer, hvilke noder og kanter der kan findes i din graf
- Begrænsninger er yderligere regler og restriktioner, som graftyper pålægger grafer for at sikre dataintegritet
-
Forespørgsler bruger sætninger som
MATCH,FILTERogRETURNtil at behandle data og vise resultater - Mønstre beskriver de grafstrukturer, du vil finde ved hjælp af intuitiv visuel syntaks
- Udtryk udfører beregninger og sammenligninger på dine data på samme måde som SQL-udtryk
- Prædikater er booleske værdiudtryk, der bruges til at filtrere resultater inden for forespørgsler
- Værdityper definerer, hvilke typer værdier du kan behandle og gemme
Om grafdata
Hvis du vil arbejde effektivt med GQL, skal du forstå, hvordan grafdata er struktureret. Dette fundament hjælper dig med at skrive bedre forespørgsler og udforme dine data effektivt.
Noder og kanter: byggestenene
I GQL arbejder du med navngivne egenskabsgrafer. En graf består af to typer elementer:
Noder repræsenterer typisk enhederne ("navneord") i dit system – f.eks. personer, organisationer, indlæg eller produkter. De er uafhængige objekter, der findes i dit domæne. Noder kaldes også også knudepunkter.
Kanter repræsenterer relationer mellem objekter ("verber")– hvordan dine objekter opretter forbindelse og interagerer.
For eksempel kender folk hinanden (:knows), organisationer, der opererer i specifikke regioner (:operates), eller kunder, der har købt produkter (:purchased).
Kanter kaldes også også relationer.
Hvert grafelement har følgende egenskaber:
- Et internt id , der entydigt identificerer det
-
Et eller flere navne – beskrivende navne som
Personellerknows. I Microsoft Fabric har grafkanter altid præcis én label. -
Egenskaber—navn-værdi-par, der gemmer data om elementet (såsom
firstName: "Alice"ellerbirthday: "19730108").
Sådan struktureres grafer
Hver kant forbinder præcis to noder: en kilde og en destination. Denne forbindelse opretter grafens struktur og viser, hvordan objekter er relateret til hinanden. Kanternes retning betyder noget – en hvem Person en follows anden Person opretter en direkte relation.
Notat
Graph i Microsoft Fabric understøtter i øjeblikket ikke urettede kanter.
Egenskabsgrafer, som understøttes i Microsoft Fabric, er altid veludviklede, hvilket betyder, at hver kant forbinder to gyldige noder. Hvis du kan se en kant i en graf, findes begge slutpunkterne i den samme graf.
Grafmodeller og graftyper
Strukturen af en graf i Microsoft Fabric er beskrevet af dens grafmodel, som fungerer som et databaseskema for dit programdomæne. Grafmodeller definerer:
- Hvilke noder og kanter kan findes
- Hvilke mærkater og egenskaber de kan have
- Sådan kan noder og kanter forbindes
Grafmodeller sikrer også dataintegritet gennem begrænsninger, især nodenøglebegrænsninger , der angiver, hvilke egenskaber der entydigt identificerer hver node.
Notat
Grafmodeller kan angives ved hjælp af GQL-standardsyntaks, i hvilket tilfælde de kaldes graftyper.
Et praktisk eksempel: socialt netværk
I hele denne dokumentation bruger vi et eksempel på sociale netværk til at illustrere GQL-koncepter. Hvis du forstår dette domæne, kan du følge eksemplerne og anvende lignende mønstre på dine egne data.
Notat
Det sociale netværk er et eksempel, der er afledt af LDBC SNB (LDBC Social Network Benchmark), der er udgivet af GDC (Graph Data Council). Se artiklen "The LDBC Social Network Benchmark" for at få flere oplysninger.
Enhederne på det sociale netværk
Vores sociale netværk omfatter disse primære typer noder, der repræsenterer objekter i domænet:
Folk har personlige oplysninger som navne, fødselsdage og køn. De bor i byer og danner sociale forbindelser.
Steder udgør et geografisk hierarki:
- Byer som "New York" eller "London"
- Lande/områder som "USA" eller "Storbritannien"
- Kontinenter som "Nordamerika" eller "Europa"
Organisationer , hvor folk bruger tid:
- Universiteter , hvor folk studerer
- Virksomheder , hvor folk arbejder
Indhold og diskussioner:
- Forummer med titler, der indeholder indlæg
- Indlæg med indhold, sprog og valgfri billeder
- Kommentarer , der besvarer indlæg eller andre kommentarer
- Mærker , der kategoriserer indhold og repræsenterer interesser
Sådan opretter alt forbindelse
Forbindelserne mellem enheder gør netværket interessant:
- Folk kender hinanden (venskaber,
:knows) - Folk arbejder i virksomheder (
:workAt) eller studerer på universiteter (:studyAt) - Folk laver opslag og kommentarer (
:hasCreator) - Folk kan lide opslag og kommentarer (
:likes) - Indlæg, fora, kommentarer kan have tags (
:hasTag) - Folk har interesser i specifikke tags (
:hasInterest) - Fora indeholder indlæg (
:containerOf) og har medlemmer (:hasMember) og moderatorer (:hasModerator)
Grafkanter repræsenterer domænerelationer. Dette omfattende netværk skaber mange muligheder for interessante forespørgsler og analyser.
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
Lad os begynde med den mest grundlæggende forespørgsel muligt, find navnene (fornavn, efternavn) på alle personer i:Person grafen.
MATCH (p:Person)
RETURN p.firstName, p.lastName
Denne forespørgsel udføres som følger:
-
MATCHfinder alle noder, der er forsynet med mærkaterPerson -
RETURNviser deres for- og efternavne
Tilføj filtrering: Find bestemte personer
Lad os nu finde folk med specifikke karakteristika, i dette tilfælde alle ved navn Alice, og vise deres navne og fødselsdage.
MATCH (p:Person)
FILTER p.firstName = 'Annemarie'
RETURN p.firstName, p.lastName, p.birthday
Denne forespørgsel udføres som følger:
-
MATCHfinder alle noder (p) mærket Person -
FILTERnoder (p) hvis fornavn er Alice -
RETURNviser 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 udføres som følger:
-
MATCHfinder alle nodeparPerson, der kender hinanden -
FILTERholder kun de par, hvor begge personer har samme fødselsdag -
RETURNtæller, hvor mange sådanne vennepar der findes
Tips
Filtrering kan også udføres direkte som en del af et mønster ved at tilføje en WHERE delsætning.
Vil f.eks MATCH (n:Person WHERE n.age > 23) . kun matche Person noder, hvis age egenskab er større end 23.
Notat
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. -
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. -
OFFSETogLIMIT: 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.
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.
- Dette skaber en klar, forudsigelig datastrøm, der forenkler komplekse forespørgsler.
Vigtigt
Internt kan udførelsen af statements omarrangeres, og individuelle statements kan udføres parallelt af Microsoft Fabric for at maksimere ydeevnen. Dette vil dog ikke påvirke korrektheden af resultaterne.
Eksempel
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 udføres som følger:
-
MATCHfinder folk, der arbejder i virksomheder med "Air" i deres navn -
LETopretter fulde navne ved at kombinere for- og efternavne -
FILTERholder kun Contoso-medarbejdere -
ORDER BYsorterer efter fuldt navn -
LIMITtager de første 10 resultater -
RETURNReturneringer, navne og virksomhedsplaceringer
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.
Variabler kan kategoriseres 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 (se Avancerede sammenlægningsteknikker)
Udførelsesresultater og -resultater
Når du kører en forespørgsel, får du et udførelsesresultat tilbage, der består af:
-
En (valgfri) resultattabel med dataene fra din
RETURNsætning. - 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
I tilfælde af udførelsesfejl medtages der ingen resultattabel i udførelsesresultatet.
Statusoplysninger
Der registreres forskellige bemærkelsesværdige betingelser (f.eks. fejl eller advarsler) under udførelsen af forespørgslen. Hver af disse betingelser registreres af et statusobjekt i statusoplysningerne for udførelsesresultatet.
Statusoplysningerne består af et primært statusobjekt og en (muligvis tom) liste over yderligere statusobjekter. Det primære statusobjekt er altid til stede og angiver, om udførelsen af forespørgslen lykkedes eller mislykkedes.
Hvert statusobjekt indeholder en 5-cifret statuskode (kaldet GQLSTATUS), der identificerer den registrerede betingelse samt en meddelelse, der beskriver den.
Statuskoder for vellykkede handlinger:
| GQLSTATUS | Meddelelse | Når |
|---|---|---|
| 00000 | Bemærk! fuldførelse er fuldført | Udført med mindst én række |
| 00001 | Bemærk! fuldført - udeladt resultat | Udført uden tabel (bruges i øjeblikket) |
| 02000 | Bemærk! ingen data | Succes med nul rækker |
Andre statuskoder angiver yderligere fejl eller advarsler, der blev registreret under udførelse af forespørgsler.
Vigtigt
I programkoden skal du altid være afhængig af statuskoder for at teste for visse betingelser. Statuskoder er garanteret at være stabile, og deres generelle betydning ændres ikke i fremtiden. Test ikke indholdet af beskeder, da den konkrete besked, der rapporteres for en statuskode, kan ændre sig i fremtiden afhængigt af forespørgslen eller endda mellem udførelser af den samme forespørgsel.
Derudover kan statusobjekter indeholde et underliggende årsagsstatusobjekt og en diagnosticeringspost med yderligere oplysninger, der karakteriserer den registrerede betingelse.
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
Grafmønstre er kernen i GQL-forespørgsler. De giver dig mulighed for at beskrive den datastruktur, du leder efter, ved hjælp af intuitiv visuel syntaks, der ligner de relationer, du vil finde.
Enkle mønstre:
Start med grundlæggende relationsmønstre:
-- Find direct friendships
(p:Person)-[:knows]->(f:Person)
-- Find people working at any company
(p:Person)-[:workAt]->(c:Company)
-- Find cities in any country/region
(ci:City)-[:isPartOf]->(co:Country)
Mønstre med bestemte data:
-- Find who works at Microsoft specifically
(p:Person)-[:workAt]->(c:Company)
WHERE p.firstName = 'Annemarie'
-- Find friends who are both young
(p:Person)-[:knows]->(f:Person)
WHERE p.birthday > 19950101 AND f.birthday > 19950101
Navneudtryk for fleksibelt objektvalg:
(:Person|Company)-[:isLocatedIn]->(p:City|Country) -- OR with |
(:Place&City) -- AND with &
(:Person&!Company) -- NOT with !
Notat
Grafmodeller med flere elementetiketter understøttes endnu ikke (kendt problem).
Med mærkatudtryk kan du matche forskellige typer noder i et enkelt mønster, hvilket gør dine forespørgsler mere fleksible.
Genbrug af variabler opretter effektive joinforbindelser:
-- Find coworkers: people who work at the same company
(c:Company)<-[:workAt]-(x:Person)-[:knows]-(y:Person)-[:workAt]->(c)
Genbrug af variabel c sikrer, at begge personer arbejder i det samme firma og opretter en automatisk joinforbindelsesbegrænsning. Dette mønster er et nøglemønster til at udtrykke "samme objekt"-relationer.
Vigtigt
Kritisk indsigt: Variabel genbrug i mønstre skaber strukturelle begrænsninger. Denne teknik er den måde, du udtrykker komplekse grafrelationer som "venner, der arbejder i samme virksomhed" eller "personer i samme by"
Filtrering på mønsterniveau med WHERE:
-- Filter during pattern matching (more efficient)
(p:Person WHERE p.birthday < 19940101)-[:workAt]->(c:Company WHERE c.id > 1000)
-- Filter edges during matching
(p:Person)-[w:workAt WHERE w.workFrom >= 2000]->(c:Company)
Afgrænsede mønstre med variabel længde:
(:Person)-[:knows]->{1,3}(:Person) -- Friends up to 3 degrees away
TRAIL-mønstre for cyklusfri gennemløb:
Brug TRAIL mønstre til at forhindre cyklusser under grafløb, så det sikres, at hver kant besøges højst én gang:
-- Find paths without visiting the same :knows edge twice
MATCH TRAIL (src:Person)-[:knows]->{1,4}(dst:Person)
WHERE src.firstName = 'Alice' AND dst.firstName = 'Bob'
RETURN count(*) AS num_connections
-- Find acyclic paths in social networks
MATCH TRAIL (p:Person)-[e:knows]->{,3}(celebrity:Person)
RETURN
p.firstName || ' ' || p.lastName AS person_name,
celebrity.firstName || ' ' || celebrity.lastName AS celebrity_name,
count(e) AS distance
LIMIT 1000
Kantbinding med variabel længde:
I mønstre med variabel længde henter kantvariabler forskellige oplysninger baseret på kontekst:
-- Edge variable 'e' binds to a single edge for each result row
MATCH (p:Person)-[e:knows]->(friend:Person)
RETURN p.firstName, e.creationDate, friend.firstName -- e refers to one specific relationship
LIMIT 1000
-- Edge variable 'e' binds to a group list of all edges in the path
MATCH (p:Person)-[e:knows]->{2,4}(friend:Person)
RETURN
p.firstName || ' ' || p.lastName AS person_name,
friend.firstName || ' ' || friend.lastName AS friend_name,
-- e is a list
size(e) AS num_edges
LIMIT 1000
Denne skelnen er afgørende for korrekt brug af kantvariabler.
Komplekse mønstre med flere relationer:
MATCH (p:Person), (p)-[:workAt]->(c:Company), (p)-[:isLocatedIn]->(city:City)
RETURN p.firstName, p.lastName, c.name AS company_name, city.name AS city_name
LIMIT 1000
Dette mønster finder personer sammen med både deres arbejdsplads og bopæl, der viser, hvordan en person opretter forbindelse til flere andre enheder.
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, der forbinder inputvariabler med mønstervariabler og skriver alle matchende 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 med WHERE:
-- Filter pattern matches
MATCH (p:Person)-[:workAt]->(c:Company) WHERE p.lastName = c.name
Alle forekomster kan efterfiltreres ved hjælp af WHERE, så du undgår en separat FILTER sætning.
Sammenføjning med 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
Graph i Microsoft Fabric understøtter endnu ikke sammensætning af vilkårlige udsagn. Se 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 (ingen joinforbindelser til venstre/højre)
-
Filtreringsrækkefølge: Filtre på sætningsniveau
WHERE, når mønstermatch er fuldført - Mønsterforbindelse: Flere mønstre skal dele mindst én variabel for korrekt sammenføjning
- Ydeevne: Delte variabler opretter effektive joinforbindelser
Vigtigt
Begrænsning: Hvis dette MATCH ikke er den første sætning, skal mindst én inputvariabel forbindes med en mønstervariabel. Flere mønstre skal have én variabel til fælles.
Flere mønstre kræver 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)
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:
- Udtryk evalueres 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
LETevalueres parallelt (ingen krydsreferencer)
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, '127.0.0.1') STARTS WITH '127.0.0'- der blev ikke oprettet forbindelse fra det lokale netværk -
Kombiner betingelser: Bruges
AND/ORsammen 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 ], <expression> [ ASC | DESC ], ...
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:
ORDER BY coalesce(p.gender, 'not specified') DESC -- Treat NULL as 'not specified'
Oplysninger om funktionsmåde for sortering:
Om, hvordan ORDER BY fungerer:
- Evaluering af udtryk: Udtryk evalueres for hver række, og resultaterne bestemmer derefter rækkerækkefølgen
- Flere sorteringsnøgler: Opret hierarkisk sortering (primær, sekundær, tertiær osv.)
-
Null-håndtering:
NULLbehandles altid som den mindste værdi i sammenligninger -
Standardrækkefølge:
ASC(stigende) er standard,DESC(faldende) skal angives eksplicit - Beregnet sortering: Du kan sortere efter beregnede værdier og ikke kun gemte egenskaber
Advarsel
Den sorteringsrækkefølge, der er oprettet af ORDER BY , er kun synlig for følgende sætning med det samme .
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 */
Dette har øjeblikkelige konsekvenser for "Top-k"-forespørgsler: LIMIT Skal altid følge den ORDER BY sætning, der oprettede 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 ], <expression> [ ASC | DESC ], ... ]
[ 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 med 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 companyName = c.name
RETURN companyName,
count(*) AS employeeCount,
avg(p.birthday) AS avg_birth_year
GROUP BY 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
Du kan se avancerede sammenlægningsteknikker, herunder vandret aggregering over mønstre med variabel længde, under Avancerede sammenlægningsteknikker.
Datatyper: Arbejde med værdier
GQL understøtter omfattende datatyper til lagring og manipulation af forskellige typer oplysninger i din graf.
Grundlæggende værdityper:
-
Tal:
INT64,UINT64,DOUBLEtil beregninger og målinger -
Tekst:
STRINGfor navne, beskrivelser og tekstdata -
Logik:
BOOLmed tre værdier: TRUE, FALSE og UNKNOWN (til håndtering af null) -
Klokkeslæt:
ZONED DATETIMEfor tidsstempler med tidszoneoplysninger -
Samlinger:
LIST<T>for flere værdier af samme typeT,PATHfor grafgennemløbsresultater -
Grafelementer:
NODEogEDGEtil at referere til grafdata
Vigtigt
Visse værdityper understøttes ikke som ejendomsværdityper. Især kan alle værdier, der involverer grafelement-referenceværdier, ikke bruges som egenskabsværdier (såsom lister over noder eller stier).
Eksempel på konstanter:
42 -- Integer literal
"Hello, graph!" -- String literal
TRUE -- Boolean literal
ZONED_DATETIME('2024-01-15T10:30:00Z') -- DateTime with timezone literakl
[1, 2, 3] -- Literal list of integers
Kritiske null-håndteringsmønstre:
-- Equality predicates with NULL always returns UNKNOWN
5 = NULL -- Evaluates to UNKNOWN (not FALSE!)
NULL = NULL -- Evaluates to UNKNOWN (not TRUE!)
-- Use IS NULL predicates for explicit null testing
p.nickname IS NULL -- Evaluates to TRUE if nickname is null
p.nickname IS NOT NULL -- Evaluates to TRUE if nickname has a value
-- Use the COALESCE function for null-safe value selection
coalesce(p.nickname, p.firstName, '???') -- Evaluates to first non-null value
Konsekvenser for logik med tre værdier:
-- In FILTER statements, only TRUE values pass through
FILTER p.birthday > 0 -- Removes rows where birthday is null or missing or zero
-- It's important to understand that NOT UNKNOWN = UNKNOWN
FILTER NOT (p.birthday > 0) -- Removes rows where birthday is null or missing or positive
-- Use explicit null handling for inclusive filtering
FILTER p.birthday < 19980101 OR p.birthday IS NULL -- Includes null birthdays
Advarsel
Logik med tre værdier betyder NULL = NULL returnerer UNKNOWN, ikke TRUE. Denne funktionsmåde påvirker filtrering og joinforbindelser.
IS NULL Brug altid til null-test.
Udtryk: Transformering og analyse af data
Med udtryk kan du beregne, sammenligne og transformere data i dine forespørgsler. De ligner udtryk i SQL, men har ekstra funktioner til håndtering af grafdata.
Almindelige udtrykstyper:
p.birthday < 19980101 -- Birth year comparison
p.firstName || ' ' || p.lastName -- String concatenation
count(*) -- Aggregation
p.firstName IN ['Alice', 'Bob'] -- List membership
coalesce(p.firstName, p.lastName) -- Null handling
Kompleks prædikatkomposition:
-- Combine conditions with proper precedence
FILTER (p.birthday > 19560101 AND p.birthday < 20061231)
AND ((p.gender IN ['male', 'female']) OR (p.browserUsed IS NOT NULL))
-- Use parentheses for clarity and correctness
FILTER p.gender = 'female' AND (p.firstName STARTS WITH 'A' OR p.id > 1000)
Matchende strengmønster:
-- Pattern matching with different operators
p.locationIP CONTAINS '192.168' -- Substring search
p.firstName STARTS WITH 'John' -- Prefix matching
p.lastName ENDS WITH 'son' -- Suffix matching
-- Case-insensitive operations
upper(p.firstName) = 'ALICE' -- Convert to uppercase for comparison
Indbyggede funktioner efter kategori:
GQL indeholder disse funktionskategorier til forskellige databehandlingsbehov:
-
Aggregeringsfunktioner:
count(),sum(),avg(),min()tilmax()opsummering af data -
Strengfunktioner:
char_length(),upper(),lower(),trim()til tekstbehandling -
Graffunktioner:
nodes(),edges()tillabels()analyse af grafstrukturer -
Generelle funktioner:
coalesce()Til håndtering af null-værdier på en elegant måde
Operatorrækkefølge for komplekse udtryk:
- Egenskabsadgang (
.) - Multiplikation/division (
*,/) - Addition/Subtraktion (
+,-) - Sammenligning (
=,<>,<,>,<=)>= - Logisk negation (
NOT) - Logisk konjunktion (
AND) - Logisk fjernelse (
OR)
I ovenstående liste "binder en operator med lavere tal" mere end en operator med et højere tal.
Eksempel: NOT n.prop OR m.prop er (NOT n.prop) OR m.prop men ikke 'IKKE (n.prop ELLER m.prop)
Tips
Brug parenteser til at gøre prioritet eksplicit. Komplekse udtryk er nemmere at læse og foretage fejlfinding af, når gruppering er ryddet.
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 sammensætning med flere udsagn
Vigtigt
Graph i Microsoft Fabric understøtter endnu ikke sammensætning af vilkårlige udsagn. Se artiklen om aktuelle begrænsninger.
Det er afgørende for avanceret grafforespørgsler, hvordan du opretter komplekse forespørgsler effektivt.
Forløb af mønster med flere trin:
-- Build complex analysis step by step
MATCH (company:Company)<-[:workAt]-(employee:Person)
LET companyName = company.name
MATCH (employee)-[:isLocatedIn]->(city:City)
FILTER employee.birthday < 19850101
LET cityName = city.name
RETURN companyName, cityName, avg(employee.birthday) AS avgBirthday, count(employee) AS employeeCount
GROUP BY companyName, cityName
ORDER BY avgBirthday DESC
Denne forespørgsel opbygger gradvist kompleksitet: find virksomheder, deres medarbejdere, medarbejderlokationer, filtrer virksomheder med medarbejdere født før 1985, beregne gennemsnitlig fødselsdato og opsummere og sortere resultater.
Brug af vandret aggregering:
-- Find people and their minimum distance to people working at Microsoft
MATCH TRAIL (p:Person)-[e:knows]->{,5}(:Person)-[:workAt]->(:Company { name: 'Microsoft'})
LET p_name = p.lastName || ', ' || p.firstName
RETURN p_name, min(count(e)) AS minDistance
GROUP BY p_name
ORDER BY minDistance DESC
Notat
Denne forespørgsel understøttes endnu ikke (kendt problem).
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 fullNume
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 new variable for managed employee
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.
Avancerede sammenlægningsteknikker
GQL understøtter to forskellige typer sammenlægninger til analyse af data på tværs af grupper og samlinger: lodret aggregering med GROUP BY og vandret aggregering over mønstre med variabel længde.
Lodret sammenlægning med GRUPPÉR EFTER
Lodret sammenlægning (dækket medRETURNGROUP BY) grupperer rækker efter delte værdier og beregner aggregeringer i hver gruppe:
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN c.name AS companyName,
count(*) AS employee_count,
avg(p.birthday) AS avg_birth_year
GROUP BY companyName
Denne fremgangsmåde opretter én resultatrække pr. firma og aggregerer alle medarbejdere i hver gruppe.
Vandret sammenlægning med grupperingslistevariabler
Vandret aggregering beregner samlinger over samlinger, der er bundet af mønstre med variabel længde. Når du bruger kantkanter med variabel længde, bliver kantvariablen en gruppelistevariabel , der indeholder alle kanter i hver tilsvarende sti:
-- Group list variable 'edges' enables horizontal aggregation
MATCH (p:Person)-[edges:knows]->{2,4}(friend:Person)
RETURN p.firstName || ' ' || p.lastName AS person_name,
friend.firstName || ' ' || friend.lastName AS friend_name,
size(edges) AS degrees_of_separation,
avg(edges.creationDate) AS avg_connection_age,
min(edges.creationDate) AS oldest_connection
Notat
Denne forespørgsel understøttes endnu ikke (kendt problem).
Vigtige forskelle:
- Lodret sammenlægning opsummerer på tværs af rækker – eller – grupperer rækker og opsummerer på tværs af rækker i hver gruppe
- Vandret aggregering opsummerer elementer i individuelle kantsamlinger
- Gruppelistevariabler kommer kun fra kantmønstre med variabel længde
Kontekster for kantbinding med variabel længde
Det er afgørende at forstå, hvordan kantvariabler bindes i mønstre med variabel længde:
Under matchning af mønster (enkelttonkontekst):
-- Edge variable 'e' refers to each individual edge during filtering
MATCH (p:Person)-[e:knows WHERE e.creationDate > zoned_datetime('2000-01-01T00:00:00Z')]->{2,4}(friend:Person)
-- 'e' is evaluated for each edge in the path during matching
RETURN *
I resultatudtryk (gruppekontekst):
-- Edge variable 'edges' becomes a list of all qualifying edges
MATCH (p:Person)-[e:knows]->{2,4}(friend:Person)
RETURN size(e) AS num_edges, -- Number of edges in path
e[0].creationDate AS first_edge, -- First edge in path
avg(e.creationDate) AS avg_age -- Horizontal aggregation
Notat
Denne forespørgsel understøttes endnu ikke (kendt problem).
Kombination af lodret og vandret sammenlægning
Du kan kombinere begge sammenlægningstyper i avancerede analysemønstre:
-- Find average connection age by city pairs
MATCH (p1:Person)-[:isLocatedIn]->(c1:City)
MATCH (p2:Person)-[:isLocatedIn]->(c2:City)
MATCH (p1)-[e:knows]->{1,3}(p2)
RETURN c1.name AS city1,
c2.name AS city2,
count(*) AS connection_paths, -- Vertical: count paths per city pair
avg(size(e)) AS avg_degrees, -- Horizontal then vertical: path lengths
avg(avg(e.creationDate)) AS avg_connection_age -- Horizontal then vertical: connection ages
GROUP BY city1, city2
Notat
Denne forespørgsel understøttes endnu ikke (kendt problem).
Tips
Vandret aggregering har altid forrang frem for lodret sammenlægning. Hvis du vil konvertere en gruppeliste til en almindelig liste, skal du bruge collect_list(edges).
Notat
Du kan finde en detaljeret reference til aggregeringsfunktioner under GQL-udtryk og -funktioner.
Fejlhåndteringsstrategier
Hvis du forstår almindelige fejlmønstre, kan du skrive robuste forespørgsler.
Håndter manglende data på en elegant måde:
MATCH (p:Person)
-- Use COALESCE for missing properties
LET displayName = coalesce(p.firstName, p.lastName, 'Unknown')
LET contact = coalesce(p.locationIP, p.browserUsed, 'No info')
RETURN *
Brug eksplicitte null-kontroller:
MATCH (p:Person)
-- Be explicit about null handling
FILTER p.id IS NOT NULL AND p.id > 0
-- Instead of just: FILTER p.id > 0
RETURN *
Flere oplysninger
GQLSTATUS-koder
Som forklaret i afsnittet om forespørgselsresultater rapporterer GQL omfattende statusoplysninger, der er relateret til, om udførelsen lykkedes eller mislykkedes. Se referencen til GQL-statuskoder for at få en komplet liste.
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
Nu, hvor du forstår de grundlæggende GQL-elementer, er her dit anbefalede læringsforløb:
Fortsæt med at opbygge dine GQL-færdigheder
For begyndere:
- Prøv den hurtige introduktion – Følg vores praktiske selvstudium for at få praktisk erfaring
- Øv dig i grundlæggende forespørgsler – Prøv eksemplerne fra denne vejledning med dine egne data
- Få mere at vide om grafmønstre – Master den omfattende mønstersyntaks
- Udforsk datatyper – Forstå GQL-værdier og værdityper
For erfarne brugere:
- Avancerede udtryk – GQL-masterudtryk og -funktioner
- Skemadesign – Få mere at vide om GQL-graftyper og -begrænsninger
- Udforsk datatyper – Forstå GQL-værdier og værdityper
Referencematerialer
Hold disse referencer praktiske til hurtige opslag:
- Hurtig reference til GQL – Hurtig reference til syntaks
- GQL-statuskoder – Komplet reference til fejlkode
- Reserverede GQL-ord – Komplet liste over reserverede nøgleord
Udforsk Microsoft Fabric
Få mere at vide om platformen:
- Grafdatamodeller – Om grafbegreber og modellering
- Graph vs. relationsdatabaser – Vælg den rigtige fremgangsmåde
- Prøv Microsoft Fabric gratis – Få praktisk erfaring
- Komplette selvstudier – Komplette læringsscenarier
Bliv involveret
- Del feedback – Hjælp med at forbedre vores dokumentation og værktøjer
- Deltag i community'et – Opret forbindelse til andre brugere af grafdatabaser
- Hold dig opdateret – Følg Microsoft Fabric-meddelelser om nye funktioner
Tips
Start med selvstudiet hurtig start , hvis du foretrækker at lære ved at gøre det, eller gå i dybden med grafmønstre , hvis du vil mestre forespørgselssproget først.
Relateret indhold
Yderligere oplysninger om vigtige emner:
- Eksempel på skema på sociale netværk – Komplet arbejdseksempel på grafskema
- GQL-grafmønstre – Omfattende mønstersyntaks og avancerede matchningsteknikker
- GQL-udtryk og -funktioner – alle udtrykstyper og indbyggede funktioner
- GQL-graftyper – Graftyper og -begrænsninger
- GQL-værdier og værdityper – Komplet systemreference og værdihåndtering
Hurtig referencer:
- GQL-forkortet reference – Hurtig syntakshenvisning
- GQL-statuskoder – Komplet reference til fejlkode
- Reserverede GQL-ord – Komplet liste over reserverede nøgleord
Graph i Microsoft Fabric:
- Grafdatamodeller – Om grafbegreber og modellering
- Graf- og relationsdatabaser – forskelle, og hvornår de skal bruges
- Prøv Microsoft Fabric gratis
- Komplette selvstudier i Microsoft Fabric