備註
這項功能目前處於公開預覽狀態。 此預覽版是在沒有服務等級協定的情況下提供，不建議用於生產工作負載。 可能不支援特定功能，或可能已經限制功能。 如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。
GQL 圖形查詢語言是圖形資料庫的 ISO 標準化查詢語言。 它可協助您有效率地查詢和處理圖形資料。
GQL 由標準化 SQL 的 ISO 工作小組共同開發，確保一致性與嚴謹性。 如果你熟悉 SQL，你會發現 GQL 有很多相似之處（表達式、謂詞、型別），這會讓你更容易入門。 本指南既適合學習 GQL 基礎知識的新手，也適合尋求先進技術和全面參考資訊的經驗豐富的使用者。
備註
GQL 的官方國際標準是 ISO/IEC 39075 資訊科技 - 資料庫語言 - GQL。
先決條件
在深入研究 GQL 之前，您應該熟悉以下概念：
- 對資料庫的基本了解——任何資料庫系統（例如關聯式（SQL）、NoSQL 或圖形）的經驗都很有幫助
- 圖形概念 - 瞭解連線資料中的節點、邊緣和關係
- 查詢基本概念 - 基本查詢概念的知識，例如篩選、排序和彙總
推薦背景：
- 有 SQL 或 openCypher 語言的經驗，能讓學習 GQL 語法變得更容易（它們是 GQL 的根源）。
- 熟悉資料建模有助於圖形結構描述設計
- 了解圖形資料的特定使用案例
你需要什麼：
- 存取具有圖形功能的 Microsoft Fabric
- 範例資料或願意使用我們的社交網路範例
- 用於編寫查詢的基本文本編輯器
小提示
如果您是圖形資料庫的新手，請先從 圖形資料模型概觀 開始，再繼續本指南。
GQL 有何特別之處
GQL 專為圖形資料而設計。 這使得處理連接資訊變得自然直觀。
與依賴表格連接來表達關係的 SQL 不同，GQL 使用視覺圖模式，直接鏡像實體之間的連結方式，使查詢更易閱讀與推理。
假設你想找1999年以前出生的人和他們的朋友（彼此認識的人）。 以下是 GQL 如何用視覺圖圖來表達這一點：
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
此查詢會尋找 1999 年之前出生的朋友 （彼此認識的人）。 該模式 (person:Person)-[:knows]-(friend:Person) 直觀地顯示了您要尋找的關係結構，就像繪製資料圖表一樣。
GQL 基本概念
在深入研究查詢之前，請先了解構成 GQL 基礎的以下核心概念：
- 圖會 將你的資料儲存為節點（實體）和邊（關係），每個節點都有標籤和屬性
- 圖形類型 就像結構描述一樣，定義圖形中可以存在哪些節點和邊緣
- 限制 是圖類型對圖施加的額外規則與限制，以強制資料完整性
-
查詢會使用 、
MATCH和FILTER等RETURN陳述式來處理資料並顯示結果 - 模式 描述了您想要使用直觀的視覺語法查找的圖形結構
- 運算式會 對資料執行計算和比較，類似於 SQL 運算式
- 謂詞 是用於查詢中篩選結果的布林值表達式
- 值類型定義 您可以處理和儲存的值類型
瞭解圖形資料
若要有效地使用 GQL，您需要瞭解圖形資料的結構。 此基礎可協助您撰寫更好的查詢並有效地建立資料模型。
節點和邊緣：建構區塊
在 GQL 中，您可以使用標記的屬性圖表。 圖形由兩種類型的元素組成：
節點 通常代表系統中的實體 （「名詞」），例如人員、組織、貼文或產品。 它們是存在於您網域中的獨立物件。 節點有時也稱為頂點。
邊 代表實體之間的關係 （“動詞”），即實體如何連接和互動。
例如，人們彼此認識（:knows）、在特定地區營運的組織（:operates）、或購買產品的顧客（:purchased）。
邊緣有時也稱為關係。
每個圖形元素都有以下特徵：
- 唯一識別它的內部 ID
-
一或多個標籤 - 描述性名稱，例如
Person或knows。 在 Microsoft Fabric 中，圖形邊總是只有一個標籤。 -
屬性——儲存關於元素資料的名稱與值對（例如
firstName: "Alice"或birthday: "19730108"）。
圖表的結構
每個 Edge 恰好連接兩個節點：來源和目的地。 此連接創建了圖形的結構並顯示了實體如何相互關聯。 邊的方向很重要——Personfollows另一個人Person創造了一種定向關係。
備註
Microsoft Fabric 中的圖形目前不支援無向邊。
Microsoft Fabric 所支援的屬性圖總是良好形成的，意即每條邊連接兩個有效節點。 如果您在圖形中看到邊緣，則其兩個端點都存在於相同的圖形中。
圖形模型和圖形類型
Microsoft Fabric 中圖形的結構是由其 圖形模型描述，其作用類似於應用程式網域的資料庫結構描述。 圖形模型定義：
- 哪些節點和邊緣可以存在
- 它們可以具有哪些標籤和屬性
- 節點和邊緣如何連線
圖形模型也透過約束來確保資料完整性，特別是 節點鍵約束 ，指定哪些屬性唯一地識別每個節點。
備註
可以使用 GQL 標準語法指定圖形模型，在這種情況下，它們稱為 圖形類型。
一個實際的例子：社交網絡
在本文件中，我們使用社交網路範例來說明 GQL 概念。 瞭解此網域有助於您遵循範例，並將類似的模式套用至您自己的資料。
備註
社交網絡的例子源自 GDC（圖數據委員會）發布的 LDBC SNB（LDBC 社交網絡基準）。 有關更多詳細信息 ，請參閱文章“LDBC 社交網絡基準” 。
社交網路實體
我們的社交網絡包括以下主要類型的節點，代表域的實體：
人們 擁有姓名、生日和性別等個人資訊。 他們生活在城市並形成社會聯繫。
地點形成 地理層次結構：
- 「紐約」或「倫敦」等城市
- 國家/地區，例如「美國」或「英國」
- 「北美」或「歐洲」等大陸
人們花時間的組織：
- 人們學習的大學
- 有人工作的公司
內容與討論：
- 標題包含貼文的論壇
- 包含內容、語言和可選圖片的貼文
- 回覆貼文或其他留言的留言
- 對內容進行分類並代表興趣的標籤
一切如何連接
實體之間的連接使網路變得有趣：
- 人們彼此認識（友誼，
:knows） - 人們在公司工作（
:workAt）或在大學就讀（:studyAt） - 人們會
:hasCreator發文和留言（） - 人們按
:likes讚貼文和留言（） - 貼文、論壇、留言都可以有標籤（）
:hasTag - 人們對特定標籤有興趣（
:hasInterest） - 論壇包含貼文（）
:containerOf並設有成員（:hasMember）和版主（:hasModerator）
圖形邊緣代表領域關係。 這個豐富的網絡為有趣的查詢和分析創造了許多機會。
您的第一個 GQL 查詢
現在您已經了解了圖形基礎知識，讓我們看看如何使用 GQL 查詢圖形資料。 這些範例從簡單到複雜構建，向您展示 GQL 的方法如何使圖形查詢變得直觀且強大。
從簡單開始：找到所有人
讓我們從最基本的查詢開始，找出圖中所有人物:Person的名字（名字、姓氏）。
MATCH (p:Person)
RETURN p.firstName, p.lastName
此查詢的執行方式如下：
-
MATCH尋找所有標記為Person -
RETURN顯示他們的名字和姓氏
新增篩選：尋找特定人員
現在我們找出具有特定特徵的人，這裡是所有叫 Alice 的人，並展示他們的名字和生日。
MATCH (p:Person)
FILTER p.firstName = 'Annemarie'
RETURN p.firstName, p.lastName, p.birthday
此查詢的執行方式如下：
-
MATCH找到所有標記為 Person 的節點 （p） -
FILTER節點 （p） 名字為 Alice -
RETURN顯示他們的名字、姓氏和生日
基本查詢結構
基本 GQL 查詢都遵循一致的模式：一系列語句，這些陳述式協同工作以尋找、篩選和傳回資料。
大多數查詢從尋找圖中的模式開始 MATCH ，最後以 RETURN 指定輸出結束。
這裡有一個簡單的查詢，可以找到彼此認識且同一生日的人配對，然後回傳這些朋友配對的總數。
MATCH (n:Person)-[:knows]-(m:Person)
FILTER n.birthday = m.birthday
RETURN count(*) AS same_age_friends
此查詢的執行方式如下：
-
MATCH尋找彼此認識的所有節點對Person -
FILTER只保留兩個人生日相同的配對 -
RETURN數一數這樣的朋友對有多少
小提示
過濾也可以透過附加 WHERE 子句直接作為模式的一部分來執行。
例如， MATCH (n:Person WHERE n.age > 23) 只會比對 Person 屬性大於 23 的 age 節點。
備註
GQL支援C樣 // 式行註解、SQL樣式 -- 行註解和C樣 /* */ 式區塊註解。
常見陳述
-
MATCH： 識別要搜尋的圖型態——這裡是你定義你感興趣資料結構的地方。 -
LET：根據匹配資料指派新變數或計算值——將導出欄位加入結果。 -
FILTER：透過套用條件縮小結果範圍——移除不符合條件的列。 -
ORDER BY：篩選後的資料排序——根據一個或多個欄位協助組織輸出。 -
OFFSET以及LIMIT：限制回傳的列數——對分頁或頂尖查詢非常有用。 -
RETURN： 指定最終輸出——定義應包含哪些資料於結果集中，並執行彙總。
陳述式如何協同運作
GQL 語句形成一條管線，每個語句處理前一個語句的輸出。 這種序列執行使查詢易於閱讀與除錯，因為執行順序與讀取順序相符。
重點︰
- 語句實際上是依序執行的。
- 每個語句都會轉換資料並將它傳遞給下一個。
- 這創造了清晰且可預測的資料流程，簡化了複雜的查詢。
這很重要
在內部，Microsoft Fabric 可以重新排序敘述的執行，並可平行執行個別敘述，以最大化效能。 不過，這不會影響結果的正確性。
範例
以下 GQL 查詢會找到前 10 位在公司名稱中帶有「Air」字樣的公司員工，依全名排序，並回傳他們的全名及公司名稱。
-- 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
此查詢的執行方式如下：
-
MATCH尋找在公司名稱中帶有「Air」字樣的公司工作者 -
LET透過結合名字與姓氏來創造全名 -
FILTER只保留Contoso員工 -
ORDER BY按全名排序 -
LIMIT取前10個結果 -
RETURN報稅名稱與公司地點
變數連接您的資料
變數 （例如 p前面範例中的 、 c和 fullName ） 會在陳述式之間攜帶資料。 當您重複使用變數名稱時，GQL 會自動確保它引用相同的數據，從而建立強大的聯結條件。 變數有時也稱為繫結變數。
變數可以以不同的方式分類：
依綁定來源：
- 模式變數 - 由相符的圖形模式所束縛
- 常規變數 - 受其他語言結構約束
模式變數類型：
-
元素變數 - 繫結至圖形元素參考值
- 節點變數 - 繫結至個別節點
- 邊緣變數 - 繫結至個別邊緣
- 路徑變數 - 繫結至代表相符路徑的路徑值
按參考程度：
- 單一變數 - 從型樣繫結至個別元素參考值
- 群組變數 - 繫結至可變長度型樣中的元素參考值清單 （請參閱 進階彙總技術）
執行結果和結果
當您執行查詢時，您會傳回包含下列內容的 執行結果 ：
- 包含陳述式中資料的
RETURN。 - 顯示查詢是否成功的狀態資訊。
結果表格
結果表格 （如果存在） 是查詢執行的實際結果。
結果表格包括其直欄的名稱和類型、用來顯示結果的慣用直欄名稱序列、表格是否排序， 以及實際列本身的相關資訊。
備註
如果執行失敗，則執行結果中不會包含任何結果表格。
狀態資訊
在查詢執行期間會偵測到各種值得注意的條件 （例如錯誤或警告）。 每個此類條件都由執行結果的狀態資訊中的狀態物件記錄。
狀態資訊由主要狀態物件和其他狀態物件的 （可能是空的） 清單組成。 主要狀態物件一律存在，並指出查詢執行是成功還是失敗。
每個狀態物件都包含一個 5 位數的狀態碼（稱為 GQLSTATUS），用於識別記錄的條件以及描述它的訊息。
成功狀態碼：
| GQL狀態 | Message | When |
|---|---|---|
| 00000 | 註：成功完成 | 至少一列成功 |
| 00001 | 註：成功完成 - 省略結果 | 成功，沒有表格（目前未使用） |
| 02000 | 注意：暫無資料 | 零列成功 |
其他狀態碼表示在查詢執行期間偵測到的進一步錯誤或警告。
這很重要
在應用程式程式碼中，一律依賴狀態碼來測試特定條件。 狀態碼保證穩定，其一般含義將來不會改變。 不要測試訊息內容，因為狀態碼所報告的具體訊息未來可能會因查詢不同，甚至在同一查詢執行間而改變。
此外，狀態物件可以包含基礎原因狀態物件和診斷記錄，其中包含描述記錄狀況的進一步資訊。
基本概念和陳述
本節涵蓋撰寫有效 GQL 查詢所需的核心建置區塊。 每個概念都建立為實用的查詢寫作技能。
圖形模式：尋找結構
圖形模式是 GQL 查詢的核心。 它們可讓您使用直覺的視覺化語法來描述您要尋找的資料結構，該語法看起來像您想要尋找的關係。
簡單圖案：
從基本關係模式開始：
-- 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)
具有特定資料的模式：
-- 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
用於靈活選擇實體的標籤表達式：
(:Person|Company)-[:isLocatedIn]->(p:City|Country) -- OR with |
(:Place&City) -- AND with &
(:Person&!Company) -- NOT with !
備註
多元素標籤的圖模型尚未支援（已知問題）。
標籤運算式可讓您在單一模式中比對不同類型的節點，讓您的查詢更加靈活。
變數重複使用會建立強大的聯結：
-- Find coworkers: people who work at the same company
(c:Company)<-[:workAt]-(x:Person)-[:knows]-(y:Person)-[:workAt]->(c)
變數 c 的重複使用可確保兩個人在同一 家 公司工作，從而建立自動加入約束。 此模式是表達「相同實體」關係的關鍵模式。
這很重要
關鍵見解：模式中的變數重複使用會產生結構限制。 這種技術是您表達複雜圖關係的方式，例如「在同一家公司工作的朋友」或「同一城市的人」。
使用 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)
有界可變長度模式：
(:Person)-[:knows]->{1,3}(:Person) -- Friends up to 3 degrees away
用於無週期遍歷的 TRAIL 模式：
使用 TRAIL 模式來防止圖遍歷期間的循環，確保每個邊緣最多被訪問一次：
-- 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
可變長度邊緣綁定：
在可變長度模式中，邊緣變數會根據上下文擷取不同的資訊：
-- 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
這種區別對於正確使用邊緣變數至關重要。
具有多個關係的複雜模式：
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
這種模式會同時尋找人員及其工作場所和住所，顯示一個人如何與其他多個實體連線。
核心陳述
GQL 提供特定的語句類型，這些陳述式類型可以協同工作，逐步處理您的圖形資料。 理解這些陳述對於建立有效的查詢至關重要。
MATCH 陳述
Syntax:
MATCH <graph pattern>, <graph pattern>, ... [ WHERE <predicate> ]
該 MATCH 語句獲取輸入資料並尋找圖形模式，將輸入變數與模式變數連接並輸出所有匹配的組合。
輸入和輸出變數：
-- 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)
使用 WHERE 進行陳述式層級篩選：
-- Filter pattern matches
MATCH (p:Person)-[:workAt]->(c:Company) WHERE p.lastName = c.name
所有相符項都可以使用 WHERE進行後過濾，避免單獨 FILTER 的陳述式。
使用輸入變數聯結：
當不是第一個陳述式時 MATCH ，它會將輸入資料與模式比對結合：
...
-- Input: table with 'targetCompany' column
-- Implicit join: targetCompany (equality join)
-- Output: table with (targetCompany, p, r) columns
MATCH (p:Person)-[r:workAt]->(targetCompany)
這很重要
Microsoft Fabric 中的圖形尚不支援任意陳述式組合。 請參閱 有關當前限制的文章。
關鍵加入行為：
如何 MATCH 處理資料聯結：
- 變數相等：輸入變數使用相等匹配與模式變數結合
- 內部聯結：捨棄沒有模式相符的輸入列（無左/右聯結）
-
篩選順序：型樣比對完成後的陳述式層級
WHERE篩選 - 型樣連線能力：多個型樣必須至少共用一個變數，才能正確聯結
- 效能：共用變數會建立有效率的聯結約束
這很重要
限制： 如果這 MATCH 不是第一個陳述式，則至少有一個輸入變數必須與型樣變數結合。 多個型樣必須有一個共同的變數。
多個模式需要共用變數：
-- 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 陳述
Syntax:
LET <variable> = <expression>, <variable> = <expression>, ...
此 LET 陳述式會建立計算變數，並在查詢管線內啟用資料轉換。
基本變數建立：
MATCH (p:Person)
LET fullName = p.firstName || ' ' || p.lastName
RETURN *
LIMIT 1000
複雜的計算：
MATCH (p:Person)
LET adjustedAge = 2000 - (p.birthday / 10000),
fullProfile = p.firstName || ' ' || p.lastName || ' (' || p.gender || ')'
RETURN *
LIMIT 1000
關鍵行為：
- 會針對每個輸入列評估運算式
- 結果會變成輸出表格中的新資料行
- 變數只能參考先前陳述式中的現有變數
- 一個
LET中的多個分配會平行評估 （無交互參照）
FILTER 陳述
Syntax:
FILTER [ WHERE ] <predicate>
此 FILTER 陳述式可讓您精確控制哪些資料會透過查詢管線進行。
基本過濾：
MATCH (p:Person)
FILTER p.birthday < 19980101 AND p.gender = 'female'
RETURN *
複雜的邏輯條件：
MATCH (p:Person)
FILTER (p.gender = 'male' AND p.birthday < 19940101)
OR (p.gender = 'female' AND p.birthday < 19990101)
OR p.browserUsed = 'Edge'
RETURN *
Null 感知篩選模式：
使用下列模式來安全地處理 Null 值：
-
檢查值：
p.firstName IS NOT NULL- 有名字 -
驗證資料：
p.id > 0- 有效身分證件 -
處理遺失的資料：
NOT coalesce(p.locationIP, '127.0.0.1') STARTS WITH '127.0.0'- 未從本地網路連線 -
組合條件：
AND/OR與複雜邏輯的明確 null 檢查一起使用
謹慎
請記住，涉及空值的條件會傳回 UNKNOWN，這會篩選掉這些列。 當您需要包含 Null 的邏輯時，請使用明確 IS NULL 檢查。
ORDER BY 陳述
Syntax:
ORDER BY <expression> [ ASC | DESC ], <expression> [ ASC | DESC ], ...
使用計算表達式進行多級排序：
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)
排序中的空值處理：
ORDER BY coalesce(p.gender, 'not specified') DESC -- Treat NULL as 'not specified'
排序行為細節：
了解運作方式 ORDER BY ：
- 運算式評估：針對每一列評估運算式，然後結果決定列順序
- 多個排序鍵：建立分層排序（主要、次要、第三等）
-
Null 處理：
NULL在比較中一律被視為最小值 -
預設順序：
ASC（遞增）為預設，DESC必須明確指定（遞減） - 計算排序：您可以按計算值排序，而不僅僅是儲存的屬性
謹慎
所 ORDER BY 建立的排序順序僅對 緊接的 陳述式可見。
因此， ORDER BY 後面的 不 RETURN * 會產生有序的結果。
比：
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 */
取代為：
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 */
這對「Top-k」查詢有直接影響： LIMIT 必須一律遵循 ORDER BY 建立預期排序順序的陳述式。
OFFSET 和 LIMIT 語句
Syntax:
OFFSET <offset> [ LIMIT <limit> ]
| LIMIT <limit>
常見模式：
-- Basic top-N query
MATCH (p:Person)
RETURN *
ORDER BY p.id DESC
LIMIT 10 -- Top 10 by ID
這很重要
如需可預測的分頁結果，請一律使用 ORDER BY before OFFSET 和 LIMIT 以確保查詢之間的資料列順序一致。
RETURN：基本結果預測
Syntax:
RETURN [ DISTINCT ] <expression> [ AS <alias> ], <expression> [ AS <alias> ], ...
[ ORDER BY <expression> [ ASC | DESC ], <expression> [ ASC | DESC ], ... ]
[ OFFSET <offset> ]
[ LIMIT <limit> ]
此 RETURN 陳述式會指定結果資料表中顯示哪些資料，以產生查詢的最終輸出。
基本輸出：
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName || ' ' || p.lastName AS name,
p.birthday,
c.name
為了清楚起見，使用別名：
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN p.firstName AS first_name,
p.lastName AS last_name,
c.name AS company_name
結合排序和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
使用 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
結合彙總：
MATCH (p:Person)-[:workAt]->(c:Company)
RETURN count(DISTINCT p) AS employee_count
RETURN with GROUP BY：分組結果投影
Syntax:
RETURN [ DISTINCT ] <expression> [ AS <alias> ], <expression> [ AS <alias> ], ...
GROUP BY <variable>, <variable>, ...
[ ORDER BY <expression> [ ASC | DESC ], <expression> [ ASC | DESC ], ... ]
[ OFFSET <offset> ]
[ LIMIT <limit> ]
用 GROUP BY 來依共用值將資料列分組，並在每個群組內計算彙總函數。
具有彙總的基本分組：
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
多欄分組：
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
備註
如需進階彙總技術，包括可變長度型樣的水平彙總，請參閱 進階彙總技術。
資料類型：使用值
GQL 支援豐富的資料類型，用於在圖表中儲存和操作不同類型的資訊。
基本值類型：
-
數字：
INT64、UINT64、用於DOUBLE計算和測量 -
文字：
STRING用於名稱、描述和文字資料 -
邏輯：
BOOL具有三個值：TRUE、FALSE 和 UNKNOWN （用於 null 處理） -
時間：
ZONED DATETIME用於帶有時區資訊的時間戳記 -
集合：
LIST<T>對多個相同類型的T值，PATH圖遍歷結果 -
圖形元素：
NODE以及EDGE用於引用圖形資料
這很重要
某些價值類型不被支援為財產價值類型。 特別地，所有涉及圖元素參考值的值都不能用作屬性值（例如節點或路徑的清單）。
範例文字：
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
關鍵 Null 處理模式：
-- 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
三值邏輯含義：
-- 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
謹慎
三值邏輯意味著 NULL = NULL 返回 UNKNOWN，而不是 TRUE。 此行為會影響篩選和聯結。 一律用於 IS NULL 空值測試。
運算式：轉換和分析資料
運算式可讓您計算、比較和轉換查詢中的資料。 它們類似於 SQL 中的表達式，但具有處理圖形資料的額外功能。
常見的表達式類型：
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
複雜的謂詞組成：
-- 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)
字串模式匹配：
-- 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
按類別劃分的內建功能：
GQL 針對不同的資料處理需求提供了這些函數類別：
-
聚合函數：
count()、sum()、avg()、min()、，max()用於彙總資料 -
字串函數：
char_length()、upper()、lower()、用於trim()文字處理 -
圖形函數：
nodes()、edges()、labels()用於分析圖形結構 -
一般函數：
coalesce()用於正常處理空值
複雜運算式的運算子優先順序：
- 物業存取權 （
.） - 乘法/除法 （
*，/） - 加法/減法 （
+，-） - 比較 （
=，<>，<，>，<=>=， ， ） - 邏輯否定 （
NOT） - 邏輯連接詞 （
AND） - 邏輯析取 （
OR）
在上述列表中，數字較低的運算子比數字較高的運算子「綁定得更緊密」。
範例： NOT n.prop OR m.prop 是 (NOT n.prop) OR m.prop 但不是「NOT」（n.prop 或 m.prop）
小提示
使用括弧來明確表示優先順序。 當分組清晰時，複雜的運算式更容易閱讀和偵錯。
進階查詢技術
本節介紹用於建立複雜、高效的圖形查詢的複雜模式和技術。 這些模式超越基本陳述式用法，可協助您撰寫強大的分析查詢。
複雜的多語句組合
這很重要
Microsoft Fabric 中的圖形尚不支援任意陳述式組合。 請參閱 有關當前限制的文章。
了解如何有效地撰寫複雜的查詢對於進階圖形查詢至關重要。
多步驟模式進展：
-- 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
這個查詢會逐漸增加複雜度：查找公司、員工、員工所在地、篩選1985年前出生員工的公司、計算平均生日，並彙整和排序結果。
水平聚合的使用：
-- 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
備註
這個查詢目前還不支援（已知問題）。
可變範圍和進階流量控制
變數跨查詢語句連接資料並啟用複雜的圖形遍歷。 瞭解進階範圍規則可協助您撰寫複雜的多語句查詢。
變數繫結和範圍模式：
-- 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)
跨陳述式聯結的變數重複使用：
-- 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 *
關鍵範圍規則和限制：
-- ✅ 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 *
複雜查詢中的變數可見性：
-- 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
謹慎
相同陳述式中的變數無法相互參考 （圖形模式除外）。 使用單獨的陳述式來建立應變數。
先進的聚合技術
GQL 支援兩種不同類型的彙總，用於跨群組和集合分析資料：垂直 GROUP BY 彙總和可變長度模式的水平彙總。
使用 GROUP BY 進行垂直彙總
垂直彙總（涵蓋於RETURNGROUP BY）會依共用值將資料列分組，並計算每個群組內的彙總：
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
此方法會為每個公司建立一個結果列，彙總每個群組內的所有員工。
具有群組清單變數的水平彙總
水平彙總會計算受可變長度模式所系結之集合的彙總。 當您使用可變長度邊時，邊變數會變成群組 清單變數 ，以保留每個相符路徑中的所有邊：
-- 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
備註
這個查詢目前還不支援（已知問題）。
主要差異：
- 垂直彙總會 跨列摘要 - 或 - 將列分組，並跨每個群組中的列摘要
- 水平彙總 會彙總個別邊緣集合中的元素
- 群組清單變數僅來自可變長度邊緣模式
可變長度邊緣繫結內容
了解邊緣變數如何在可變長度模式中綁定至關重要：
在模式比對期間（單例上下文）：
-- 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 *
在結果運算式 （群組內容） 中：
-- 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
備註
這個查詢目前還不支援（已知問題）。
結合垂直和水平聚合
您可以在複雜的分析模式中結合這兩種聚集類型：
-- 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
備註
這個查詢目前還不支援（已知問題）。
小提示
水平彙總一律優先於垂直彙總。 若要將群組清單轉換為一般清單，請使用 collect_list(edges)。
備註
如需詳細的彙總函數參考，請參閱 GQL 運算式和函數。
錯誤處理策略
了解常見的錯誤模式有助於您撰寫健全的查詢。
正常處理遺失的資料：
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 *
使用明確的 Null 檢查：
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 *
其他資訊
GQL狀態碼
如 查詢結果一節所述，GQL 會報告與執行成功或潛在失敗相關的豐富狀態資訊。 如需完整清單，請參閱 GQL 狀態碼參考。
保留字詞
GQL 會保留某些您無法用作識別碼的關鍵字，例如變數、屬性名稱或標籤名稱。 如需完整清單，請參閱 GQL 保留字組參考 。
如果您需要使用保留字作為標識符，請使用反引號轉義它們： `match`， `return`。
若要避免逸出保留字，請使用此命名慣例：
- 對於單字識別碼，請附加底線：
:Product_ - 對於多字標識符，請使用駝峰命名法或帕斯卡命名法：
:MyEntity，:hasAttribute，textColor
後續步驟
現在您已經了解了 GQL 基礎知識，以下是您推薦的學習路徑：
繼續培養您的 GQL 技能
對於初學者：
對於有經驗的用戶：
- 進階運算式 - 掌握 GQL 運算式和函數
- 架構設計 - 學習 GQL 圖形類型 和限制
- 探索資料類型 - 了解 GQL 值和值類型
參考資料
將這些參考資料放在手邊以便快速查找：
探索 Microsoft Fabric
了解平台：
- 圖形資料模型 - 瞭解圖形概念和建模
- 圖形與關聯式資料庫 - 選擇正確的方法
- 免費試用 Microsoft Fabric - 取得實作體驗
- 端對端教學課程 - 完整的學習案例
積極參與
- 分享意見反應 - 協助改善我們的文件和工具
- 加入社區 - 與其他圖數據庫從業者聯繫
- 保持更新 - 關注 Microsoft Fabric 公告以獲取新功能
相關內容
有關關鍵主題的更多詳細信息：
- 社交網路結構描述範例 - 圖形結構描述的完整工作範例
- GQL 圖模式 - 全面的模式語法和高級匹配技術
- GQL 運算式和函數 - 所有運算式類型和內建函數
- GQL 圖形類型 - 圖形類型和限制
- GQL 值和值類型 - 完整的類型系統參考和值處理
快速參考：
Microsoft Fabric 中的圖形：
- 圖形資料模型 - 瞭解圖形概念和建模
- 圖形和關聯式資料庫 - 差異以及何時使用每個資料庫
- 免費試用 Microsoft Fabric
- Microsoft Fabric 中的端對端教學課程