GQL 快速參考

本文是關於 Microsoft Fabric 中圖形語法的快速參考資料。用它來回憶語法和預設值。欲獲得端到端說明，請參閱 GQL 語言指南;每個章節都連結到擁有完整細節的重點參考文獻。

備註

本文主要使用社群網路範例圖集。它也提供了幾個使用 Adventure Works 資料集的範例，這些資料來自圖表教學。

查詢結構

GQL 查詢使用一系列語句來定義要從圖表中取得哪些資料、如何處理資料以及如何顯示結果。每個語句都有特定的用途，它們共同創建了一個線性管道，該管道與圖表中的資料進行匹配並逐步轉換。

一般查詢流程：
GQL 查詢通常從指定相符的圖型開始。接著，它使用可選的語句來建立變數、篩選、排序、分頁和結果輸出。

範例：

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

陳述撰寫：

這很重要

語句形成有序的管線，無法隨意重新排列。請參閱有關當前限制的文章。

MATCH – 指定要查找的圖形模式。
LET – 從表達式定義變數。
FOR – 將清單展開成一列。
CALL – 執行內嵌子查詢並加入其回傳的欄位。
FILTER – 保持行匹配條件。
WHEN – 將每個輸入列路由到第一個匹配的條件分支。
ORDER BY – 對結果進行排序。
OFFSET – 跳過許多行。
LIMIT – 限制行數。
RETURN – 輸出最終結果。
NEXT – 使用前一階段回傳的欄位開始另一個查詢階段。

每個陳述式都以前一個陳述式為基礎，因此您可以累加精簡和調整查詢輸出。使用 UNION、 UNION DISTINCT或 UNION ALL 來合併完整的查詢區塊。如需每個陳述式的詳細資訊，請參閱下列各節。

查詢陳述式

MATCH

在資料中尋找圖形模式。

Syntax:

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

範例：

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

如需陳述式的詳細資訊 MATCH ，請參閱圖形模式。

讓

透過使用表達式來建立變數。

Syntax:

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

範例：

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

如需此 LET 陳述式的詳細資訊，請參閱 GQL 語言指南。

FOR

將清單展開為列，並可選擇性地回傳每個元素的位置。

Syntax:

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

範例：

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

WITH OFFSET 從 0開始。 WITH ORDINALITY 從 1開始。

如需此 FOR 陳述式的詳細資訊，請參閱 GQL 語言指南。

CALL

為每個輸入列執行一個內嵌子查詢。已在作用域中的變數則隱含於子查詢中。

Syntax:

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

在子查詢中建立的變數中，只有其最終 RETURN 陳述式中的欄位能在子查詢之外使用。當子查詢回傳無列時，Ordinary CALL 會丟棄一個外層列;當子查詢回傳多列時，則將該列乘以。 OPTIONAL CALL 當子查詢回傳無列時，會保留一個帶有子 NULL 查詢欄位的外層列。

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

欲了解更多內嵌子查詢資訊，請參閱 GQL 語言指南。

過濾器

保持符合條件的划行。

Syntax:

FILTER [ WHERE ] <predicate>
...

範例：

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

如需此 FILTER 陳述式的詳細資訊，請參閱 GQL 語言指南。

排序依據

排序結果。

Syntax:

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

範例：

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

空置位置與排序方向無關。預設值同時為 NULLS LASTASC 和 DESC;指定 NULLS FIRST 在非空值前放置空值。

這很重要

所請求的列序僅保證緊接前一個語句後 ORDER BY 立即成立。後續的語句（如果存在）並不保證能維持任何此類順序。

如需此 ORDER BY 陳述式的詳細資訊，請參閱 GQL 語言指南。

偏移/限制

略過列並限制結果數量。

Syntax:

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

範例：

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

如需 and OFFSETLIMIT 陳述式的詳細資訊，請參閱 GQL 語言指南。

RETURN

輸出最終結果。

Syntax:

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

範例：

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

如需此 RETURN 陳述式的詳細資訊，請參閱 GQL 語言指南。

開始另一個查詢階段。之後僅有 NEXT前一階段回傳的欄位可用。

Syntax:

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

範例：

RETURN 1 AS value
NEXT
RETURN value + 1 AS nextValue

任一階段都可以包含查詢區塊的聯集。合併會在該階段內評估，然後產出才會越 NEXT 界。

欲了解更多資訊 NEXT，請參閱 GQL語言指南。

條件陳述式

將每個輸入列路由至第一個 WHEN 分支，其謂詞值為 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 }> ]

謂詞必須是布林值，並依序評估。 FALSE 然後 UNKNOWN 穿過來，然後掉到下一個分支。如果沒有分支匹配且沒有 ELSE，則該輸入列會被省略。第一個匹配後的謂詞和未被選取的分支體不會被評估。

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

所有分支必須回傳相同的欄位名稱且資料型別相容。當枝條包含巢狀程序時，請用支架包圍該枝條。

欲了解更多資訊，請參閱條件語句。

UNION

結合完整查詢區塊的輸出。

Syntax:

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

裸 UNION 露並 UNION DISTINCT 移除重複的排。 UNION ALL 保留重複的列。每個查詢區塊必須回傳相同的欄位名稱集合，且資料型別相容。

欲了解更多工會資訊，請參閱 GQL語言指南。

圖形模式

圖形模式描述要匹配的圖形結構。

節點模式

在圖資料庫中，使用節點來表示實體，例如人物、產品或地點。

節點模式描述如何比對圖形中的節點。您可以依標籤或繫結變數進行篩選。

(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

如需節點模式的詳細資訊，請參閱圖形模式。

邊緣圖案

邊樣式指定節點之間的關係，包括方向和邊類型。在圖形資料庫中，邊緣代表兩個節點之間的連接或關係。

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

如需邊緣模式的詳細資訊，請參閱圖表模式。

標籤運算式

標籤表達式可以透過邏輯運算子，讓你能以特定標籤組合匹配節點。

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

如需標籤運算式的詳細資訊，請參閱圖表型樣。

路徑模式

路徑模式描述了圖的遍歷，包括躍點計數和變數繫結。

(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 是預設路徑模式，允許重複節點與邊。 TRAIL 防止重複邊緣。 SIMPLE 防止重複節點，除非關閉倒數第一個循環，並 ACYCLIC 防止所有重複節點。這兩種節點唯一模式也防止重複邊，因為邊的重複使用會重複端點節點。 ALL 是預設的路徑搜尋。 ANY SHORTEST 對每個來源-目的節點回傳一條最短路徑，且不會在綁定路徑中選擇。

支援的量詞包括固定 {n}、有界 {m,n} 、 {,n}以及無界 {m,}、 *、 +和。不支援無界 ALL WALK 模式;請使用終止路徑模式。無界則 ANY SHORTEST WALK 有額外的形狀與路徑值限制。詳情請參見 GQL圖形模式。

如需路徑模式的詳細資訊，請參閱圖表模式。

多種模式

在單一查詢中，使用多種模式來匹配複雜且非線性的圖結構。

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

如需多個模式的詳細資訊，請參閱圖形模式。

值和值類型

基本類型

基本類型是原始資料值，例如字串、數字、布林值和日期時間。

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

或D後d綴會形成近似FLOAT64的字面值。沒有後綴的指數也會產生一個 FLOAT64 值。 f F目前不支援字面後綴。

欲了解更多基本型別資訊，請參見 GQL 值與值型別。

參考值類型

參考值類型是你在查詢中用作值的節點和邊。

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

欲了解更多參考值類型資訊，請參閱 GQL值與值型別。

集合類型

集合類型會將多個值分組，例如清單和路徑。

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

欲了解更多關於收藏類型的資訊，請參閱 GQL 值與值型別。

材質型與可歸零型

每個值類型要麼是可空的（包含空值），要麼是 material（排除空值）。預設情況下，型別是可空的，除非你明確指定 NOT NULL。

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

運算式和運算子

Conditional

簡單的 CASE 表達式將一個表達式與一個或多個數值進行比較。

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

搜尋過 CASE WHEN <predicate> 的表達式不支援。使用條件語句根據謂詞來路由列。

欲了解更多條件表達式的資訊，請參閱 GQL 表達式與函式。

Comparison

比較運算子會比較值，並檢查相等、排序或空值。

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

如需比較述詞的詳細資訊，請參閱 GQL 運算式和函數。

Logical

邏輯運算子會結合或否定查詢中的布林條件。

AND, OR, NOT, XOR               -- Boolean logic

如需邏輯運算式的詳細資訊，請參閱 GQL 運算式和函數。

EXISTS

測試程序表單子查詢是否至少回傳一列。

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

EXISTS 回傳一個非空的布林值。用 NOT EXISTS 來測試子查詢是否回傳任何列。你可以在或 FILTER、 LET、 RETURN、 ORDER BY、以及彙總濾波器或來源表達式中使用結果WHERE。 EXISTS 在列表謂詞過濾器中不被支援。

這很重要

僅有圖形模式的形式 EXISTS { (p)-[:knows]->(friend) } 如和 EXISTS ((p)-[:knows]->(friend)) 不被支援。請使用前述範例所示的程序表 MATCH 單。

Caution

像未分組的聚合，即使沒有任何模式匹配，也會 RETURN count(*) 回傳一列。因為 EXISTS 對列的測試，該形式會被評估為 TRUE。

欲了解更多相關 EXISTS資訊，請參見存在性子查詢。

Arithmetic

算術運算符對數字進行計算。

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

如需算術運算式的詳細資訊，請參閱 GQL 運算式和函數。

字串模式

字串型樣述詞會比對字串中的子字串、字首或字尾。

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

如需字串模式述詞的詳細資訊，請參閱 GQL 運算式和函數。

列出作業

清單作業會測試成員資格、存取元素，以及測量清單長度。

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

列表謂詞會回傳 TRUE、 FALSE，或 UNKNOWN 根據篩選結果。對於一個空清單，和 ALL 返回，而 SINGLEANY 返回 FALSE。TRUENONE 空原始碼列表會回傳 UNKNOWN。

元素綁定是局部於濾波器，且可遮蔽外部變數。不支援在本地綁定上的聚合和 EXISTS 篩選器內的子查詢。

欲了解更多資訊，請參閱 List 謂詞函數。

屬性存取

屬性存取會從節點或邊緣取得屬性的值。

n.firstName                      -- Property access

如需屬性存取的詳細資訊，請參閱 GQL 運算式和函數。

Functions

使用內建函式來轉換數值、檢查圖形元素並彙總列。

數值函數

數值函數計算數值或產生整數範圍。

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

其他支援的三角函數包括 TAN、 COT、 COSHATANSINHTANH和。除了和 ABSRANGE外，這些數值函數會回傳 DOUBLE。

了解更多關於 GQL 表達式與函數中的數值函數。

聚合函數

彙總函數會計算列群組（垂直彙總）或群組清單元素（水平彙總）的摘要值。

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

若不分組欄位，若一個無輸入列的彙總查詢，會對和返回0一個空清單COLLECT_ELEMENTSCOLLECT_LIST，對於 MINCOLLECT_ONESUMMAXAVG、和。COUNT 群組列表論證使總體成為水平的。

進一步瞭解 GQL 運算式和函數中的彙總函數。

字串函數

字串函數可讓您使用和分析字串值。

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

正則表達式模式、替換和選項必須是字面的。關於簽名、旗標與空行為，請參見字串函數。

清單函式

清單功能可讓您使用清單，例如檢查長度或修剪大小。

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

欲了解更多關於列表函式的資訊，請參見 GQL 表達式與函式。

圖形函式

圖形函數可讓您從節點、路徑和邊緣取得資訊。

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

欲了解更多圖函數資訊，請參見 GQL 表達式與函數。

時間函數

時態函數可讓您使用日期和時間值。

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

欲了解更多時間函數，請參見 GQL表達式與函數。

泛型函數

泛型函數可讓您以常見的方式處理資料。

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

欲了解更多一般函式的資訊，請參閱 GQL 表達式與函式。

任務導向範例

當你需要完整且可即時調整的查詢模式時，請使用操作文章：

撰寫常見的 GQL 查詢，包括鄰居、多跳遍歷、共享連線及存在性檢查。
過濾與彙整圖資料，用於列與模式篩選、分組、集合聚合及條件路由。
撰寫路徑模式、路徑搜尋、模式組合及可選匹配的圖形模式查詢。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-09-29

GQL 快速參考

查詢結構

查詢陳述式

MATCH

讓

FOR

CALL

過濾器

排序依據

偏移/限制

RETURN

NEXT

條件陳述式

UNION

圖形模式

節點模式

邊緣圖案

標籤運算式

路徑模式

多種模式

值和值類型

基本類型

參考值類型

集合類型

材質型與可歸零型

運算式和運算子

Conditional

Comparison

Logical

EXISTS

Arithmetic

字串模式

列出作業

屬性存取

Functions

數值函數

聚合函數

字串函數

清單函式

圖形函式

時間函數

泛型函數

任務導向範例

相關內容

意見反應

其他資源