跳转至

MATCH

MATCH语句提供基于模式(pattern)匹配的搜索功能。

一个MATCH语句定义了一个搜索模式,用该模式匹配存储在 Nebula Graph 中的数据,然后用RETURN子句检索数据。

本文示例使用测试数据集 basketballplayer 进行演示。

语法

GOLOOKUP等其他查询语句相比,MATCH的语法更灵活。MATCH语句采用的路径类型是trail,即遍历时只有点可以重复,边不可以重复。

MATCH 语法如下:

MATCH <pattern> [<clause_1>]  RETURN <output>  [<clause_2>];
  • pattern:pattern 的详细说明请参见模式MATCH语句支持匹配一个或多个模式,多个模式之间用英文逗号(,)分隔。例如(a)-[]->(b),(c)-[]->(d)
  • clause_1:支持WHEREWITHUNWINDOPTIONAL MATCH子句,也可以使用MATCH作为子句。
  • output:定义需要返回的输出。可以使用AS设置输出的别名。
  • clause_2:支持ORDER BYLIMIT子句。

注意事项

除以下三种情况之外,请确保 MATCH 语句有至少一个索引可用。

  • MATCH语句中WHERE子句使用 id() 函数指定了点的 VID,不需要创建索引即可执行。
  • 当遍历所有点边时,例如MATCH (v) RETURN v LIMIT N,不需要创建索引,但必须使用LIMIT限制输出结果数量。
  • 当遍历指定 Tag 的点或指定 Edge Type 的边时,例如MATCH (v:player) RETURN v LIMIT N,不需要创建索引,但必须使用LIMIT限制输出结果数量。

Note

目前 MATCH 语句无法查询到悬挂边。

历史版本兼容性

从 3.0.0 版本开始,为了区别不同 Tag 的属性,返回属性时必须额外指定 Tag 名称。即从RETURN <变量名>.<属性名>改为RETURN <变量名>.<Tag名>.<属性名>

示例

创建索引

# 在 Tag player 的 name 属性和 Edge type follow 上创建索引。
nebula> CREATE TAG INDEX IF NOT EXISTS name ON player(name(20));
nebula> CREATE EDGE INDEX IF NOT EXISTS follow_index on follow();

# 重建索引使其生效。
nebula> REBUILD TAG INDEX name;
+------------+
| New Job Id |
+------------+
| 121        |
+------------+

nebula> REBUILD EDGE INDEX follow_index;
+------------+
| New Job Id |
+------------+
| 122        |
+------------+

# 确认重建索引成功。
nebula> SHOW JOB 121;
+----------------+---------------------+------------+----------------------------+----------------------------+-------------+
| Job Id(TaskId) | Command(Dest)       | Status     | Start Time                 | Stop Time                  | Error Code  |
+----------------+---------------------+------------+----------------------------+----------------------------+-------------+
| 121            | "REBUILD_TAG_INDEX" | "FINISHED" | 2021-05-27T02:18:02.000000 | 2021-05-27T02:18:02.000000 | "SUCCEEDED" |
| 0              | "storaged1"         | "FINISHED" | 2021-05-27T02:18:02.000000 | 2021-05-27T02:18:02.000000 | "SUCCEEDED" |
| 1              | "storaged0"         | "FINISHED" | 2021-05-27T02:18:02.000000 | 2021-05-27T02:18:02.000000 | "SUCCEEDED" |
| 2              | "storaged2"         | "FINISHED" | 2021-05-27T02:18:02.000000 | 2021-05-27T02:18:02.000000 | "SUCCEEDED" |
+----------------+---------------------+------------+----------------------------+----------------------------+-------------+

nebula> SHOW JOB 122;
+----------------+----------------------+------------+----------------------------+----------------------------+-------------+
| Job Id(TaskId) | Command(Dest)        | Status     | Start Time                 | Stop Time                  | Error Code  |
+----------------+----------------------+------------+----------------------------+----------------------------+-------------+
| 122            | "REBUILD_EDGE_INDEX" | "FINISHED" | 2021-05-27T02:18:11.000000 | 2021-05-27T02:18:11.000000 | "SUCCEEDED" |
| 0              | "storaged1"          | "FINISHED" | 2021-05-27T02:18:11.000000 | 2021-05-27T02:18:21.000000 | "SUCCEEDED" |
| 1              | "storaged0"          | "FINISHED" | 2021-05-27T02:18:11.000000 | 2021-05-27T02:18:21.000000 | "SUCCEEDED" |
| 2              | "storaged2"          | "FINISHED" | 2021-05-27T02:18:11.000000 | 2021-05-27T02:18:21.000000 | "SUCCEEDED" |
+----------------+----------------------+------------+----------------------------+----------------------------+-------------+

匹配点

历史版本兼容性

从 Nebula Graph 3.0.0 开始,支持MATCH (v) RETURN v LIMIT n,不需要创建索引; 但是必须使用 LIMIT 限制输出结果数量。

不可以直接执行 MATCH (v) RETURN v

用户可以在一对括号中使用自定义变量来表示模式中的点。例如(v)

nebula> MATCH (v) \
        RETURN v \
        LIMIT 3;
+-----------------------------------------------------------+
| v                                                         |
+-----------------------------------------------------------+
| ("player102" :player{age: 33, name: "LaMarcus Aldridge"}) |
| ("player106" :player{age: 25, name: "Kyle Anderson"})     |
| ("player115" :player{age: 40, name: "Kobe Bryant"})       |
+-----------------------------------------------------------+

匹配 Tag

历史版本兼容性

在 Nebula Graph 3.0.0 之前,匹配 Tag 的前提是 Tag 本身有索引或者 Tag 的某个属性有索引,否则,用户无法基于该 Tag 执行 MATCH 语句。从 Nebula Graph 3.0.0 开始,匹配 Tag 可以不创建索引,但需要使用 LIMIT 限制输出结果数量。

用户可以在点的右侧用:<tag_name>表示模式中的 Tag。

nebula> MATCH (v:player) \
        RETURN v \
        LIMIT 3;
+-----------------------------------------------------------+
| v                                                         |
+-----------------------------------------------------------+
| ("player102" :player{age: 33, name: "LaMarcus Aldridge"}) |
| ("player106" :player{age: 25, name: "Kyle Anderson"})     |
| ("player115" :player{age: 40, name: "Kobe Bryant"})       |
+-----------------------------------------------------------+
...

需要匹配拥有多个 Tag 的点,可以用英文冒号(:)。

Note

匹配多个 Tag 的点时,不支持进行属性过滤。

例如,不支持match (v1:player:team) where v1.player.name=="Tim Duncan" return v1 limit 10;

nebula> CREATE TAG actor (name string, age int);
nebula> INSERT VERTEX actor(name, age) VALUES "player100":("Tim Duncan", 42);
nebula> MATCH (v:player:actor) \
        RETURN v \
        LIMIT 10;
+----------------------------------------------------------------------------------------+
| v                                                                                      |
+----------------------------------------------------------------------------------------+
| ("player100" :actor{age: 42, name: "Tim Duncan"} :player{age: 42, name: "Tim Duncan"}) |
+----------------------------------------------------------------------------------------+

匹配点的属性

用户可以在 Tag 的右侧用{<prop_name>: <prop_value>}表示模式中点的属性。

# 使用属性 name 搜索匹配的点。
nebula> MATCH (v:player{name:"Tim Duncan"}) \
        RETURN v;
+----------------------------------------------------+
| v                                                  |
+----------------------------------------------------+
| ("player100" :player{age: 42, name: "Tim Duncan"}) |
+----------------------------------------------------+

使用WHERE子句也可以实现相同的操作:

nebula> MATCH (v:player) \
        WHERE v.player.name == "Tim Duncan" \
        RETURN v;
+----------------------------------------------------+
| v                                                  |
+----------------------------------------------------+
| ("player100" :player{age: 42, name: "Tim Duncan"}) |
+----------------------------------------------------+

openCypher 兼容性

在 openCypher 9 中,=是相等运算符,在 nGQL 中,==是相等运算符,=是赋值运算符。

匹配点 ID

用户可以使用点 ID 去匹配点。id()函数可以检索点的 ID。

nebula> MATCH (v) \
        WHERE id(v) == 'player101' \
        RETURN v;
+-----------------------------------------------------+
| v                                                   |
+-----------------------------------------------------+
| ("player101" :player{age: 36, name: "Tony Parker"}) |
+-----------------------------------------------------+

要匹配多个点的 ID,可以用WHERE id(v) IN [vid_list]

nebula> MATCH (v:player { name: 'Tim Duncan' })--(v2) \
        WHERE id(v2) IN ["player101", "player102"] \
        RETURN v2;
+-----------------------------------------------------------+
| v2                                                        |
+-----------------------------------------------------------+
| ("player101" :player{age: 36, name: "Tony Parker"})       |
| ("player101" :player{age: 36, name: "Tony Parker"})       |
| ("player102" :player{age: 33, name: "LaMarcus Aldridge"}) |
+-----------------------------------------------------------+

匹配连接的点

用户可以使用--符号表示两个方向的边,并匹配这些边连接的点。

历史版本兼容性

在 nGQL 1.x 中,--符号用于行内注释,从 nGQL 2.x 起,--符号表示出边或入边,不再用于注释。

nebula> MATCH (v:player{name:"Tim Duncan"})--(v2:player) \
        RETURN v2.player.name AS Name;
+---------------------+
| Name                |
+---------------------+
| "Manu Ginobili"     |
| "Manu Ginobili"     |
| "Dejounte Murray"   |
...

用户可以在--符号上增加<>符号指定边的方向。

# -->表示边从 v 开始,指向 v2。对于点 v 来说是出边,对于点 v2 来说是入边。
nebula> MATCH (v:player{name:"Tim Duncan"})-->(v2:player) \
        RETURN v2.player.name AS Name;
+-----------------+
| Name            |
+-----------------+
| "Tony Parker"   |
| "Manu Ginobili" |
+-----------------+

如果需要判断目标点,可以使用CASE表达式。

nebula> MATCH (v:player{name:"Tim Duncan"})--(v2) \
        RETURN \
        CASE WHEN v2.team.name IS NOT NULL \
        THEN v2.team.name  \
        WHEN v2.player.name IS NOT NULL \
        THEN v2.player.name END AS Name;

+---------------------+
| Name                |
+---------------------+
| "Manu Ginobili"     |
| "Manu Ginobili"     |
| "Spurs"             |
| "Dejounte Murray"   |
...

如果需要扩展模式,可以增加更多点和边。

nebula> MATCH (v:player{name:"Tim Duncan"})-->(v2)<--(v3) \
        RETURN v3.player.name AS Name;
+---------------------+
| Name                |
+---------------------+
| "Dejounte Murray"   |
| "LaMarcus Aldridge" |
| "Marco Belinelli"   |
...

如果不需要引用点,可以省略括号中表示点的变量。

nebula> MATCH (v:player{name:"Tim Duncan"})-->()<--(v3) \
        RETURN v3.player.name AS Name;
+---------------------+
| Name                |
+---------------------+
| "Dejounte Murray"   |
| "LaMarcus Aldridge" |
| "Marco Belinelli"   |
...

匹配路径

连接起来的点和边构成了路径。用户可以使用自定义变量命名路径。

nebula> MATCH p=(v:player{name:"Tim Duncan"})-->(v2) \
        RETURN p;
+--------------------------------------------------------------------------------------------------------------------------------------+
| p                                                                                                                                    |
+--------------------------------------------------------------------------------------------------------------------------------------+
| <("player100" :player{age: 42, name: "Tim Duncan"})-[:serve@0 {end_year: 2016, start_year: 1997}]->("team204" :team{name: "Spurs"})> |
| <("player100" :player{age: 42, name: "Tim Duncan"})-[:follow@0 {degree: 95}]->("player101" :player{age: 36, name: "Tony Parker"})>   |
| <("player100" :player{age: 42, name: "Tim Duncan"})-[:follow@0 {degree: 95}]->("player125" :player{age: 41, name: "Manu Ginobili"})> |
+--------------------------------------------------------------------------------------------------------------------------------------+

openCypher 兼容性

在 nGQL 中,@符号表示边的 rank,在 openCypher 中,没有 rank 概念。

匹配边

历史版本兼容性

在 Nebula Graph 3.0.0 之前,匹配边的前提是边本身有对应属性的索引,否则,用户无法基于边执行 MATCH 语句。从 Nebula Graph 3.0.0 开始,匹配边可以不创建索引,但需要使用 LIMIT 限制输出结果数量,并且必须指定边的方向。

nebula> MATCH ()<-[e]-() \
        RETURN e \
        LIMIT 3;
+----------------------------------------------------+
| e                                                  |
+----------------------------------------------------+
| [:follow "player101"->"player102" @0 {degree: 90}] |
| [:follow "player103"->"player102" @0 {degree: 70}] |
| [:follow "player135"->"player102" @0 {degree: 80}] |
+----------------------------------------------------+

匹配 Edge type

和点一样,用户可以用:<edge_type>表示模式中的 Edge type,例如-[e:follow]-

历史版本兼容性

在 Nebula Graph 3.0.0 之前,匹配 Edge Type 的前提是 Edge type 本身有对应属性的索引,否则,用户无法基于 Edge Type 执行 MATCH 语句。从 Nebula Graph 3.0.0 开始,匹配 Edge Type 可以不创建索引,但需要使用 LIMIT 限制输出结果数量,并且必须指定边的方向。

nebula> MATCH ()-[e:follow]->() \
        RETURN e \
        limit 3;
+----------------------------------------------------+
| e                                                  |
+----------------------------------------------------+
| [:follow "player102"->"player100" @0 {degree: 75}] |
| [:follow "player102"->"player101" @0 {degree: 75}] |
| [:follow "player129"->"player116" @0 {degree: 90}] |
+----------------------------------------------------+

匹配边的属性

Note

匹配边的属性的前提是 Edge type 本身有对应属性的索引,否则,用户无法执行 MATCH 语句匹配该属性。

用户可以用{<prop_name>: <prop_value>}表示模式中 Edge type 的属性,例如[e:follow{likeness:95}]

nebula> MATCH (v:player{name:"Tim Duncan"})-[e:follow{degree:95}]->(v2) \
        RETURN e;
+--------------------------------------------------------+
| e                                                      |
+--------------------------------------------------------+
| [:follow "player100"->"player101" @0 {degree: 95}]     |
| [:follow "player100"->"player125" @0 {degree: 95}]     |
+--------------------------------------------------------+

匹配多个 Edge type

使用|可以匹配多个 Edge type,例如[e:follow|:serve]。第一个 Edge type 前的英文冒号(:)不可省略,后续 Edge type 前的英文冒号可以省略,例如[e:follow|serve]

Note

同时匹配多个 Tag 和多个 Edge type 时,不支持进行属性过滤。

例如,不支持MATCH (v)-[e:follow|serve]->(v2) where v.player.name=="Tim Duncan" RETURN e limit 10;,其中(v)代表匹配点的所有 Tag。

nebula> MATCH (v:player{name:"Tim Duncan"})-[e:follow|:serve]->(v2) \
        RETURN e;
+---------------------------------------------------------------------------+
| e                                                                         |
+---------------------------------------------------------------------------+
| [:follow "player100"->"player101" @0 {degree: 95}]                        |
| [:follow "player100"->"player125" @0 {degree: 95}]                        |
| [:serve "player100"->"team204" @0 {end_year: 2016, start_year: 1997}]     |
+---------------------------------------------------------------------------+

匹配多条边

用户可以扩展模式,匹配路径中的多条边。

nebula> MATCH (v:player{name:"Tim Duncan"})-[]->(v2)<-[e:serve]-(v3) \
        RETURN v2, v3;
+----------------------------------+-----------------------------------------------------------+
| v2                               | v3                                                        |
+----------------------------------+-----------------------------------------------------------+
| ("team204" :team{name: "Spurs"}) | ("player104" :player{age: 32, name: "Marco Belinelli"})   |
| ("team204" :team{name: "Spurs"}) | ("player101" :player{age: 36, name: "Tony Parker"})       |
| ("team204" :team{name: "Spurs"}) | ("player102" :player{age: 33, name: "LaMarcus Aldridge"}) |
...

匹配定长路径

用户可以在模式中使用:<edge_type>*<hop>匹配定长路径。hop必须是一个非负整数。

nebula> MATCH p=(v:player{name:"Tim Duncan"})-[e:follow*2]->(v2) \
        RETURN DISTINCT v2 AS Friends;
+-----------------------------------------------------------+
| Friends                                                   |
+-----------------------------------------------------------+
| ("player100" :player{age: 42, name: "Tim Duncan"})        |
| ("player125" :player{age: 41, name: "Manu Ginobili"})     |
| ("player102" :player{age: 33, name: "LaMarcus Aldridge"}) |
+-----------------------------------------------------------+

如果hop为 0,模式会匹配路径上的起始点。

nebula> MATCH (v:player{name:"Tim Duncan"}) -[*0]-> (v2) \
        RETURN v2;
+----------------------------------------------------+
| v2                                                 |
+----------------------------------------------------+
| ("player100" :player{age: 42, name: "Tim Duncan"}) |
+----------------------------------------------------+

匹配变长路径

用户可以在模式中使用:<edge_type>*[minHop..maxHop]匹配变长路径。

Caution

如果未设置 maxHop 可能会导致 graph 服务 OOM,请谨慎执行该命令。

参数 说明
minHop 可选项。表示路径的最小长度。minHop必须是一个非负整数,默认值为 1。
maxHop 可选项。表示路径的最大长度。maxHop必须是一个非负整数,默认值为无穷大。

如果未指定minHopmaxHop,仅设置了:<edge_type>*,则二者都应用默认值,即minHop为 1,maxHop为无穷大。

nebula> MATCH p=(v:player{name:"Tim Duncan"})-[e:follow*]->(v2) \
        RETURN v2 AS Friends;
+-----------------------------------------------------------+
| Friends                                                   |
+-----------------------------------------------------------+
| ("player125" :player{age: 41, name: "Manu Ginobili"})     |
| ("player101" :player{age: 36, name: "Tony Parker"})       |
...

nebula> MATCH p=(v:player{name:"Tim Duncan"})-[e:follow*1..3]->(v2) \
        RETURN v2 AS Friends;
+-----------------------------------------------------------+
| Friends                                                   |
+-----------------------------------------------------------+
| ("player101" :player{age: 36, name: "Tony Parker"})       |
| ("player125" :player{age: 41, name: "Manu Ginobili"})     |
| ("player100" :player{age: 42, name: "Tim Duncan"})        |
...

nebula> MATCH p=(v:player{name:"Tim Duncan"})-[e:follow*1..]->(v2) \
        RETURN v2 AS Friends;
+-----------------------------------------------------------+
| Friends                                                   |
+-----------------------------------------------------------+
| ("player125" :player{age: 41, name: "Manu Ginobili"})     |
| ("player101" :player{age: 36, name: "Tony Parker"})       |
| ("player100" :player{age: 42, name: "Tim Duncan"})        |
...

用户可以使用DISTINCT关键字聚合重复结果。

nebula> MATCH p=(v:player{name:"Tim Duncan"})-[e:follow*1..3]->(v2:player) \
        RETURN DISTINCT v2 AS Friends, count(v2);
+-----------------------------------------------------------+-----------+
| Friends                                                   | count(v2) |
+-----------------------------------------------------------+-----------+
| ("player102" :player{age: 33, name: "LaMarcus Aldridge"}) | 1         |
| ("player100" :player{age: 42, name: "Tim Duncan"})        | 4         |
| ("player101" :player{age: 36, name: "Tony Parker"})       | 3         |
| ("player125" :player{age: 41, name: "Manu Ginobili"})     | 3         |
+-----------------------------------------------------------+-----------+

如果minHop0,模式会匹配路径上的起始点。例如,与上个示例相比,下面的示例设置minHop0。此时,因为表示"Tim Duncan"的点是路径的起始点,所以它在结果集中的计数为 5,比在上个示例的结果中多计一次。

nebula> MATCH p=(v:player{name:"Tim Duncan"})-[e:follow*0..3]->(v2:player) \
        RETURN DISTINCT v2 AS Friends, count(v2);
+-----------------------------------------------------------+-----------+
| Friends                                                   | count(v2) |
+-----------------------------------------------------------+-----------+
| ("player102" :player{age: 33, name: "LaMarcus Aldridge"}) | 1         |
| ("player100" :player{age: 42, name: "Tim Duncan"})        | 5         |
| ("player125" :player{age: 41, name: "Manu Ginobili"})     | 3         |
| ("player101" :player{age: 36, name: "Tony Parker"})       | 3         |
+-----------------------------------------------------------+-----------+

匹配多个 Edge type 的变长路径

用户可以在变长或定长模式中指定多个 Edge type。hopminHopmaxHop对所有 Edge type 都生效。

nebula> MATCH p=(v:player{name:"Tim Duncan"})-[e:follow|serve*2]->(v2) \
        RETURN DISTINCT v2;
+-----------------------------------------------------------+
| v2                                                        |
+-----------------------------------------------------------+
| ("team204" :team{name: "Spurs"})                          |
| ("player100" :player{age: 42, name: "Tim Duncan"})        |
| ("team215" :team{name: "Hornets"})                        |
| ("player125" :player{age: 41, name: "Manu Ginobili"})     |
| ("player102" :player{age: 33, name: "LaMarcus Aldridge"}) |
+-----------------------------------------------------------+

匹配多个模式

用户可以用英文逗号(,)分隔多个模式。

nebula> MATCH (v1:player{name:"Tim Duncan"}), (v2:team{name:"Spurs"}) \
        RETURN v1,v2;
+----------------------------------------------------+----------------------------------+
| v1                                                 | v2                               |
+----------------------------------------------------+----------------------------------+
| ("player100" :player{age: 42, name: "Tim Duncan"}) | ("team204" :team{name: "Spurs"}) |
+----------------------------------------------------+----------------------------------+

匹配最短路径

用户可以用 shortestPath 表示模式中的路径。

nebula> MATCH p = shortestPath((a:player)-[e:follow*..2]-(b:player))\
        WHERE a.player.age >  45 AND b.player.age < 30 \
        RETURN p;
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| p                                                                                                                                                                                                                         |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| <("player144" :player{age: 47, name: "Shaquille O'Neal"})-[:follow@0 {degree: 80}]->("player100" :player{age: 42, name: "Tim Duncan"})<-[:follow@0 {degree: 99}]-("player113" :player{age: 29, name: "Dejounte Murray"})> |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

多MATCH检索

不同的模式有不同的筛选条件时,可以使用多MATCH,会返回模式完全匹配的行。

nebula> MATCH (m)-[]->(n) WHERE id(m)=="player100" \
        MATCH (n)-[]->(l) WHERE id(n)=="player125" \
        RETURN id(m),id(n),id(l);
+-------------+-------------+-------------+
| id(m)       | id(n)       | id(l)       |
+-------------+-------------+-------------+
| "player100" | "player125" | "team204"   |
| "player100" | "player125" | "player100" |
+-------------+-------------+-------------+

OPTIONAL MATCH检索

参见OPTIONAL MATCH

Performance

Nebula Graph 3.2.0 中MATCH语句的性能和资源占用得到了优化.但对性能要求较高时,仍建议使用 GO, LOOKUP, |FETCH 等来替代MATCH


最后更新: August 12, 2022