你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure 数字孪生查询语言参考：MATCH 子句

项目
03/25/2023

本文档包含有关 Azure 数字孪生查询语言 MATCH 子句的参考信息。

MATCH 子句在 Azure 数字孪生查询语言中是 FROM 子句的一部分。 MATCH 允许指定在遍历 Azure 数字孪生图中的关系时应该遵循的模式（这也称为“变量跃点”查询模式）。

在查询时，此子句为可选项。

核心语法：MATCH

MATCH 支持根据某些关系条件在一个跃点范围内查找孪生体之间路径的任何查询。

关系方向可能包括以下一种或多种具体情况：

关系方向（从左到右、从右到左或无方向）
关系名称（单个名称或可能性列表）
从一个孪生体到另一个孪生体的“跃点”数（具体的数字或范围）
查询变量赋值，用于表示查询文本中的关系。该查询变量还允许筛选关系属性。

具有 MATCH 子句的查询还必须使用 WHERE 子句为它引用的至少一个孪生体指定 $dtId 属性值。

注意

MATCH 是可在查询存储中执行的所有 JOIN 查询的超集。

语法

基本 MATCH 语法如下。

它包含以下占位符：

twin_or_twin_collection (x2)：MATCH 子句需要一个操作数来表示单个孪生体。另一个操作数可以表示另一个单个孪生体或孪生体的集合。
relationship_condition：在此空间中，定义描述孪生体或孪生体集合之间的关系的条件。条件可以指定关系方向、指定关系名称、指定跃点数、指定关系属性或这些选项的任意组合。
twin_ID：此处，在其中一个孪生体集合中指定一个 $dtId，以便其中一个操作数表示单个孪生体。

--SELECT ... FROM ...  
MATCH (twin_or_twin_collection_1)-[relationship_condition]-(twin_or_twin_collection_2)
WHERE twin_or_twin_collection.$dtId = 'twin_ID' 
-- AND ...

可以将其中一个孪生体集合留空，以允许任何孪生体在该位置工作。

你还可以更改关系条件的数量，以便具有多个链接的关系条件或无任何关系条件：

--Chained relationship conditions
-- SELECT ... FROM ... 
MATCH (twin_or_twin_collection_1)-[relationship_condition]-(twin_or_twin_collection_2)-[relationship_condition]-(twin_or_twin_collection_3)...
WHERE twin_or_twin_collection.$dtId = 'twin_ID'

-- No relationship condition
-- SELECT ... FROM ... 
MATCH (twin_or_twin_collection_1)
WHERE twin_or_twin_collection.$dtId = 'twin_ID'

有关每种类型的关系条件以及如何组合它们的详细信息，请参阅本文档的其他部分。

示例

下面是一个使用 MATCH 的示例查询。

查询指定关系方向，并搜索孪生体 Building 和 Sensor，其中…

Sensor 是 Building 的目标，二者之间可为任何关系，Building 孪生体的 $dtId 属性值为“Building21”，并且
Sensor 的 temperature 值大于 50。 Building 和 Sensor 都包含在查询结果中。

SELECT Building, Sensor FROM DIGITALTWINS 
MATCH (Building)-[]->(Sensor) 
WHERE Building.$dtId = 'Building21' AND Sensor.temperature > 50

指定关系方向

使用 MATCH 子句中的关系条件指定孪生体之间的关系方向。可能的方向包括从左到右、从右到左或无方向。自动检测循环关系，以便只遍历一次关系。

注意

通过使用链接，可以表示双向关系。

语法

注意

本部分中的示例重点介绍关系方向。这些示例未指定关系名称，默认为单个跃点，并且不向关系分配查询变量。有关如何使用这些其他条件执行更多操作的说明，请参阅指定关系名称、指定跃点数以及将查询变量分配给关系。有关如何在同一查询中同时使用其中多个条件的说明，请参阅组合 MATCH 操作。

方向关系说明使用箭头这一可视化描述来指示关系的方向。箭头包含一个使用方括号 ([]) 预留的位置，用于设置可选的关系名称。

本部分介绍不同关系方向的语法。 source_twin_or_twin_collection 和target_twin_or_twin_collection 这两个占位符的值应替换为你自己的值。

对于从左到右的关系，请使用以下语法。

-- SELECT ... FROM ...
MATCH (source_twin_or_twin_collection)-[]->(target_twin_or_twin_collection)
-- WHERE ...

对于从右到左的关系，请使用以下语法。

-- SELECT ... FROM ...
MATCH (target_twin_or_twin_collection)<-[]-(source_twin_or_twin_collection)
-- WHERE ...

对于无方向的关系，请使用以下语法。这不会为关系指定方向，因此任何方向的关系都将包含在结果中。

-- SELECT ... FROM ...
MATCH (source_twin_or_twin_collection)-[]-(target_twin_or_twin_collection)
-- WHERE ...

提示

无方向查询需要进行额外处理，这可能会导致延迟和成本增加。

示例

第一个示例介绍从左到右方向的遍历。此查询查找孪生体 Room 和 Factory，其中…

Room 的目标方向为 Factory（包含任何关系名称）
Room 的 temperature 值大于 50
Factory 的 $dtId 属性值为“ABC”

SELECT Room, Factory FROM DIGITALTWINS MATCH (Room)-[]->(Factory) 
WHERE Room.temperature > 50 AND Factory.$dtId = 'ABC'

注意

如果对 MATCH 遍历的起始孪生之外的任何其他孪生执行包含 $dtId 筛选器的查询，则可能会显示空结果。这适用于上述示例中的 factory.$dtId。有关详细信息，请参阅限制。

以下示例介绍从右到左方向的遍历。此查询类似于上面的查询，但 Room 和 Factory 之间的关系方向相反。此查询查找孪生体 Room 和 Factory，其中…

Factory 的目标方向为 Room（包含任何关系名称）
Factory 的 $dtId 属性值为“ABC”
Room 的 temperature 值大于 50

SELECT Room, Factory FROM DIGITALTWINS MATCH (Room)<-[]-(Factory) 
WHERE Factory.$dtId = 'ABC' AND Room.temperature > 50

以下示例介绍无方向的遍历。此查询查找孪生体 Room 和 Factory，其中…

Room 和 Factory 共享任何关系名称，且关系可以是任一方向
Factory 的 $dtId 属性值为“ABC”
Room 的 humidity 值大于 70

SELECT Factory, Room FROM DIGITALTWINS MATCH (Factory)-[]-(Room) 
WHERE Factory.$dtId ='ABC'  AND Room.humidity > 70

指定关系名称

（可选）可以使用 MATCH 子句中的关系条件来指定孪生体之间的关系名称。可以指定单个名称或可能的名称列表。此可选关系名称是用于指定关系方向的箭头语法的一部分。

如果未提供关系名称，默认情况下，查询将包含所有关系名称。

提示

在查询中指定关系名称可以提高性能和结果的可预测性。

语法

注意

本部分中的示例重点介绍关系名称。这些示例显示为无方向关系，默认为单个跃点，并且不向关系分配查询变量。有关如何使用这些其他条件执行更多操作的说明，请参阅指定关系方向、指定跃点数以及将查询变量分配给关系。有关如何在同一查询中同时使用其中多个条件的说明，请参阅组合 MATCH 操作。

在 MATCH 子句中，于方括号 ([]) 中的冒号 (:) 后，指定要遍历的关系名称。本部分介绍指定关系名称的语法。

对于单个名称，请使用以下语法。 twin_or_twin_collection_1、relationship_name 和 twin_or_twin_collection_2 这三个占位符的值应替换为你自己的值。

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)-[:relationship_name]-(twin_or_twin_collection_2)
-- WHERE ...

对于多个可能的名称，请使用以下语法。 twin_or_twin_collection_1、relationship_name_option_1、relationship_name_option_2 和 twin_or_twin_collection_2 这四个占位符的值应替换为你自己的值，并可按照示例中的模式继续输入所需数量的关系名称。

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)-[:relationship_name_option_1|relationship_name_option_2|continue pattern as needed...]-(twin_or_twin_collection_2)
-- WHERE ...

重要

方括号中的冒号 (:) 是用于在 MATCH 查询中指定关系名称的语法的必需部分。如果未包含冒号，则查询不会指定关系名称。而你有一个将查询变量分配给关系的查询。

要将名称保留为未指定（默认设置），请将方括号中的名称信息留空，如下所示：

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)-[]-(twin_or_twin_collection_2)
-- WHERE ...

示例

以下示例介绍单个关系名称。此查询查找孪生体 Building 和 Sensor，其中…

Building 和 Sensor 具有“contains”关系（可以是任一方向）
Building 的 $dtId 为“Seattle21”

SELECT Building, Sensor FROM DIGITALTWINS   
MATCH (Building)-[:contains]-(Sensor)  
WHERE Building.$dtId = 'Seattle21'

以下示例介绍多个可能的关系名称。此查询类似于上面的查询，但结果中包含多个可能的关系名称。此查询查找孪生体 Building 和 Sensor，其中…

Building 和 Sensor 具有“contains”或“isAssociatedWith”关系（可以是任一方向）
Building 的 $dtId 为“Seattle21”

SELECT Building, Sensor FROM DIGITALTWINS   
MATCH (Building)-[:contains|isAssociatedWith]-(Sensor)  
WHERE building.$dtId = 'Seattle21'

以下示例没有指定的关系名称。因此，查询结果中将包含具有任何名称的关系。此查询查找孪生体 Building 和 Sensor，其中…

Building 和 Sensor 的关系可以为任何名称（可以是任一方向）
Building 的 $dtId 为“Seattle21”

SELECT Building, Sensor FROM DIGITALTWINS   
MATCH (Building-[]-(Sensor)  
WHERE Building.$dtId = 'Seattle21'

指定跃点数

（可选）可以使用 MATCH 子句中的关系条件来指定孪生体之间的跃点数。可以指定具体的数字或范围。此可选值是用于指定关系方向的箭头语法的一部分。

如果未提供跃点数，则查询将默认为一个跃点。

重要

如果指定的跃点数量大于 1，则不能将查询变量分配给关系。在同一查询中只能使用其中一个条件。

语法

注意

本部分中的示例重点介绍跃点数。这些示例均显示为无方向关系，并且不指定名称。有关如何使用这些其他条件执行更多操作的说明，请参阅指定关系方向和指定关系名称。有关如何在同一查询中同时使用其中多个条件的说明，请参阅组合 MATCH 操作。

MATCH 子句中使用方括号 ([]) 来指定要遍历的跃点数。

要指定具体的跃点数，请使用以下语法。 twin_or_twin_collection_1、number_of_hops 和 twin_or_twin_collection_2 这三个占位符的值应替换为你自己的值。

-- SELECT ... FROM ... 
MATCH (twin_or_twin_collection_1)-[*number_of_hops]-(twin_or_twin_collection_2)
-- WHERE ...

要指定跃点数的范围，请使用以下语法。 twin_or_twin_collection_1、starting_limit、ending_limit 和 twin_or_twin_collection_2 这四个占位符的值应替换为你自己的值。范围内不包括起始限制，但包括结束限制。

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)-[*starting_limit..ending_limit]-(twin_or_twin_collection_2)
-- WHERE ...

还可以省略开始限制数，用于表示“从任意值开始到”（且包括）结束限制数。必须始终提供结束限制数。

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)-[*..ending_limit]-(twin_or_twin_collection_2)
-- WHERE ...

要默认为一个跃点（默认设置），请将跃点信息的方括号留空，如下所示：

-- SELECT ... FROM ... 
MATCH (twin_or_twin_collection_1)-[]-(twin_or_twin_collection_2)
-- WHERE ...

示例

以下示例指定了具体的跃点数。查询将仅返回孪生体 Floor 和 Room 之间具有正好 3 个跃点的关系。

SELECT Floor, Room FROM DIGITALTWINS 
MATCH (Floor)-[*3]-(Room)
WHERE Floor.$dtId = 'thermostat-15'

以下示例指定了跃点数范围。查询将返回孪生体 Floor 和 Room 之间具有 1 到 3 个跃点的关系（意味着跃点数可以为 2 或 3）。

SELECT Floor, Room FROM DIGITALTWINS 
MATCH (Floor)-[*1..3]-(Room)
WHERE Floor.$dtId = 'thermostat-15'

也可以只提供一个边界值来显示范围。在以下示例中，查询将返回孪生体 Floor 和 Room 之间最多具有 2 个跃点的关系（意味着跃点数可以为 1 或 2）。

SELECT Floor, Room FROM DIGITALTWINS 
MATCH (Floor)-[*..2]-(Room)
WHERE Floor.$dtId = 'thermostat-15'

以下示例没有指定的跃点数，因此孪生体 Floor 和 Room 之间默认为一个跃点。

SELECT Floor, Room FROM DIGITALTWINS  
MATCH (Floor)-[]-(Room)
WHERE Floor.$dtId = 'thermostat-15'

将查询变量分配给关系（并指定关系属性）

（可选）可以将查询变量分配给 MATCH 子句中引用的关系，以便在查询文本中按名称引用该变量。

执行此操作的一个有用结果是能够筛选 WHERE 子句中的关系属性。

重要

只有当查询指定单个跃点时，才支持将查询变量分配给关系。在查询中，必须在指定关系变量和指定更多跃点数二者之间选择其一。

语法

注意

本部分中的示例重点介绍关系的查询变量。这些示例均显示为无方向关系，并且不指定名称。有关如何使用这些其他条件执行更多操作的说明，请参阅指定关系方向和指定关系名称。有关如何在同一查询中同时使用其中多个条件的说明，请参阅组合 MATCH 操作。

要将查询变量分配给关系，请将变量名置于方括号 ([]) 中。下面显示的三个占位符（即 twin_or_twin_collection_1、relationship_variable 和 twin_or_twin_collection_2）的值应替换为你自己的值。

-- SELECT ... FROM ...   
MATCH (twin_or_twin_collection_1)-[relationship_variable]-(twin_or_twin_collection_2>) 
-- WHERE ...

示例

以下示例将查询变量“Rel”分配给关系。然后，在 WHERE 子句中，使用此变量指定关系 Rel 的名称属性值为“child”。

SELECT Floor,Cafe, Rel DIGITALTWINS   
MATCH (Floor)-[Rel]-(Cafe)  
WHERE Floor.$dtId = 'thermostat-15' AND Rel.name = 'child'

组合 MATCH 操作

可以在同一查询中组合多个关系条件。还可以链接多个关系条件来表示双向关系或其他更大的组合。

语法

在单个查询中，可将关系方向、关系名称以及跃点数或查询变量赋值二者之一组合使用。

以下语法示例介绍如何组合这些属性。还可以省略占位符中显示的任何可选详细信息，以忽略这部分条件。

要在单个查询中指定关系方向、关系名称和跃点数，请在关系条件中使用以下语法。 twin_or_twin_collection_1 和 twin_or_twin_collection_2、optional_left_angle_bracket 和 optional_right_angle_bracket、relationship_name(s) 和 number_of_hops 这些占位符的值应替换为你自己的值。

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)optional_left_angle_bracket-[:relationship_name(s)*number_of_hops]-optional_right_angle_bracket(twin_or_twin_collection_2)
-- WHERE

要在单个查询中指定关系方向、关系名称和关系的查询变量，请在关系条件中使用以下语法。 twin_or_twin_collection_1 和 twin_or_twin_collection_2、optional_left_angle_bracket 和 optional_right_angle_bracket、relationship_variable 和 relationship_name(s) 这些占位符的值应替换为你自己的值。

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)optional_left_angle_bracket-[relationship_variable:relationship_name(s)]-optional_right_angle_bracket(twin_or_twin_collection_2)
-- WHERE

注意

根据指定关系方向的选项，必须在左尖括号（表示从右到左的关系）或右尖括号（表示从左到右的关系）之间选择其一。不能在同一箭头上同时包含这两者，但可以通过链接来表示双向关系。

可以将多个关系条件链接在一起，如下所示。 twin_or_twin_collection_1、relationship_condition 的所有实例和 twin_or_twin_collection_2 这些占位符的值应替换为你自己的值。

--Chained relationship conditions
-- SELECT ... FROM ... 
MATCH (twin_or_twin_collection_1)-[relationship_condition]-(twin_or_twin_collection_2)-[relationship_condition]-(twin_or_twin_collection_3)...
WHERE twin_or_twin_collection.$dtId = 'twin_ID'

示例

以下示例组合了关系方向、关系名称和跃点数。以下查询查找孪生体 floor 和 room，其中 floor 和 room 之间的关系满足以下条件：

关系为从左到右方向，以 Floor 为源，Room 为目标
关系名称为“contains”或“isAssociatedWith”
关系有 4 个或 5 个跃点

查询还指定孪生体 Floor 的 $dtId 为“thermostat-15”。

SELECT Floor, Room FROM DIGITALTWINS    
MATCH (Floor)-[:contains|isAssociatedWith*3..5]->(Room) 
WHERE Floor.$dtId = 'thermostat-15'

以下示例组合了关系方向、关系名称和已命名的关系查询变量。以下查询查找两者之间的关系已分配查询变量 r 并满足以下条件的孪生体 Floor 和 Room：

关系为从左到右方向，以 Floor 为源，Room 为目标
关系名称为“contains”或“isAssociatedWith”
已分配查询变量 r 的关系，其 length 属性等于 10

查询还指定孪生体 Floor 的 $dtId 为“thermostat-15”。

SELECT Floor, Room FROM DIGITALTWINS    
MATCH (Floor)-[r:contains|isAssociatedWith]->(Room) 
WHERE Floor.$dtId = 'thermostat-15' AND r.length = 10

下面的示例阐释了链接关系条件。此查询查找孪生体 Floor、Cafe 和 Room，其中…

Floor 与 Room 之间的关系满足以下条件：
- 关系为从左到右方向，以 Floor 为源，Cafe 为目标
- 关系名称为“contains”或“isAssociatedWith”
- 已分配查询变量 r 的关系，其 length 属性等于 10
Cafe 与 Room 之间的关系满足以下条件：
- 关系为从右到左方向，以 Room 为源，Cafe 为目标
- 关系名称为“has”或“includes”
- 关系最多有 3（即 1、2 或 3）个跃点

查询还指定孪生体 Floor 的 $dtId 为“thermostat-15”，而孪生体 Cafe 的 temperature 值为 55。

SELECT Floor,Room, Cafe FROM DIGITALTWINS    
MATCH (Floor)-[r:contains|isAssociatedWith]->(Cafe)<-[has|includes*..3]-(Room)  
WHERE Floor.$dtId = 'thermostat-15'  AND r.length = 10 AND Cafe.temperature = 55

还可使用链接关系条件来表示双向关系。以下查询查找孪生体 Floor、Room 和 Building，其中…

Building 与 Floor 之间的关系满足以下条件：
- 关系为从左到右方向，以 Building 为源，Floor 为目标
- 关系名称为“isAssociatedWith”
- 已为关系分配查询变量 r1
Floor 与 Room 之间的关系满足以下条件：
- 关系为从右到左方向，以 Room 为源，Floor 为目标
- 关系名称为“isAssociatedWith”
- 已为关系分配查询变量 r2

查询还指定孪生体 Building 的 $dtId 为“building-3”，而 Room 的 temperature 值大于 50。

SELECT Floor, Room, Building FROM DIGITALTWINS    
MATCH (Building)-[r1:isAssociatedWith]->(Floor)<-[r2:isAssociatedWith]-(Room)
WHERE Building.$dtId = 'building-3'  AND Room.temperature > 50

限制

以下限制适用于使用 MATCH 的查询：

每个查询语句仅支持一个 MATCH 表达式。
WHERE 子句中必须有 $dtId。
只有当查询指定单个跃点时，才支持将查询变量分配给关系。
查询中支持的最大跃点数为 10。
如果对 MATCH 遍历的起始孪生之外的任何其他孪生执行包含 $dtId 筛选器的查询，则可能会显示空结果。例如，以下查询受限于此限制：
```
SELECT A, B, C FROM DIGITALTWINS 
MATCH A-[contains]->B-[is_part_of]->C 
WHERE B.$dtId = 'Device01'
```
如果方案要求在其他孪生体上使用 $dtId，请考虑改为使用 JOIN 子句。
多次遍历同一个孪生的 MATCH 查询可能会意外地从结果中删除该孪生。

通过