Source: https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/graph/ Documentation version: v5.3.2 # 图元素函数本文介绍 GQL 支持的图元素相关函数，并基于[示例数据集](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/overview/example-dataset/)提供示例。 Note 图元素函数返回的标识符由系统自动生成，仅在同一系统内唯一。 ## 分类 | 分类 | 函数 | [点函数](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/graph/#node_functions) | `element_id()`、`labels()`、`type()` | [边函数](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/graph/#edge_functions) | `multiedge_id()`、`left_node_id()`、`right_node_id()`、`start_node_id()`、`end_node_id()`、`labels()`、`type()` | [路径函数](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/graph/#path_functions) | `nodes()`、`edges()/relationships()`、`length()`、`cardinality()` Note 此外，还支持使用 [ALL_DIFFERENT 谓词](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/predicates/all_different/)和 [SAME 谓词](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/predicates/same/)检查图元素的一致性。 ## 点函数 []() ### element_id() 返回图中点的唯一标识符。 NULL 行为：默认 #### 函数签名 ```` element_id(n: NODE) -> INT64 ```` #### 示例 ##### 返回点类型为`Actor`的点的 ID ```` USE movie MATCH (v@Actor) RETURN element_id(v) AS id, v.name AS name LIMIT 5 ```` 返回： ```` +--------------------+---------------------------+ | id | name | +--------------------+---------------------------+ | 288342985899245569 | Mark Christopher Lawrence | | 288343033143885825 | Al Pacino | | 288343153402970113 | Richard Boes | | 288343161992904705 | Zheng Tia Yong | | 288343200647610369 | Peter Lawford | +--------------------+---------------------------+ ```` ### labels() 返回点的所有标签。 NULL 行为：默认 #### 函数签名 ```` labels(n: NODE) -> LIST ```` #### 示例 ##### 返回点的标签 ```` ''' USE movie MATCH (v)-[]->(m) WHERE v.id = 133 RETURN labels(m) AS m_labels ''' ```` 返回： ```` +----------+ | m_labels | +----------+ | [Movie] | +----------+ ```` ### type() 返回点类型名。 NULL 行为：默认 #### 函数签名 ```` type(n: NODE) -> STRING ```` #### 示例 ##### 返回点的点类型名 ```` ''' USE movie MATCH (v:Person) RETURN DISTINCT type(v) AS node_types ''' ```` 返回： ```` +------------+ | node_types | +------------+ | Director | | User | | Actor | +------------+ ```` ## 边函数 []() ### multiedge_id() 基于平行边的多边键，返回用于区分特定平行边的唯一标识符。若不存在平行边，则返回`0`。 NULL 行为：默认 #### 函数签名 ```` multiedge_id(e: EDGE) -> INT64 ```` #### 示例 ##### 不存在平行边时，查询该标识符 ```` ''' USE movie MATCH ()-[e]->() RETURN multiedge_id(e) AS e LIMIT 5 ''' ```` 返回： ```` +---+ | e | +---+ | 0 | | 0 | | 0 | | 0 | | 0 | +---+ ```` 上述语句使用的图中不存在平行边，因此返回值为`0`。 ##### 存在平行边时，查询该标识符 ```` ''' // 创建边类型带多边键的图类型 CREATE GRAPH TYPE IF NOT EXISTS multi_edges AS { NODE Person (LABEL Person {id INT64, name STRING, PRIMARY KEY (id)}), EDGE `Like` (Person)-[:`Like` {rate FLOAT, MULTIEDGE KEY (rate)}]->(Person) } ''' ''' // 创建图 CREATE GRAPH IF NOT EXISTS multiedges TYPED multi_edges ''' ''' // 插入两个点以及两条平行边 USE multiedges INSERT (n@Person{id:3, name:"Alice"})-[@`Like`{rate: 3.1}]->(m@Person{id:4, name:"Bob"}), (n)-[@`Like`{rate: 3.3}]->(m) ''' ''' // 查询两点之间平行边的由多边键生成的标识符 USE multiedges MATCH (@Person{id:3})-[e]->(@Person{id:4}) RETURN multiedge_id(e) AS a ''' ```` 返回： ```` +------------+ | a | +------------+ | 1078355558 | | 1079194419 | +------------+ ```` ### left_node_id() 返回给定路径中指定边左侧点的唯一标识符。 NULL 行为：错误 #### 函数签名 ```` left_node_id(e: EDGE) -> INT64 ```` #### 示例 ##### 返回给定路径中一条边左侧点的 ID ```` ''' USE movie MATCH p = (v)<-[e]-(m) RETURN left_node_id(e) AS left_id, element_id(v) AS v_id, e AS edge LIMIT 5 ''' ```` 返回： ```` +--------------------+--------------------+----------------------------------------------------------+ | left_id | v_id | edge | +--------------------+--------------------+----------------------------------------------------------+ | 289329634376417282 | 289329634376417282 | (288247435761811457)-[0@Act:Act{}]->(289329634376417282) | | 289329634376417282 | 289329634376417282 | (288249956907614209)-[0@Act:Act{}]->(289329634376417282) | | 289329634376417282 | 289329634376417282 | (288264602746093569)-[0@Act:Act{}]->(289329634376417282) | | 289329634376417282 | 289329634376417282 | (288266148934320129)-[0@Act:Act{}]->(289329634376417282) | | 289329634376417282 | 289329634376417282 | (288346404693213185)-[0@Act:Act{}]->(289329634376417282) | +--------------------+--------------------+----------------------------------------------------------+ ```` 上述语句指定了路径`(v)<-[e]-(m)`，边`[e]`在该路径中左侧点的 ID 即为点`(v)`的 ID。 ### right_node_id() 返回给定路径中指定边右侧点的唯一标识符。 NULL 行为：错误 #### 函数签名 ```` right_node_id(e: EDGE) -> INT64 ```` #### 示例 ##### 返回给定路径中一条边右侧点的 ID ```` ''' USE movie MATCH p = (v)<-[e]-(m) RETURN right_node_id(e) AS right_id, element_id(m) AS m_id, e AS edge LIMIT 5 ''' ```` 返回： ```` +--------------------+--------------------+----------------------------------------------------------+ | right_id | m_id | edge | +--------------------+--------------------+----------------------------------------------------------+ | 288238622488920065 | 288238622488920065 | (288238622488920065)-[0@Act:Act{}]->(289131417340739586) | | 288243608945950721 | 288243608945950721 | (288243608945950721)-[0@Act:Act{}]->(289131417340739586) | | 288317563987820545 | 288317563987820545 | (288317563987820545)-[0@Act:Act{}]->(289131417340739586) | | 288324427345559553 | 288324427345559553 | (288324427345559553)-[0@Act:Act{}]->(289131417340739586) | | 288345352426225665 | 288345352426225665 | (288345352426225665)-[0@Act:Act{}]->(289131417340739586) | +--------------------+--------------------+----------------------------------------------------------+ ```` 上述语句指定了路径`(v)<-[e]-(m)`，边`[e]`在该路径中右侧点的 ID 即为点`(m)`的 ID。 ### start_node_id() 返回边的起始点 ID。对于有向边，返回源点 ID；对于无向边，返回两个点 ID 中较小的一个。 NULL 行为：默认 #### 函数签名 ```` start_node_id(e: EDGE) -> INT64 ```` #### 示例 ##### 使用 start_node_id() 判断路径方向以下示例基于 [movie 示例数据集](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/overview/example-dataset/)，使用`start_node_id()`检查无向边匹配路径中每条边的实际方向，构建带边类型标签的路径拓扑。 ```` ''' USE movie MATCH p= TRAIL (a:Actor{name:"Al Pacino"})-[:Act|Direct]-{1,3}() RETURN range(0,length(p)) AS range, nodes(p) AS nodes, edges(p) AS edges NEXT USE movie RETURN reduce(range, "", (state, i) -> state || "(" || (nodes[i]).name || ":" || type(nodes[i]) || ")" || case when i+1=size(range) then "" else case when start_node_id(edges[i])=element_id(nodes[i]) then "-["|| type(edges[i]) || "]->" else "<-[" || type(edges[i]) || "]-" end end) AS path_topology LIMIT 5 ''' ```` 返回： ```` +---------------------------------------------------------------------------------------------------------------+ | path_topology | +---------------------------------------------------------------------------------------------------------------+ | (Al Pacino:Actor)-[Act]->(The Godfather II:Movie) | | (Al Pacino:Actor)-[Act]->(The Godfather Coda: The Death of Michael Corleone:Movie) | | (Al Pacino:Actor)-[Act]->(Ocean's Thirteen:Movie) | | (Al Pacino:Actor)-[Act]->(Der Pate:Movie) | | (Al Pacino:Actor)-[Act]->(The Godfather Coda: The Death of Michael Corleone:Movie)<-[Act]-(Talia Shire:Actor) | +---------------------------------------------------------------------------------------------------------------+ ```` 上述示例使用无向边匹配`-[:Act|Direct]-`遍历路径，`start_node_id()`用于判断每条边相对当前点的方向：若`start_node_id(edges[i])`等于当前点 ID，则边从当前点出发（`->`）；否则边指向当前点（`<-`）。对于有向边，`start_node_id()`始终返回源点 ID。 ### end_node_id() 返回边的结束点 ID。对于有向边，返回目标点 ID；对于无向边，返回两个点 ID 中较大的一个。 NULL 行为：默认 #### 函数签名 ```` end_node_id(e: EDGE) -> INT64 ```` #### 示例 ##### 使用 end_node_id() 判断路径方向以下示例基于 [movie 示例数据集](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/overview/example-dataset/)，使用`end_node_id()`重建`TRAIL`匹配遍历的每条路径的拓扑，将边方向展示为`->`或`<-`。 ```` ''' USE movie MATCH p= TRAIL (a:Actor{name:"Al Pacino"})-[:Act]-{1,3}() RETURN range(0,length(p)) AS range, nodes(p) AS nodes, edges(p) AS edges NEXT USE movie RETURN reduce(range, "", (state, i) -> state || (nodes[i]).name || case when i+1=size(range) then "" else case when end_node_id(edges[i])<>element_id(nodes[i]) then "->" else "<-" end end) AS path_topology LIMIT 5 ''' ```` 返回： ```` +--------------------------------------------------------------+ | path_topology | +--------------------------------------------------------------+ | Al Pacino->Der Pate | | Al Pacino->Ocean's Thirteen | | Al Pacino->The Godfather II | | Al Pacino->The Godfather Coda: The Death of Michael Corleone | | Al Pacino->The Godfather II<-Lee Strasberg | +--------------------------------------------------------------+ ```` 上述示例使用无向边匹配`-[:Act]-`遍历路径。对于有向边`Act`（Actor→Movie），若`end_node_id(edges[i])`等于当前点 ID，则该边指向当前点（`<-`）；否则该边从当前点出发（`->`）。对于无向边，`end_node_id()`返回两端点 ID 中较大的一个。 ### labels() 返回边的所有标签。 NULL 行为：默认 #### 函数签名 ```` labels(e: EDGE) -> LIST ```` #### 示例 ##### 返回边的标签 ```` ''' USE movie MATCH (v)-[e]->(m) WHERE v.id = 133 RETURN labels(e) AS e_labels ''' ```` 返回： ```` +----------+ | e_labels | +----------+ | [Watch] | +----------+ ```` ### type() 返回边类型名。 NULL 行为：默认 #### 函数签名 ```` type(e: EDGE) -> STRING ```` #### 示例 ##### 返回边的边类型名 ```` ''' USE movie MATCH ()-[e]->() RETURN DISTINCT type(e) AS edge_types ''' ```` 返回： ```` +------------+ | edge_types | +------------+ | Direct | | Act | | Watch | | WithGenre | +------------+ ```` ## 路径函数 []() ### nodes() 以列表的形式返回路径中的所有点。 NULL 行为：默认 #### 函数签名 ```` nodes(p: PATH) -> LIST ```` #### 示例 ##### 返回包含两个点组成的路径中的点 ```` USE movie MATCH p=(m@Movie)<-[e:Watch]-(n@`User`) RETURN nodes(p) LIMIT 5 ```` 返回： ```` +--------------------------------------------------------------------------------------------------------------------------------+ | nodes(p) | +--------------------------------------------------------------------------------------------------------------------------------+ | [(289219219357171713@Movie:Movie{id:651,name:M*A*S*H}),(288991745004273665@User:Person{id:188})] | | [(289222513597087745@Movie:Movie{id:473,name:Pi}),(288982321846026242@User:Person{id:162})] | | [(289315070142316545@Movie:Movie{id:252,name:"Willy Wonka & the Chocolate Factory"}),(288993205293154307@User:Person{id:269})] | | [(289159802779598849@Movie:Movie{id:648,name:"Beauty and the Beast"}),(288990585363103745@User:Person{id:444})] | | [(289222513597087745@Movie:Movie{id:473,name:Pi}),(288990585363103745@User:Person{id:444})] | +--------------------------------------------------------------------------------------------------------------------------------+ ```` ### edges()/relationships() 以列表的形式返回路径中的所有边。 NULL 行为：默认 #### 函数签名 ```` edges(p: PATH) | relationships(p: PATH) -> LIST ```` #### 示例 ##### 返回包含两个点的路径中的边 ```` USE movie MATCH p=(m@Movie)<-[e:Watch]-(n@`User`) RETURN edges(p) AS p LIMIT 5 ```` 或 ```` USE movie MATCH p=(m@Movie)<-[e:Watch]-(n@`User`) RETURN relationships(p) AS p LIMIT 5 ```` 返回： ```` +------------------------------------------------------------------------+ | p | +------------------------------------------------------------------------+ | [(288975157840576514)-[0@Watch:Watch{rate:5.0}]->(289169659729543169)] | | [(288975157840576514)-[0@Watch:Watch{rate:5.0}]->(289158106267516929)] | | [(288985753524895745)-[0@Watch:Watch{rate:4.0}]->(289100304597647361)] | | [(288985753524895745)-[0@Watch:Watch{rate:4.0}]->(289078181221105665)] | | [(288985753524895745)-[0@Watch:Watch{rate:4.0}]->(289159802779598849)] | +------------------------------------------------------------------------+ ```` ### length() 返回路径的长度，即路径中边的数量。该函数还可以用于返回列表中的元素数量或字符串中的字符数量。更多信息，请参见[列表函数`length()`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/list/#length)和[字符串函数`length()`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/string/#length)。 NULL 行为：默认 #### 函数签名 ```` length(p: PATH) -> INT32 ```` #### 示例 ##### 返回由三个点组成的路径长度 ```` ''' USE movie MATCH p=(v@Genre)-[e2]-(m@Movie)-[e1]-(n@`User`) RETURN length(p) LIMIT 2 ''' ```` 返回： ```` +-----------+ | length(p) | +-----------+ | 2 | | 2 | +-----------+ ```` ### cardinality() 返回路径中的元素数量。该函数还可以用于返回列表或记录中的元素数量。更多信息，请参见[列表函数`cardinality()`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/list/#cardinality)。 NULL 行为：默认 #### 函数签名 ```` cardinality(input: PATH) -> INT32 ```` #### 示例 ##### 返回路径中元素的数量 ```` ''' USE movie MATCH p=(a:Movie{name:"Unpromised Land"})-[e:WithGenre]->{1,2}(b:Genre) RETURN cardinality(p) AS a ''' ```` 返回： ```` +---+ | a | +---+ | 3 | | 3 | +---+ ```` 上述示例返回每个路径中的元素总数，包括 2 个点和 1 条边。