图元素函数

本文介绍 GQL 支持的图元素相关函数，并基于示例数据集提供示例。

Note

图元素函数返回的标识符由系统自动生成，仅在同一系统内唯一。

分类

分类	函数
点函数	element_id()、labels()、type()
边函数	multiedge_id()、left_node_id()、right_node_id()、start_node_id()、end_node_id()、labels()、type()
路径函数	nodes()、edges()/relationships()、length()、cardinality()

Note

此外，还支持使用 ALL_DIFFERENT 谓词和 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<STRING>

示例

返回点的标签

'''
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 示例数据集，使用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 示例数据集，使用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<STRING>

示例

返回边的标签

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

示例

返回包含两个点组成的路径中的点

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

示例

返回包含两个点的路径中的边

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()和字符串函数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()。

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 条边。