Azure Digital Twins クエリ言語リファレンス: MATCH 句

このドキュメントには、Azure Digital Twins クエリ言語の MATCH 句に関するリファレンス情報が含まれています。

MATCH 句は、Azure Digital Twins クエリ言語で FROM 句の一部として使用されます。 MATCH では、Azure Digital Twins グラフで関係を走査している間に従う必要のあるパターンを指定できます (これは、"変数ホップ" クエリ パターンとも呼ばれます)。

この句はクエリの実行時に省略可能です。

コア構文: MATCH

MATCH では、特定のリレーションシップ条件に基づいて、一連のホップ内のツイン間のパスを見つけるあらゆるクエリがサポートされます。

リレーションシップ条件には、次の 1 つまたは複数の詳細情報を含めることができます。

• リレーションシップ方向 (左から右、右から左、または非方向)
• リレーションシップ名 (単一の名前または可能性の一覧)
• あるツインから別のツインへの "ホップ" 数 (正確な数または範囲)
• クエリ テキスト内のリレーションシップを表すクエリ変数の割り当て。 これにより、リレーションシップのプロパティに基づいてフィルター処理を行うこともできます。

また、MATCH 句を使用するクエリでは、WHERE 句も使用して、少なくとも 1 つの参照先ツインの $dtId を指定する必要があります。

構文

次に基本的な MATCH 構文を示します。

これには、次のプレースホルダーが含まれています。

• twin_or_twin_collection (x2): MATCH 句には、1 つのツインを表すオペランドが 1 つ必要です。 もう 1 つのオペランドは、別の 1 つのツインまたはツイン コレクションを表すことができます。
• relationship_condition: この空間で、ツインまたはツイン コレクション間のリレーションシップを記述する条件を定義します。 この条件では、リレーションシップの方向、リレーションシップ名、ホップ数、リレーションシップ プロパティ、またはこれらのオプションの任意の組み合わせを指定できます。
• twin_ID: ここでは、オペランドのいずれかが 1 つのツインを表すよう、いずれかのツイン コレクションの中で $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 は、$dtId が Building21 の Building ツインからのすべてのリレーションシップの対象になっており、
• Sensor の温度が 50 度を超えています。 Building と Sensor は両方ともクエリ結果に含まれます。

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

リレーションシップ方向を指定する

MATCH 句でリレーションシップ条件を使用して、ツイン間のリレーションシップ方向を指定します。 可能な方向には、左から右、右から左、非方向があります。 循環リレーションシップが自動的に検出され、その結果、リレーションシップは 1 回だけ走査されます。

構文

方向付けされたリレーションシップの説明では、矢印の外形を使用して、リレーションシップ方向を示します。 矢印には、省略可能なリレーションシップ名用に角かっこ ([]) で確保されたスペースが含まれます。

このセクションでは、リレーションシップのさまざまな方向の構文について説明します。 実際の値に置き換える必要のあるプレースホルダー値は、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 の温度値が 50 度を超えています
• Factory の $dtId は 'ABC' です

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

次の例では、右から左方向のトラバーサルが示されています。 このクエリは上の例と同じように見えますが、Room と Factory の間のリレーションシップの方向が逆になっています。 このクエリでは、次の場合の Room と Factory のツインが検索されます。

• Factory の対象が Room になっています (リレーションシップ名は任意)
• Factory の $dtId は 'ABC' です
• Room の温度値が 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 の湿度値が 70 を超えています

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

リレーションシップ名を指定する

必要に応じて、MATCH 句でリレーションシップ条件を使用して、ツイン間のリレーションシップの名前を指定できます。 1 つの名前を指定することも、使用可能な名前の一覧を指定することもできます。 オプションのリレーションシップ名は、リレーションシップ方向を指定する矢印構文の一部に含まれています。

リレーションシップ名を指定しない場合、既定で、すべてのリレーションシップ名がクエリに含まれます。

構文

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

(既定値) 名前を未指定のままにするには、次のように名前情報のかっこを空のままにします。

-- 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 句で走査するホップ数を角かっこ ([]) で囲んで指定します。

正確なホップ数を指定するには、次の構文を使用します。 実際の値に置き換える必要のあるプレースホルダー値は、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 ...

(既定値) 既定で 1 つのホップに設定するには、次のようにホップ情報のかっこを空のままにします。

-- 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 である (つまりホップ数は 2 か 3) Floor と Room のツイン間のリレーションシップを返します。

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

1 つの境界のみを指定して範囲を表示することもできます。 次の例では、クエリにより、ホップ数が 2 以下である (つまりホップ数は 1 か 2) Floor と Room のツイン間のリレーションシップが返されます。

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

次の例では、ホップ数が指定されていないので、Floor と Room のツイン間は既定で 1 ホップに設定されます。

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

クエリ変数をリレーションシップに割り当てる (およびリレーションシップのプロパティを指定する)

必要に応じて、MATCH 句で参照されているリレーションシップにクエリ変数を割り当てることができ、その結果、クエリ テキスト内でそれを名前で参照できます。

このようにすると、WHERE 句でリレーションシップのプロパティに基づいてフィルター処理する機能で役立ちます。

構文

リレーションシップにクエリ変数を割り当てるには、変数名を角かっこ ([]) で囲みます。 実際の値に置き換える必要のある下記のプレースホルダー値は、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' の name プロパティが必要であることを指定します。

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'

リレーションシップ方向、リレーションシップ名、リレーションシップの名前付きクエリ変数を組み合わせた例を次に示します。 次のクエリは、Floor と Room のツインを検索します。ここでは、Floor と Room のリレーションシップは、クエリ変数 r に割り当てられ、次の条件を満たします。

• リレーションシップが左から右であり、Floor がソースに、Room がターゲットになっています
• リレーションシップの名前は 'contains' と 'isAssociatedWith' のどちらかです
• リレーションシップには、クエリ変数 r が指定され、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 が指定されたリレーションシップに、10 に等しい長さプロパティがあります
• Cafe と Room の間のリレーションシップは次の条件を満たします。
  • Room をソース、Cafe をターゲットとした左から右へのリレーションシップです
  • リレーションシップの名前は 'has' と 'includes' のどちらかです
  • リレーションシップのホップ数は最大 3 (つまり、1、2、または 3) です

また、このクエリでは、ツイン Floor の $dtId が 'thermostat-15' であり、ツイン Cafe の温度が 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 の温度が 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 式は 1 つのみです。

• $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 クエリは、予期せずこのツインを結果から削除することがあります。