Azure Digital Twins 查詢語言參考：MATCH 子句

發行項
04/04/2024

本檔包含 Azure Digital Twins 查詢語言 MATCH 子句的參考資訊。

子MATCH句會用於 Azure Digital Twins 查詢語言作為 FROM 子句的一部分。 MATCH 可讓您指定在 Azure Digital Twins 圖表中周遊關聯性時應該遵循哪個模式（也稱為「變數躍點」查詢模式）。

查詢時，這個子句是選擇性的。

核心語法：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 對應項與 $dtId Building21 的任何關聯性為目標，且
感測器的溫度高於 50。建置和感測器都包含在查詢結果中。

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

指定關聯性方向

使用子句中的 MATCH 關聯性條件來指定對應項之間的關聯性方向。可能的方向包括從左至右、由右至左或非方向。系統會自動偵測循環關聯性，以便只周遊一次關聯性。

注意

您可以使用鏈結來代表雙向關聯性。

Syntax

注意

本節中的範例著重於關聯性方向。它們不會指定關聯性名稱、預設為單一躍點，而且不會將查詢變數指派給關聯性。如需如何使用這些其他條件執行更多動作的指示，請參閱指定關聯性名稱、指定躍點數目，以及將查詢變數指派給關聯性。如需如何在相同查詢中一起使用其中數個的詳細資訊，請參閱合併 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 ...

提示

非方向查詢需要額外的處理，這可能會導致延遲和成本增加。

範例

第一個範例顯示由左至右方向周遊。此查詢會尋找對應項會議室和處理站...

會議室以工廠為目標（具有任何關聯性名稱）
會議室有大於50的溫度值
工廠有一個 $dtId 'ABC'

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

注意

MATCH 查詢，包含 $dtId MATCH 周遊之起始對應項以外的任何對應項篩選可能會顯示空的結果。這適用於 factory.$dtId 上述範例。如需詳細資訊，請參閱限制。

下列範例顯示由右至左方向周遊。此查詢看起來類似上述查詢，但 Room 和 Factory 之間的關聯性方向會反轉。此查詢會尋找對應項會議室和處理站...

工廠目標會議室（具有任何關聯性名稱）
工廠有一個 $dtId 'ABC'
會議室有大於50的溫度值

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

下列範例顯示非方向周遊。此查詢會尋找對應項會議室和處理站...

會議室和處理站共用任何關聯性名稱，往任一方向
工廠有一個 $dtId 'ABC'
會議室的濕度值大於 70

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

指定關聯性名稱

您可以選擇性地使用子句中的 MATCH 關聯性條件來指定對應項之間的關聯性名稱。您可以指定單一名稱或可能的名稱清單。選擇性關聯性名稱包含在箭頭語法中，以指定關聯性方向。

如果您未提供關聯性名稱，則查詢預設會包含所有關聯性名稱。

提示

在查詢中指定關聯性名稱可以改善效能，並讓結果更容易預測。

Syntax

注意

本節中的範例著重於關聯性名稱。它們全都會顯示非方向關聯性，預設為單一躍點，而且不會將查詢變數指派給關聯性。如需有關如何使用這些其他條件執行更多動作的指示，請參閱指定關聯性方向、指定躍點數目，以及將查詢變數指派給關聯性。如需如何在相同查詢中一起使用其中數個的詳細資訊，請參閱合併 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_2twin_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 ...

範例

下列範例顯示單一關聯性名稱。此查詢會尋找對應項建置和感測器，其中...

建築物與感測器具有「包含」關聯性（雙向）
建築有一個 $dtId 'Seattle21'

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

下列範例顯示多個可能的關聯性名稱。此查詢看起來與上述查詢類似，但結果中包含多個可能的關聯性名稱。此查詢會尋找對應項建置和感測器，其中...

建築物具有與感測器的「內含」或「isAssociatedWith」關聯性（往任一方向前進）
建築有一個 $dtId 'Seattle21'

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

下列範例沒有指定的關聯性名稱。因此，任何名稱的關聯性都會包含在查詢結果中。此查詢會尋找對應項建置和感測器，其中...

建置與感測器具有任何名稱的關聯性（且任一方向）
建築有一個 $dtId 'Seattle21'

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

指定躍點數目

您可以選擇性地使用子句中的 MATCH 關聯性條件來指定對應項之間關聯性的躍點數目。您可以指定確切的數位或範圍。這個選擇性值包含在箭頭語法中，以指定關聯性方向。

如果您未提供多個躍點，查詢會預設為一個躍點。

重要

如果您指定大於一個的躍點數目，則無法將查詢變數指派給關聯性。相同的查詢中只能使用其中一個條件。

Syntax

注意

本節中的範例著重於躍點數目。它們全都會顯示非方向關聯性，而不指定名稱。如需有關如何使用這些其他條件執行更多動作的指示，請參閱指定關聯性方向和指定關聯性名稱。如需如何在相同查詢中一起使用其中數個的詳細資訊，請參閱合併 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_limitending_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 ...

範例

下列範例會指定確切的躍點數目。查詢只會傳回只有 3 個躍點的對應項 Floor 和 Room 之間的關聯性。

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

下列範例會指定躍點的範圍。查詢會傳回介於 1 到 3 個躍點之間的對應項 Floor 和 Room 之間的關聯性（這表示躍點數目為 2 或 3）。

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

您也可以只提供一個界限來顯示範圍。在下列範例中，查詢會傳回最多 2 個躍點的對應項 Floor 和 Room 之間的關聯性（這表示躍點數目為 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 句中的關聯性屬性。

重要

只有在查詢指定單一躍點時，才支援將查詢變數指派給關聯性。在查詢中，您必須在指定關聯性變數和指定較多躍點之間選擇。

Syntax

注意

本節中的範例著重於關聯性的查詢變數。它們全都會顯示非方向關聯性，而不指定名稱。如需有關如何使用這些其他條件執行更多動作的指示，請參閱指定關聯性方向和指定關聯性名稱。如需如何在相同查詢中一起使用其中數個的詳細資訊，請參閱合併 MATCH 作業。

若要將查詢變數指派給關聯性，請將變數名稱放在方括弧中（[]）。下面顯示的佔位元值應該取代為、和 twin_or_twin_collection_2值twin_or_twin_collection_1relationship_variable。

-- 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、和 number_of_hops。 relationship_name(s)

-- 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_name(s)。 relationship_variable

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

注意

根據指定關聯性方向的選項，您必須在從左至右關聯性的左角括弧或從右至左關聯性選擇右角括弧。您無法在相同的箭號中包含這兩者，但可以鏈結來代表雙向關聯性。

您可以將多個關聯性條件鏈結在一起，如下所示。應以值取代的relationship_condition佔位元元值是 twin_or_twin_collection_1、、和 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 之間的關聯性符合下列條件：

關聯性由左至右，而 Floor 作為來源和會議室作為目標
關聯性的名稱為 'contains' 或 'isAssociatedWith'
關聯性有 4 個或 5 個躍點

查詢也會指定 Twin Floor 具有 $dtId 'thermostat-15' 的。

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

以下是結合關聯性方向、關聯性名稱和關聯性之具名查詢變數的範例。下列查詢會尋找 Floor 與 Room 之間的對應項 Floor 和 Room，其中 Floor 與 Room 之間的關聯性會指派給查詢變數 r ，並符合下列條件：

關聯性由左至右，而 Floor 作為來源和會議室作為目標
關聯性的名稱為 'contains' 或 'isAssociatedWith'
給定查詢變數 r的關聯性具有等於 10 的 length 屬性

查詢也會指定 Twin 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 作為來源和咖啡館作為目標
- 關聯性的名稱為 'contains' 或 'isAssociatedWith'
- 給定查詢變數 r的關聯性具有等於 10 的 length 屬性
Cafe 和 Room 之間的關聯性符合下列條件：
- 關聯性由右至左，而 Room 作為來源和咖啡館作為目標
- 關聯性的名稱為 'has' 或 'includes'
- 關聯性最多有 3 個躍點（因此 1、2 或 3 個）躍點

查詢也會指定雙樓有『 $dtId 控溫器-15』，而雙胞胎咖啡館的溫度為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，其中...

建築物與樓層之間的關聯性符合下列條件：
- 關聯性由左至右，建置為來源和 Floor 作為目標
- 關聯性的名稱為 'isAssociatedWith'
- 關聯性會得到查詢變數 r1
Floor 和 Room 之間的關聯性符合下列條件：
- 關聯性由右至左，而 Room 作為來源和 Floor 作為目標
- 關聯性的名稱為 'isAssociatedWith'
- 關聯性會得到查詢變數 r2

查詢也會指定雙胞胎建築具有 $dtId 『building-3』的，而 Room 的溫度大於 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 表達式。
$dtId 在子句中 WHERE 是必要的。
只有在查詢指定單一躍點時，才支援將查詢變數指派給關聯性。
查詢中支援的最大躍點為10。
MATCH 查詢，包含 $dtId MATCH 周遊之起始對應項以外的任何對應項篩選可能會顯示空的結果。例如，下列查詢受限於這項限制：
```
SELECT A, B, C FROM DIGITALTWINS 
MATCH A-[contains]->B-[is_part_of]->C 
WHERE B.$dtId = 'Device01'
```
如果您的案例要求您在其他 $dtId 對應項上使用，請考慮改用 JOIN 子句。
周遊相同對應項多次的 MATCH 查詢可能會意外地從結果中移除此對應項。

Azure Digital Twins 查詢語言參考：MATCH 子句

核心語法：MATCH

語法

範例

指定關聯性方向

Syntax

範例

指定關聯性名稱

Syntax

範例

指定躍點數目

Syntax

範例

將查詢變數指派給關聯性 （並指定關聯性屬性）

Syntax

範例

合併 MATCH 作業

語法

範例

限制

其他資源

將查詢變數指派給關聯性（並指定關聯性屬性）