翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
AWS IoT TwinMaker ナレッジグラフの追加リソース
このセクションでは、ナレッジグラフにクエリを記述するために使用されるPartiQL構文の基本的な例と、ナレッジグラフデータモデルに関する情報を提供するPartiQLドキュメントへのリンクを示します。
この一連の例は、基本的なクエリとその応答を示しています。これを参考にして、独自のクエリを作成してください。
- 基本的なクエリ
-
-
フィルターを使用してすべてのエンティティを取得
SELECT entity FROM EntityGraph MATCH (entity) WHERE entity.entityName = 'room_0'
このクエリは、ワークスペース内の同じ名前のエンティティをすべて返します
room_0
。FROM
clause:EntityGraph
は、ワークスペース内のすべてのエンティティとその関係を含むグラフコレクションです。このコレクションは、 AWS IoT TwinMaker ワークスペース内のエンティティに基づいて自動的に作成および管理されます。MATCH
句: グラフの一部と一致するパターンを指定します。この場合、パターン(entity)
はグラフ内のすべてのノードと一致し、エンティティ変数にバインドされます。FROM
句の後にはMATCH
句が続く必要があります。WHERE
clause:entityName
room_0
値が一致する必要があるノードのフィールドにフィルターを指定します。SELECT
clause:entity
エンティティノード全体が返されるように変数を指定します。レスポンス:
{ "columnDescriptions": [ { "name": "entity", "type": "NODE" } ], "rows": [ { "rowData": [ { "arn": "arn:aws:iottwinmaker:us-east-1: 577476956029: workspace / SmartBuilding8292022 / entity / room_18f3ef90 - 7197 - 53 d1 - abab - db9c9ad02781 ", "creationDate": 1661811123914, "entityId": "room_18f3ef90-7197-53d1-abab-db9c9ad02781", "entityName": "room_0", "lastUpdateDate": 1661811125072, "workspaceId": "SmartBuilding8292022", "description": "", "components": [ { "componentName": "RoomComponent", "componentTypeId": "com.example.query.construction.room", "properties": [ { "propertyName": "roomFunction", "propertyValue": "meeting" }, { "propertyName": "roomNumber", "propertyValue": 0 } ] } ] } ] } ] }
は、名前やタイプなど、
columnDescriptions
列に関するメタデータを返します。返されるタイプは、NODE
です。これはノード全体が返されたことを示しています。この型の他の値には、関係を示す値やVALUE
、整数や文字列などのスカラー値などがあります。EDGE
rows
は行のリストを返します。一致したエンティティは 1 つだけなので、エンティティのすべてのフィールドを含む 1 つのrowData
が返されます。注記
スカラー値しか返せない SQL とは異なり、PartiQL を使用してオブジェクトを (JSON として) 返すことができます。
各ノードには、、などのエンティティレベルのフィールド
entityId
、、などのコンポーネントレベルのフィールドcomponents
、arn
およびなどのプロパティレベルのフィールドがすべてネストされた JSON として格納されますpropertyName
。componentName
componentTypeId
properties
propertyValue
-
すべてのリレーションシップをフィルターで取得:
SELECT relationship FROM EntityGraph MATCH (e1)-[relationship]->(e2) WHERE relationship.relationshipName = 'isLocationOf'
このクエリは、ワークスペース内のすべてのリレーションシップをリレーション名
isLocationOf
で返します。MATCH
この句:ディレクテッド・エッジ (で示される) で接続され、という変数にバインドされている 2 つのノード (で示される()
) に一致するパターンを指定します。-[]->
relationship
WHERE
句:relationshipName
値がのエッジのフィールドにフィルターを指定します。isLocationOf
SELECT
句: エッジノード全体が返されるようリレーションシップ変数を指定します。レスポンス
{ "columnDescriptions": [{ "name": "relationship", "type": "EDGE" }], "rows": [{ "rowData": [{ "relationshipName": "isLocationOf", "sourceEntityId": "floor_83faea7a-ea3b-56b7-8e22-562f0cf90c5a", "targetEntityId": "building_4ec7f9e9-e67e-543f-9d1b- 235df7e3f6a8", "sourceComponentName": "FloorComponent", "sourceComponentTypeId": "com.example.query.construction.floor" }] }, ... //rest of the rows are omitted ] }
columnDescriptions
内のカラムのタイプはEDGE
.それぞれが、
rowData
のようなフィールドを持つエッジを表しますrelationshipName
。これはエンティティに定義されているリレーションシッププロパティ名と同じです。sourceEntityId
、、には、sourceComponentName
リレーションシッププロパティが定義されているエンティティとコンポーネントに関する情報が表示されます。sourceComponentTypeId
は、targetEntityId
このリレーションシップがどのエンティティを指しているかを指定します。 -
特定のエンティティと特定の関係を持つすべてのエンティティを取得します。
SELECT e2.entityName FROM EntityGraph MATCH (e1)-[r]->(e2) WHERE relationship.relationshipName = 'isLocationOf' AND e1.entityName = 'room_0'
このクエリは、
isLocationOf
room_0
そのエンティティと関係があるすべてのエンティティのすべてのエンティティ名を返します。MATCH
句:ディレクテッドエッジ () を持つ任意の 2 つのノード (e1
,e2
) と一致するパターンを指定します。r
WHERE
句: リレーションシップ名とソースエンティティ名のフィルターを指定します。SELECT
この句:entityName
e2
ノード内のフィールドを返します。レスポンス
{ "columnDescriptions": [ { "name": "entityName", "type": "VALUE" } ], "rows": [ { "rowData": [ "floor_0" ] } ] }
ColumnDescriptionsでは、
VALUE
カラムのタイプは文字列なのでentityName
。1 つのエンティティ
floor_0
、が返されます。
-
- MATCH
-
1
MATCH
つの節では以下のパターンがサポートされています。-
ノード 'b' がノード 'a' を指しているものと一致させます。
FROM EntityGraph MATCH (a)-[rel]-(b)
-
ノード 'a' がノード 'b' を指しているものと一致させます。
FROM EntityGraph MATCH (a)-[]->(b)
リレーションシップにフィルターを指定する必要がないと仮定すると、リレーションシップにバインドされた変数はありません。
-
ノード 'a' がノード 'b' を指し、ノード 'b' がノード 'a' を指しているものと一致させます。
FROM EntityGraph MATCH (a)-[rel]-(b)
これによって 2 つのマッチが返されます。1 つは 'a' から 'b'、もう 1 つは 'b' から 'a' なので、可能な限り有向エッジを使用することをおすすめします。
-
リレーションシップ名はプロパティグラフのラベルでもあるため
EntityGraph
、rel.relationshipName
WHERE
句内でフィルターを指定する代わりに、コロン (:) の後にリレーションシップ名を指定するだけで済みます。FROM EntityGraph MATCH (a)-[:isLocationOf]-(b)
-
チェーン: 複数のリレーションシップに一致するようにパターンを連鎖させることができます。
FROM EntityGraph MATCH (a)-[rel1]->(b)-[rel2]-(c)
-
変数ホップパターンは、複数のノードやエッジにまたがっていることもあります。
FROM EntityGraph MATCH (a)-[]->{1,5}(b)
このクエリは、ノード 'a' からの出力エッジが 1 ~ 5 ホップ以内の任意のパターンにマッチします。指定できる格量指定子は次のとおりです。
{m,n}
- m 回から n 回の間の繰り返し{m,}
- m 回以上の繰り返し。
-
- FROM:
-
エンティティノードには、コンポーネントなどのネストされたデータを含めることができ、そのデータ自体にはプロパティなどのさらにネストされたデータが含まれます。これらは、MATCH パターンの結果をネスト解除することでアクセスできます。
SELECT e FROM EntityGraph MATCH (e), e.components AS c, c.properties AS p WHERE c.componentTypeId = 'com.example.query.construction.room', AND p.propertyName = 'roomFunction' AND p.propertyValue = 'meeting'
ネストされたフィールドにアクセスするには、変数を
.
ドットで囲みます。コンマ (,) を使用して、内部のコンポーネントを含むエンティティをネスト解除 (または結合) し、次にそのコンポーネント内のプロパティをネスト解除 (または結合) します。AS
変数をネストされていない変数にバインドして、or 句で使用できるようにするために使用されます。WHERE
SELECT
このクエリは、コンポーネントタイプ IDcom.example.query.construction.room
のコンポーネント内の値meeting
と、roomFunction
という名前のプロパティを含むすべてのエンティティを返します。エンティティ内の複数のコンポーネントなど、1 つのフィールドの複数のネストされたフィールドにアクセスするには、カンマ表記を使用して結合を行います。
SELECT e FROM EntityGraph MATCH (e), e.components AS c1, e.components AS c2
- SELECT:
-
-
ノードを返す:
SELECT e FROM EntityGraph MATCH (e)
-
エッジを返す:
SELECT r FROM EntityGraph MATCH (e1)-[r]->(e2)
-
スカラー値を返す:
SELECT floor.entityName, room.description, p.propertyValue AS roomfunction FROM EntityGraph MATCH (floor)-[:isLocationOf]-(room), room.components AS c, c.properties AS p
AS
を使用してエイリアシングで出力フィールドの名前をフォーマットします。ここでは、レスポンス内の列名のpropertyValue
の代わりに、roomfunction
が返されます。 -
エイリアスを返す:
SELECT floor.entityName AS floorName, luminaire.entityName as luminaireName FROM EntityGraph MATCH (floor)-[:isLocationOf]-(room)-[:hasPart]- (lightingZone)-[:feed]-(luminaire) WHERE floor.entityName = 'floor_0' AND luminaire.entityName like 'lumin%'
明示的に指定し、読みやすくし、クエリ内のあいまいさを避けるために、エイリアスを使用することを強くお勧めします。
-
- WHERE:
-
サポートされている論理演算子は、、およびです。
AND
NOT
OR
サポートされている比較演算子は、
<
、<=
、>
、=>
、=
および!=
です。OR
同じフィールドに複数の条件を指定する場合は、IN
キーワードを使用してください。-
エンティティ、コンポーネント、またはプロパティフィールドで絞り込みます。
FROM EntityGraph MATCH (e), e.components AS c, c.properties AS p WHERE e.entityName = 'room_0' AND c.componentTypeId = 'com.example.query.construction.room', AND p.propertyName = 'roomFunction' AND NOT p.propertyValue = 'meeting' OR p.propertyValue = 'office'
-
configuration
プロパティを絞り込む。unit
Celsius
これが設定マップのキーと値です。WHERE p.definition.configuration.unit = 'Celsius'
-
マッププロパティに指定されたキーと値が含まれているかどうかを確認します。
WHERE p.propertyValue.length = 20.0
-
マッププロパティに指定されたキーが含まれているかどうかを確認します。
WHERE NOT p.propertyValue.length IS MISSING
-
リストプロパティに指定された値が含まれているかどうかを確認します。
WHERE 10.0 IN p.propertyValue
-
大文字と小文字を区別しない比較にはこの
lower()
関数を使用します。デフォルトでは、大文字と小文字を区別した比較が使用されます。WHERE lower(p.propertyValue) = 'meeting'
- LIKE:
-
フィールドの正確な値がわからず、指定したフィールドで全文検索を実行できる場合に便利です。
%
はゼロ以上を表します。WHERE e.entityName LIKE '%room%'
-
インフィックス検索:
%room%
-
プレフィックス検索:
room%
-
サフィックス検索:
%room
-
値に '%' が含まれている場合は、にエスケープ文字を入力し、エスケープ文字をで指定します
ESCAPE
。LIKE
WHERE e.entityName LIKE 'room\%' ESCAPE '\'
-
- DISTINCT:
-
SELECT DISTINCT c.componentTypeId FROM EntityGraph MATCH (e), e.components AS c
-
DISTINCT
キーワードは、最終結果から重複を排除します。DISTINCT
は複雑なデータ型ではサポートされていません。
-
- COUNT
-
SELECT COUNT(e), COUNT(c.componentTypeId) FROM EntityGraph MATCH (e), e.components AS c
COUNT
このキーワードは、クエリ結果の項目数を計算します。COUNT
ネストされた複合フィールドやグラフパターンフィールドではサポートされていません。COUNT
DISTINCT
およびネストされたクエリでは集計はサポートされていません。たとえば、
COUNT(DISTINCT e.entityId)
はサポートされません。
- パス
-
パスプロジェクションを使ったクエリでは、以下のパターンプロジェクションがサポートされています。
可変ホップクエリ
SELECT p FROM EntityGraph MATCH p = (a)-[]->{1, 3}(b)
このクエリは、ノード a からの出力エッジが 1 ~ 3 ホップ以内の任意のパターンのノードメタデータを照合して投影します。
固定ホップクエリ
SELECT p FROM EntityGraph MATCH p = (a)-[]->(b)<-[]-(c)
このクエリは、エンティティと入力エッジのメタデータを照合して b に投影します。
無向クエリ
SELECT p FROM EntityGraph MATCH p = (a)-[]-(b)-[]-(c)
このクエリは、a と c を b 経由で接続する 1 ホップパターンでノードのメタデータを照合して投影します。
{ "columnDescriptions": [ { "name": "path", "type": "PATH" } ], "rows": [ { "rowData": [ { "path": [ { "entityId": "a", "entityName": "a" }, { "relationshipName": "a-to-b-relation", "sourceEntityId": "a", "targetEntityId": "b" }, { "entityId": "b", "entityName": "b" } ] } ] }, { "rowData": [ { "path": [ { "entityId": "b", "entityName": "b" }, { "relationshipName": "b-to-c-relation", "sourceEntityId": "b", "targetEntityId": "c" }, { "entityId": "c", "entityName": "c" } ] } ] } ] }
PATH
このクエリレスポンスは、a と c の間の b 経由の各パス/パターンのすべてのノードとエッジを識別するメタデータのみで構成されます。
- リミットとオフセット:
-
SELECT e.entityName FROM EntityGraph MATCH (e) WHERE e.entityName LIKE 'room_%' LIMIT 10 OFFSET 5
LIMIT
はクエリで返される結果の数を指定し、OFFSET
はスキップする結果の数を指定します。 - 結果の上限値と最大値:
-
次の例は、合計 500 件の結果を返すクエリを示していますが、1 回に API 呼び出しごとに 50 件しか表示できません。このパターンは、UI に 50 件の結果しか表示できない場合など、表示される結果の量を制限する必要がある場合に使用できます。
aws iottwinmaker execute-query \ --workspace-id exampleWorkspace \ --query-statement "SELECT e FROM EntityGraph MATCH (e) LIMIT 500"\ --max-results 50
-
LIMIT
キーワードはクエリに影響し、結果の行を制限します。返される結果の総数を制限せずに API 呼び出しごとに返される結果の数を制御する必要がある場合は、を使用してくださいLIMIT
。 -
max-results
ExecuteQuery API アクションのオプションパラメータです。max-results
API と、上記のクエリの範囲内での結果の読み取り方法にのみ適用されます。max-results
クエリで使用すると、返される結果の実際の数を制限することなく、表示される結果の数を減らすことができます。
以下のクエリは、結果の次のページまで繰り返し処理されます。このクエリは
ExecuteQuery
API 呼び出しを使用して行 51 ~ 100 を返します。結果の次のページは、で指定されます。この場合、トークンは:です。next-token
"H7kyGmvK376L"
aws iottwinmaker execute-query \ --workspace-id exampleWorkspace \ --query-statement "SELECT e FROM EntityGraph MATCH (e) LIMIT 500"\ --max-results 50 --next-token "H7kyGmvK376L"
-
next-token
この文字列は、結果の次のページを指定します。詳細については、 ExecuteQueryAPI アクションを参照してください。
-
AWS IoT TwinMaker ナレッジグラフクエリには以下の制限があります。
制限 の名前 | クォータ | 調整可能 |
---|---|---|
クエリ実行タイムアウト |
10 秒 | いいえ |
ホップの最大数 |
10 | [Yes (はい)] |
セルフの最大数 |
20 | はい |
投影フィールドの最大数 |
20 | はい |
条件式の最大数 ( |
10 | [Yes (はい)] |
|
20 | はい |
1 つの句に指定できる項目の最大数 IN |
10 | [Yes (はい)] |
の最大値:OFFSET |
3000 | はい |
の最大値: |
3000 | はい |
トラバーサルの最大値 (+) |
3000 | はい |