Szybka dokumentacja języka GQL

Ten artykuł zawiera krótkie informacje dotyczące składni języka GQL (Graph Query Language) dla grafu w usłudze Microsoft Fabric. Używaj go do przypomnienia sobie składni i domyślnych ustawień. Szczegółowe wyjaśnienie można znaleźć w przewodniku językowym GQL; każda sekcja łączy się z wyspecjalizowanym źródłem informacji, który posiada pełne szczegóły.

Uwaga / Notatka

W tym artykule używany jest przede wszystkim przykładowy zestaw danych grafu w sieci społecznościowej. Zawiera również kilka przykładów, które korzystają z zestawu danych Adventure Works z samouczka grafu.

Struktura zapytań

Zapytania GQL używają sekwencji instrukcji definiujących dane do pobrania z grafu, sposobu ich przetwarzania i sposobu wyświetlania wyników. Każda instrukcja ma określony cel i razem tworzą potok liniowy, który pasuje do danych z grafu i przekształca je krok po kroku.

Typowy przepływ zapytań:
Zapytanie GQL zwykle rozpoczyna się od określenia wzorca grafu do dopasowania. Następnie używa opcjonalnych instrukcji do tworzenia zmiennych, filtrowania, sortowania, stronicowania i danych wyjściowych wyników.

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

Skład oświadczenia:

Ważne

Instrukcje tworzą uporządkowany pipeline i nie można ich dowolnie przestawiać. Zobacz artykuł dotyczący bieżących ograniczeń.

  • MATCH — Określ wzorce grafu do znalezienia.
  • LET — Zdefiniuj zmienne z wyrażeń.
  • FOR – Rozwiń listę do wierszy.
  • CALL – Uruchom podzapytanie w linii i dodaj jego zwrócone kolumny.
  • FILTER — Zachowaj dopasowywanie wierszy do warunków.
  • WHEN – Kieruj każdy wiersz wejściowy do pierwszej dopasowanej gałęzi warunkowej.
  • ORDER BY — Sortuj wyniki.
  • OFFSET — Pomiń wiele wierszy.
  • LIMIT — ogranicz liczbę wierszy.
  • RETURN — Wyprowadza końcowe wyniki.
  • NEXT – Rozpocznij kolejny etap zapytania, używając kolumn zwróconych przez poprzedni etap.

Każda instrukcja opiera się na poprzednim, więc stopniowo uściślisz i kształtujesz dane wyjściowe zapytania. Użyj UNION, UNION DISTINCT, lub UNION ALL do połączenia pełnych bloków zapytań. Aby uzyskać więcej informacji na temat każdej instrukcji, zobacz następujące sekcje.

Wyrażenia zapytania

MATCH

Znajdź wzorce grafu w danych.

Składnia:

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

Example:

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

Aby uzyskać więcej informacji na temat instrukcji MATCH , zobacz Wzorce programu Graph.

POZWALAĆ

Tworzenie zmiennych przy użyciu wyrażeń.

Składnia:

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

Example:

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

Aby uzyskać więcej informacji na temat instrukcji LET , zobacz przewodnik języka GQL.

FOR

Rozszerza listę na wiersze i opcjonalnie zwraca pozycję każdego elementu.

Składnia:

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 zaczyna się od 0. WITH ORDINALITY zaczyna się od 1.

Aby uzyskać więcej informacji na temat instrukcji FOR , zobacz przewodnik języka GQL.

CALL

Uruchamia podzapytanie wpisowe dla każdego wiersza wejściowego. Zmienne już znajdujące się w zakresie są domyślnie dostępne wewnątrz podzapytania.

Składnia:

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

Spośród zmiennych utworzonych wewnątrz podzapytania, tylko kolumny z RETURN jego końcowego zapytania są dostępne poza nim. Ordinary CALL pomija zewnętrzny wiersz, gdy podzapytanie nie zwraca wierszy, a mnoży go, gdy podzapytanie zwraca wiele wierszy. OPTIONAL CALL zachowuje zewnętrzny wiersz z NULL podkolumnami zapytania, gdy podzapytanie nie zwraca żadnych wierszy.

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

Więcej informacji o podzapytaniach inline znajdziesz w przewodniku językowym GQL.

FILTRUJ

Przechowuje wiersze zgodne z warunkami.

Składnia:

FILTER [ WHERE ] <predicate>
...

Example:

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

Aby uzyskać więcej informacji na temat instrukcji FILTER , zobacz przewodnik języka GQL.

SORTUJ WEDŁUG

Sortuje wyniki.

Składnia:

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

Example:

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

Rozmieszczenie zera jest niezależne od kierunku sortowania. Domyślnie NULLS LAST jest to dla obu ASC i DESC; określić NULLS FIRST umieszczanie wartości zerowych przed wartościami niezerowymi.

Ważne

Żądana kolejność wierszy jest gwarantowana tylko bezpośrednio po wcześniejszym zaleceniu ORDER BY . Wszelkie następujące instrukcje (jeśli istnieją) nie mają gwarancji zachowania takiej kolejności.

Aby uzyskać więcej informacji na temat instrukcji ORDER BY , zobacz przewodnik języka GQL.

PRZESUNIĘCIE/LIMIT

Pomiń wiersze i ogranicz liczbę wyników.

Składnia:

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

Aby uzyskać więcej informacji na temat instrukcji OFFSET i LIMIT , zobacz przewodnik języka GQL.

RETURN

Wyprowadź końcowe wyniki.

Składnia:

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

Example:

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

Aby uzyskać więcej informacji na temat instrukcji RETURN , zobacz przewodnik języka GQL.

NEXT

Rozpoczyna się kolejny etap zapytania. Po tym dostępne są NEXTtylko kolumny zwrócone przez poprzedni etap.

Składnia:

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

Example:

RETURN 1 AS value
NEXT
RETURN value + 1 AS nextValue

Każdy etap może zawierać zjednoczenie bloków zapytań. Związek jest oceniany w tym etapie, zanim jego wyjście przekroczy granicę NEXT .

Więcej informacji o NEXT, zobacz przewodnik językowy GQL.

Instrukcje warunkowe

Kieruje każdy wiersz wejściowy do pierwszej WHEN gałęzi, której predykat oblicza do .TRUE

Składnia:

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

Predykaty muszą być boolowskie i oceniane w kolejności. FALSE i przechodzimy UNKNOWN do następnej gałęzi. Jeśli żadna gałąź nie pasuje i nie ELSEma , wiersz wejściowy jest pomijany. Predykaty po pierwszym meczu i niewybranych ciałach gałęzi nie są oceniane.

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

Wszystkie gałęzie muszą zwracać te same nazwy kolumn o kompatybilnych typach danych. Otocz gałąź aparatem orgazacyjnym, gdy zawiera zagnieżdżoną procedurę.

Więcej informacji można znaleźć w artykule Instrukcje warunkowe.

UNION

Łączy wyniki pełnych bloków zapytań.

Składnia:

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

Usuń UNIONUNION DISTINCT i usuń zduplikowane wiersze. UNION ALL zachowuje zduplikowane wiersze. Każdy blok zapytań musi zwracać ten sam zestaw nazw kolumn z kompatybilnymi typami danych.

Więcej informacji o związkach zawodowych można znaleźć w przewodniku językowym GQL.

Wzorce grafu

Wzorce grafu opisują strukturę grafu do dopasowania.

Wzorce węzłów

W grafowych bazach danych użyj węzłów do reprezentowania jednostek, takich jak osoby, produkty lub miejsca.

Wzorce węzłów opisują sposób dopasowania węzłów na grafie. Można filtrować według etykiet lub powiązanych zmiennych.

(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

Aby uzyskać więcej informacji na temat wzorców węzłów, zobacz Wzorce grafu.

Wzorce krawędzi

Wzorce krawędzi określają relacje między węzłami, w tym kierunek i typ krawędzi. W grafowych bazach danych krawędź reprezentuje połączenie lub relację między dwoma węzłami.

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

Aby uzyskać więcej informacji na temat wzorców krawędzi, zobacz Wzorce grafu.

Wyrażenia etykiet

Wyrażenia etykiet umożliwiają dopasowanie węzłów z określonymi kombinacjami etykiet przy użyciu operatorów logicznych.

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

Aby uzyskać więcej informacji na temat wyrażeń etykiet, zobacz Wzorce grafu.

Wzorce ścieżek

Wzorce ścieżek opisują przechodzenie przez graf, w tym liczby przeskoków i powiązania zmiennych.

(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 jest domyślnym trybem ścieżki i pozwala na powtarzające się węzły i krawędzie. TRAIL zapobiega powtarzającym się krawędziom. SIMPLE zapobiega powtarzającym się węzłom z wyjątkiem zamykającego się cyklu od początku do końca oraz zapobiega ACYCLIC wszystkim, powtarzającym się węzłom. Oba tryby unikalne dla węzła zapobiegają także powtarzaniu się krawędzi, ponieważ ponowne użycie krawędzi powodowałoby powtarzanie węzłów końcowych. ALL jest domyślnym wyszukiwaniem ścieżek. ANY SHORTEST zwraca jedną najkrótszą ścieżkę dla każdej pary źródło-cel i nie wybiera deterministycznie spośród powiązanych ścieżek.

Wspierane kwantyfikatory to stałe {n}, ograniczone {m,n} i , {,n}oraz nieograniczone {m,}, *, oraz +. Wzorce nieograniczone ALL WALK nie są obsługiwane; użyj trybu zakończenia ścieżki. Unbounded ANY SHORTEST WALK ma dodatkowe ograniczenia dotyczące kształtu i wartości ścieżki. Szczegóły można znaleźć w artykule o wzorcach wykresów GQL.

Aby uzyskać więcej informacji na temat wzorców ścieżek, zobacz Wzorce grafu.

Wiele wzorców

Użyj wielu wzorców, aby dopasować złożone, nieliniowe struktury grafu w jednym zapytaniu.

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

Aby uzyskać więcej informacji na temat wielu wzorców, zobacz Wzorce grafu.

Wartości i typy wartości

Typy podstawowe

Podstawowe typy to pierwotne wartości danych, takie jak ciągi, liczby, wartości logiczne i daty/godziny.

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

Przyrostek d or D tworzy przybliżony FLOAT64 literal. Wykładnik bez sufiksu również tworzy wartość FLOAT64 . Przyrostki f i F dosłowne nie są obecnie wspierane.

Aby uzyskać więcej informacji na temat podstawowych typów, zobacz GQL values and value types (Wartości I typy wartości GQL).

Typy wartości referencyjnych

Typy wartości referencyjnych to węzły i krawędzie, których używasz jako wartości w zapytaniach.

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

Aby uzyskać więcej informacji na temat typów wartości referencyjnych, zobacz GQL values and value types (Wartości I typy wartości GQL).

Typy kolekcji

Typy kolekcji grupuje wiele wartości, takich jak listy i ścieżki.

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

Aby uzyskać więcej informacji na temat typów kolekcji, zobacz GQL values and value types (Wartości I typy wartości GQL).

Rodzaje materiałów i unieważniające

Każdy typ wartości ma wartość null (łącznie z wartością null) lub materiał (z wyłączeniem). Domyślnie typy są dopuszczane do wartości null, chyba że jawnie określisz NOT NULLwartość .

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

Wyrażenia i operatory

Conditional

Proste CASE wyrażenia porównują jedno wyrażenie z jedną lub kilkoma wartościami.

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

Wyszukiwane CASE WHEN <predicate> wyrażenia nie są poparte. Użyj instrukcji warunkowej, aby kierować wiersze na podstawie predykatów.

Aby uzyskać więcej informacji na temat wyrażeń warunkowych, zobacz wyrażenia i funkcje GQL.

Comparison

Operatory porównania porównują wartości i sprawdzają równość, kolejność lub wartości null.

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

Aby uzyskać więcej informacji na temat predykatów porównania, zobacz wyrażenia i funkcje GQL.

Logical

Operatory logiczne łączą lub negują warunki logiczne w zapytaniach.

AND, OR, NOT, XOR               -- Boolean logic

Aby uzyskać więcej informacji na temat wyrażeń logicznych, zobacz wyrażenia i funkcje GQL.

EXISTS

Sprawdza, czy podzapytanie w formie procedury zwraca co najmniej jeden wiersz.

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

EXISTS zwraca wartość boolowską niebędącą zerową. Użyj do NOT EXISTS sprawdzenia, czy podzapytanie nie zwraca żadnych wierszy. Możesz użyć wyniku w WHERE lub FILTER, LET, RETURN, ORDER BY, oraz agregować filtry lub wyrażenia źródłowe. EXISTS nie jest obsługiwany w filtrze predykatów listowych.

Ważne

Formy oparte tylko na wzorcach grafowych, takie jak EXISTS { (p)-[:knows]->(friend) } i EXISTS ((p)-[:knows]->(friend)) nie są obsługiwane. Użyj formularza procedury z pokazanym MATCH w poprzednim przykładzie.

Caution

Niezgrupowany agregat, taki jak , RETURN count(*) zwraca jeden wiersz nawet wtedy, gdy żaden wzór nie pasuje. Ponieważ EXISTS testuje wiersze, ta forma wylicza się do TRUE.

Więcej informacji o EXISTS, zobacz Podzapytania o istnieniu.

Arithmetic

Operatory arytmetyczne wykonują obliczenia na liczbach.

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

Aby uzyskać więcej informacji na temat wyrażeń arytmetycznych, zobacz wyrażenia i funkcje GQL.

Wzorce ciągów

Predykaty wzorca ciągu pasują do podciągów, prefiksów lub sufiksów w ciągach.

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

Aby uzyskać więcej informacji na temat predykatów wzorców ciągów, zobacz wyrażenia i funkcje GQL.

Wyświetlanie listy operacji

Lista operacji test członkostwa, elementów dostępu i długości listy miar.

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

Funkcje predykatu listy zwracają TRUE, FALSE, lub UNKNOWN zgodnie z wynikami filtra. Dla listy ALL pustej i NONE wróć TRUE, podczas gdy ANY i zwróć FALSESINGLE . Lista źródeł zerowych zwraca UNKNOWN.

Wiązanie elementu jest lokalne dla filtra i może zacieniać zmienną zewnętrzną. Agregaty nad tym lokalnym wiązaniem i EXISTS podzapytaniami wewnątrz filtra nie są obsługiwane.

Więcej informacji można znaleźć w artykule Lista funkcji predykatowych.

Dostęp do właściwości

Dostęp do właściwości pobiera wartość właściwości z węzła lub krawędzi.

n.firstName                      -- Property access

Aby uzyskać więcej informacji na temat dostępu do właściwości, zobacz wyrażenia i funkcje GQL.

Functions

Używaj wbudowanych funkcji do transformacji wartości, inspekcji elementów grafu oraz agregacji wierszy.

Funkcje liczbowe

Funkcje numeryczne obliczają wartości numeryczne lub generują zakresy całkowite.

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

Inne wspierane funkcje trygonometryczne to TAN, COT, ATAN, SINH, COSH, oraz .TANH Z wyjątkiem i RANGE, te funkcje numeryczne zwracają .DOUBLEABS

Dowiedz się więcej o funkcjach numerycznych w wyrażeniach i funkcjach GQL.

Funkcje agregujące

Funkcje agregujące obliczają wartości podsumowania dla grup wierszy (agregacja pionowa) lub elementów listy grup (agregacja pozioma).

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

Bez grupowania kolumn, agregowane zapytanie bez wierszy wejściowych zwraca 0 dla COUNT, pustą listę dla COLLECT_LIST i COLLECT_ELEMENTS, oraz null dla SUM, AVG, MIN, MAX, oraz COLLECT_ONE. Argument grupy sprawia, że suma jest pozioma.

Dowiedz się więcej o funkcjach agregujących w wyrażeniach i funkcjach GQL.

Funkcje łańcuchów znakowych

Funkcje ciągów umożliwiają pracę z wartościami ciągów i analizowanie ich.

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

Wzory regexu, zamienniki i opcje muszą być dosłowne. Dla sygnatur, flag i zachowania zerowego zobacz Funkcje łańcuchowe.

Funkcje listy

Funkcje listy umożliwiają pracę z listami, takimi jak sprawdzanie długości lub rozmiaru przycinania.

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

Aby uzyskać więcej informacji na temat funkcji list, zobacz Wyrażenia i funkcje GQL.

Funkcje grafu

Funkcje programu Graph umożliwiają uzyskiwanie informacji z węzłów, ścieżek i krawędzi.

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

Aby uzyskać więcej informacji na temat funkcji grafu, zobacz Wyrażenia i funkcje GQL.

Funkcje czasowe

Funkcje czasowe umożliwiają pracę z wartościami daty i godziny.

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

Aby uzyskać więcej informacji na temat funkcji czasowych, zobacz Wyrażenia i funkcje GQL.

Funkcje ogólne

Funkcje ogólne umożliwiają pracę z danymi na typowe sposoby.

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

Aby uzyskać więcej informacji na temat funkcji ogólnych, zobacz Wyrażenia i funkcje GQL.

Przykłady zorientowane na zadania

Korzystaj z artykułów instruktażowych, gdy potrzebujesz kompletnych, gotowych do adaptacji wzorców zapytań:

Treści powiązane

  • Ostatnia aktualizacja o