图形查询语言（GQL）参考（预览版）

2025-09-18

适用于：✅Azure 数据资源管理器

注释

GQL 支持处于预览状态。功能和语法可能会根据反馈和正在进行的开发而变化。

介绍

本参考涵盖了图形查询语言（GQL）的基本概念、函数和运算符。图形查询语言（GQL）是基于数学图形理论概念构建的，为查询图形数据提供了坚实的基础。了解这些基础知识有助于编写更有效的查询，并更好地了解 GQL 如何处理数据。 GQL 还提供了一组丰富的函数和运算符，用于处理图形模式、节点、边缘和属性。

基本概念

本部分介绍使用 GQL 形成图形数据分析的基础的核心概念。

图形模式

图形模式是 GQL 查询的核心构建基块。它们描述要在图形数据中找到的结构，该结构使用一种声明性语法来反映图形的可视表示形式。

节点模式

节点模式指定如何匹配图形中的单个节点：

(n)              -- Any node
(n:Person)       -- Node with Person label  
(n:Person&City)  -- Node with Person AND City label
(:Person)        -- Person node, don't bind variable

关键概念：

变量绑定：(n)创建可在查询中稍后引用的变量n
匿名节点： (:Person) 匹配节点而不创建变量
标签筛选： :Person 将匹配项限制为具有 Person 标签的节点
标签组合：用于 & AND、 | OR作

边缘模式

边缘模式定义节点如何相互连接：

-[e]->                -- Directed outgoing edge, any label
-[e:works_at]->       -- Directed edge, works_at label
-[e:knows|likes]->    -- knows OR likes edge
<-[e]-                -- Directed incoming edge
-[e]-                 -- Undirected (any direction)

关键概念：

方向： -> 对于传出， <- 对于传入， - 对于任何方向
边缘类型：使用诸如按关系类型筛选的 :works_at 标签
多个类型： knows|likes 匹配任一关系类型

标签表达式

标签为节点和边缘提供语义意义。 GQL 支持复杂的标签表达式：

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

运算符：

& （AND）：节点必须具有所有指定的标签
| （OR）：节点必须至少有一个指定的标签
! （NOT）：节点不得具有指定的标签
()：用于对复杂表达式进行分组的括号

路径模式

路径模式描述图形中的多跃点关系：

(a)-[e1]->(b)-[e2]->(c)              -- 2-hop path
(a)-[e]->{2,4}(b)                    -- 2 to 4 hops
(a)-[e]->{1,}(b)                     -- 1 or more hops
(a)-[:knows|likes]->{1,3}(b)         -- 1-3 hops via knows/likes
p=()-[:works_at]->()                 -- Binding a path variable

可变长度路径：

{2,4}：正好 2 到 4 个跃点
{1,}：1 个或多个跃点（未绑定）
{,3}：最多 3 个跃点
{5}：恰好 5 个跃点

路径变量：

p=()->()：捕获整个路径以供以后分析
Access withNODES(p)， RELATIONSHIPS(p)PATH_LENGTH(p)

多个模式

GQL 支持复杂的非线性图形结构：

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

模式组合：

使用逗号 , 分隔多个模式
所有模式必须同时匹配
可以在模式之间共享变量

匹配模式

GQL 支持不同的路径匹配模式，这些模式控制模式如何与图形数据匹配。这些模式会影响性能、结果完整性和返回的路径类型。

匹配模式控制如何在单个 MATCH 子句中跨模式变量重复使用图形元素。

不同 EDGES （默认值）

Kusto 中的默认模式。匹配的边缘不能绑定到多个边缘变量，但可以自由重复使用节点。

MATCH (a)-[r1]->(b)-[r2]->(c)
-- r1 and r2 must be different edges
-- a, b, c can be the same or different nodes

可重复元素

允许跨模式变量重复使用边缘和节点，且不受限制。

MATCH REPEATABLE ELEMENTS (a)-[r1]->(b)-[r2]->(c)
-- r1 and r2 can be the same edge
-- a, b, c can be the same or different nodes

路径模式

路径模式根据重复约束控制结果中包含的路径类型。

WALK （默认值）

默认的 GQL 路径模式。包括所有可能的路径，且对节点或边缘重复没有限制。

MATCH WALK (a)-[]->{1,3}(b)
-- Allows paths with repeating nodes and edges

线索

筛选出具有重复边缘的路径。节点可能会重复，但每个边缘只能按路径显示一次。

MATCH TRAIL (a)-[]->{1,3}(b)
-- No edge can appear twice in the same path
-- Nodes may repeat

无环的

筛选出具有重复节点的路径。每个节点每个路径只能显示一次。

MATCH ACYCLIC (a)-[]->{1,3}(b)
-- No node can appear twice in the same path
-- Prevents cycles entirely

简单

与 ACYCLIC 相同，但允许路径中的第一个和最后一个节点相同（形成简单的周期）。

MATCH SIMPLE (a)-[]->{1,3}(b)
-- No node repetition except first/last can match
-- Currently not supported in implementation

模式组合和 Kusto cycles 参数

匹配模式和路径模式的不同组合映射到特定的 Kusto cycles 参数值：

不同 EDGES 模式

路径模式	单个路径	多路径（“星形”模式）
走	`cycles=unique_edges`	`cycles=unique_edges` （仅当所有路径均为 WALK/TRAIL 时）
线索	`cycles=unique_edges`	`cycles=unique_edges` （仅当所有路径均为 WALK/TRAIL 时）
无环的	`cycles=none`	不支持
简单	不支持	不支持

REPEATABLE ELEMENTS 模式

路径模式	单个路径	多路径（“星形”模式）
走	`cycles=all`	`cycles=all` （仅当所有路径都是 WALK 时）
线索	`cycles=unique_edges`	不支持
无环的	`cycles=none`	不支持
简单	不支持	不支持

语法示例

基本路径模式

-- Default (WALK with DIFFERENT EDGES)
MATCH (n)-[]->(m)
RETURN n, m

-- Explicit WALK mode
MATCH WALK (n)-[]->(m)
RETURN n, m

-- TRAIL mode - no repeating edges
MATCH TRAIL (n)-[]->{1,3}(m)
RETURN n, m

-- ACYCLIC mode - no repeating nodes
MATCH ACYCLIC (n)-[]->{1,3}(m)
RETURN n, m

匹配模式组合

-- DIFFERENT EDGES with WALK (default)
MATCH DIFFERENT EDGES WALK (n)-[]->(m)
RETURN n, m

-- REPEATABLE ELEMENTS with WALK
MATCH REPEATABLE ELEMENTS WALK (n)-[]->(m)
RETURN n, m

-- REPEATABLE ELEMENTS with TRAIL
MATCH REPEATABLE ELEMENTS TRAIL (n)-[]->(m)
RETURN n, m

多模式查询

-- Multiple WALK patterns (star pattern)
MATCH WALK (n)-[]->(a), WALK (n)-[]->(b)
RETURN n, a, b

-- Mixed path modes (both must be WALK/TRAIL for multi-path)
MATCH WALK (n)-[]->(a), TRAIL (n)-[]->(b)
RETURN n, a, b

函数和运算符参考

图形查询语言（GQL）提供了一组丰富的函数和运算符，用于处理图形模式、节点、边缘和属性。

核心 GQL 函数和运算符

下表列出了核心 GQL 函数和运算符及其 Kusto 查询语言（KQL）等效项和示例。

GQL 函数/运算符	Description	GQL 示例
`MATCH`	查找图形模式	`MATCH (a)-[r]->(b)`
`OPTIONAL MATCH`	查找可能不存在的模式	`OPTIONAL MATCH (p)->(c:City)`
`WHERE`	筛选器模式和属性	`WHERE person.age > 25`
`FILTER`	等效于 WHERE，但未使用 MATCH 子句	`FILTER p.name = 'Carol' OR c.name = 'Seattle'`
`IS NULL`	检查 null 值	`WHERE person.age IS NULL`
`IS NOT NULL`	检查非 null 值	`WHERE person.age IS NOT NULL`
`RETURN`	项目结果	`RETURN person.name, person.age`
`DISTINCT`	返回唯一值	`RETURN DISTINCT person.name`
`COUNT(*)`	对所有行进行计数	`RETURN COUNT(*)`
`COUNT()`	对非 null 值进行计数	`RETURN COUNT(person.name)`
`SUM()`	求和数值	`RETURN SUM(person.age)`
`MIN()`	最小值	`RETURN MIN(person.age)`
`MAX()`	最大值	`RETURN MAX(person.age)`
`AVG()`	平均值	`RETURN AVG(person.age)`
`COLLECT_LIST()`	将值收集到数组中	`RETURN COLLECT_LIST(person.name)`
`SIZE()`	数组长度	`RETURN SIZE(COLLECT_LIST(n.firstName))`
`Labels()`	显示节点或边缘的标签	`RETURN labels(entity)`
`UPPER()`	转换为大写	`RETURN UPPER(person.name)`
`LOWER()`	转换为小写	`RETURN LOWER(person.name)`
`LEFT()`	提取左侧子字符串	`WHERE LEFT(person.name, 3) = 'Tom'`
`RIGHT()`	提取右子字符串	`WHERE RIGHT(person.name, 5) = 'Hanks'`
`STARTS WITH`	字符串以模式开头	`WHERE person.name STARTS WITH 'Tom'`
`ENDS WITH`	字符串以模式结尾	`WHERE person.name ENDS WITH 'Hanks'`
`CONTAINS`	字符串包含模式	`WHERE person.name CONTAINS 'Tom'`
`\\|\\|`	字符串拼接	`RETURN n.firstName \\|\\| ' ' \\|\\| n.lastName`
`TRIM()`	从两端删除空格	`RETURN TRIM(' abc ')`
`BTRIM()`	从两端删除空格（TRIM 的别名）	`RETURN BTRIM(' abc ')`
`LTRIM()`	从左端删除空格	`RETURN LTRIM(' abc ')`
`RTRIM()`	从右端删除空格	`RETURN RTRIM(' abc ')`
`TRIM(BOTH FROM)`	从两端删除空格（显式）	`RETURN TRIM(BOTH FROM ' abc ')`
`TRIM(LEADING FROM)`	从左端删除空格（显式）	`RETURN TRIM(LEADING FROM ' abc')`
`TRIM(TRAILING FROM)`	从右端删除空格（显式）	`RETURN TRIM(TRAILING FROM 'abc ')`
`TRIM(chars FROM)`	从两端删除指定的字符	`RETURN TRIM('_' FROM '_abc_')`
`TRIM(BOTH chars FROM)`	从两端删除指定的字符（显式）	`RETURN TRIM(BOTH '_' FROM '_abc_')`
`TRIM(LEADING chars FROM)`	从左端删除指定的字符	`RETURN TRIM(LEADING 'd' FROM 'dddabc')`
`TRIM(TRAILING chars FROM)`	从右端删除指定的字符	`RETURN TRIM(TRAILING 't' FROM 'abcttt')`
`STRING_JOIN()`	使用分隔符联接数组元素	`RETURN STRING_JOIN(["a", "b" \\|\\| "c"], "-")`
`CAST()`	转换数据类型	`CAST(person.age AS STRING)`
`ZONED_DATETIME()`	从字符串创建日期/时间	`ZONED_DATETIME('2024-01-01')`
`CURRENT_TIMESTAMP`	当前时间戳	`WHERE created < CURRENT_TIMESTAMP`
`DURATION()`	从时间单位创建时间跨度（天到纳秒）	`DURATION({days: 3, hours: 2})`
`DURATION_BETWEEN()`	计算两个日期/时间值之间的持续时间	`DURATION_BETWEEN(start_time, end_time)`
`NODES()`	从路径中提取节点	`RETURN NODES(path_variable)`
`RELATIONSHIPS()`	从路径中提取边缘	`RETURN RELATIONSHIPS(path_variable)`
`PATH_LENGTH()`	获取路径的长度	`RETURN PATH_LENGTH(path_variable)`
`ORDER BY`	对结果进行排序	`ORDER BY person.age DESC`
`LIMIT`	限制结果计数	`LIMIT 10`
`&` （AND）	标签交集	`MATCH (p:Person & Male)`
`\\|` （或）	标签联合	`MATCH (n:Person \\| Movie)`
`!` （NOT）	标签求反	`MATCH (p:!Female)`

最佳做法

KQL 支持动态类型，但 GQL 并不明确定义应如何处理这些类型。为了避免运行时错误，请显式将嵌套字段强制转换为其预期类型（请参阅 CAST）。
由于 GQL 在 KQL 上运行，因此某些作继承 KQL 语义。例如，如果字段已是数组， COLLECT_LIST 则（GQL 等效项 make_list）将平展数组。如果结果与预期不同，请参阅等效函数的 KQL 文档。

性能优化

使用这些策略优化生产环境中的 GQL 查询性能：

小窍门

从简单的模式开始，然后根据需要增加复杂性。监视查询性能，并调整路径长度和筛选器以提高结果。

限制路径匹配范围：

使用特定标签筛选器减少搜索空间： MATCH (start:SpecificType) 而不是 MATCH (start)
限制具有合理边界的可变长度路径： MATCH (a)-[]->{1,3}(b) 而不是无限路径
提前应用 WHERE 子句，在成本高昂的作之前筛选结果。

使用 COUNT} 进行存在检查：

如果只需要检查模式是否存在，请使用 COUNT(*) 而不是返回完整结果。

MATCH (user:User)-[:SUSPICIOUS_ACTIVITY]->(target)
WHERE user.id = 'user123'
RETURN COUNT(*) > 0 AS HasSuspiciousActivity

局限性

保留关键字：某些 GQL 关键字不能用作查询中的标识符。某些保留关键字并不立即明显（例如， DATE 保留关键字）。如果图形数据具有与 GQL 保留关键字冲突的属性名称，请在图形架构中使用不同的属性名称或重命名它们以避免分析冲突。

重要

设计图形架构时，某些常见属性名称可能与 GQL 保留关键字冲突。请避免或重命名这些属性名称。
不 INSERT/CREATE 支持：不支持更改图形结构的作。而是对所有图形创建、更改和管理任务使用 KQL。
可选匹配项：仅支持节点模式（而不是边缘）。
不支持实体等效性检查：不支持 GQL(MATCH (n)-[]-(n2) WHERE n1 <> n2) 。请改用显式字段比较，例如 n.id <> n2.id。
时间和时区：引擎以 UTC 方式运行。日期/时间文本必须使用分区日期/时间;仅支持通过 ZONED_DATETIME("2011-12-31 23:59:59.9")..
持续时间粒度：持续时间最多支持数天，小单位数到纳秒。不支持大于日单位（例如周、月、年）。
遍历模式：GQL 为匹配和路径定义可配置的遍历模式。对于，模式是和;对于MATCH'DIFFERENT EDGES'，模式是'REPEATABLE EDGES'，PATH'WALK'和。'TRAIL''ACYCLIC''SIMPLE' 当前实现分别默认 'DIFFERENT EDGES' 为和 'WALK'。不支持某些组合。

Labels（）自定义 GQL 函数

该 labels() 函数将节点或边缘的标签显示为数组。

语法：

labels( entity'）

参数：

entity：匹配模式中的节点或边缘变量。

返回：

返回包含指定实体的所有标签的字符串数组。

示例：

显示匹配节点的标签：

MATCH (entity)
RETURN entity.name, labels(entity)

输出

此查询显示图形中每个节点的名称和所有标签。

entity.name	labels（entity）
john.doe	[“User”]
admin.user	[“User”]
web-server	[“System”]
数据库	[“System”]
域控制器	[“System”]

使用别名在投影中显示标签：

MATCH (n)-[e]->(target)
RETURN n.name, labels(n) AS n_labels, labels(e) AS edge_labels, target.name

此查询显示节点名称、其标签和连接边缘的标签。

n.name	n_labels	edge_labels	target.name
john.doe	[“User”]	[“CAN_ACCESS”]	web-server
admin.user	[“User”]	[“CAN_ACCESS”]	域控制器
web-server	[“System”]	[“CAN_ACCESS”]	数据库
域控制器	[“System”]	[“CAN_ACCESS”]	数据库

通过

图形查询语言 （GQL） 参考 （预览版）

介绍

基本概念

图形模式

节点模式

边缘模式

标签表达式

路径模式

多个模式

匹配模式

不同 EDGES （默认值）

可重复元素

路径模式

WALK （默认值）

线索

无环的

简单

模式组合和 Kusto cycles 参数

不同 EDGES 模式

REPEATABLE ELEMENTS 模式

语法示例

基本路径模式

匹配模式组合

多模式查询

函数和运算符参考

核心 GQL 函数和运算符

最佳做法

性能优化

局限性

Labels（） 自定义 GQL 函数

输出

相关内容

其他资源

图形查询语言（GQL）参考（预览版）

Labels（）自定义 GQL 函数