翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # AWS IoT TwinMaker ナレッジグラフ ナレッジグラフ AWS IoT TwinMaker ナレッジグラフは、 AWS IoT TwinMaker ワークスペースに含まれるすべての情報を整理し、ビジュアルグラフ形式で表示します。エンティティ、コンポーネント、コンポーネントタイプに対してクエリを実行して、 AWS IoT TwinMaker リソース間のリレーションシップを示す視覚的なグラフを生成できます。 以下のトピックでは、ナレッジグラフを使用し、統合する方法について説明します。 **Topics** + [ ## AWS IoT TwinMaker ナレッジグラフの主な概念 ](#tm-knowledge-graph-concepts) + [ # AWS IoT TwinMaker ナレッジグラフクエリを実行する方法 ](tm-knowledge-graph-use.md) + [ # ナレッジグラフシーンの統合 ](tm-knowledge-graph-scene.md) + [ # Grafana で AWS IoT TwinMaker ナレッジグラフを使用する方法 ](tm-knowledge-Grafana-panel.md) + [ # AWS IoT TwinMaker ナレッジグラフの追加リソース ](tm-knowledge-graph-resources.md) ## AWS IoT TwinMaker ナレッジグラフの主な概念 このトピックでは、ナレッジグラフ機能の主要な概念と用語について説明します。 **ナレッジグラフの仕組み**: ナレッジグラフは、既存の [CreateEntity](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_CreateEntity.html) API または [ UpdateEntity](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_UpdateEntity.html) APIs を使用して、エンティティとそのコンポーネント間の関係を作成します。関係は、エンティティのコンポーネントで定義された特殊なデータ型の [RELATIONSHIP ](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_DataType.html#:~:text=Valid%20Values%3A-,RELATIONSHIP,-%7C%20STRING%20%7C%20LONG%20%7C%20BOOLEAN)のプロパティにすぎません。 AWS IoT TwinMaker ナレッジグラフは、[ExecuteQuery](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_ExecuteQuery.html) API を呼び出して、エンティティ内のデータまたはエンティティ間の関係に基づいてクエリを実行します。ナレッジグラフは、グラフ一致構文のサポートが新しく追加された柔軟な PartiQL クエリ言語 (多くの AWS サービスで使用) を使用して、クエリの記述を支援します。呼び出しが完了したら、結果をテーブルとして表示したり、接続されたノードとエッジのグラフとして視覚化したりできます。 **ナレッジグラフの主要用語**: + **エンティティグラフ**: ワークスペース内のノードとエッジの収集。 + **ノード**: ワークスペース内のすべてのエンティティがエンティティグラフのノードになります。 + **エッジ**: エンティティのコンポーネントに定義されているすべてのリレーションシッププロパティがエンティティグラフのエッジになります。さらに、エンティティの parentEntityId フィールドを使用して定義された階層的な親子関係も、エンティティグラフのisChildOf」リレーションシップ名を持つエッジになります。すべてのエッジは方向性のあるエッジです。 + **関係**: AWS IoT TwinMaker 関係は、エンティティのコンポーネントの特別なタイプのプロパティです。[ CreateEntity](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_CreateEntity.html) または [UpdateEntity](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_UpdateEntity.html) API を使用して AWS IoT TwinMaker 、関係を定義および編集できます。では AWS IoT TwinMaker、エンティティのコンポーネントで関係を定義する必要があります。リレーションシップを独立したリソースとして定義することはできません。リレーションシップは、あるエンティティから別のエンティティへの方向性がある必要があります。 # AWS IoT TwinMaker ナレッジグラフクエリを実行する方法 ナレッジグラフの使用 AWS IoT TwinMaker ナレッジグラフを使用する前に、次の前提条件を満たしていることを確認してください。 + AWS IoT TwinMaker ワークスペースを作成します。ワークスペースは、[AWS IoT TwinMaker コンソール](https://console.aws.amazon.com/iottwinmaker/)で作成できます。 + AWS IoT TwinMakerのエンティティコンポーネントシステムおよびエンティティの作成方法を理解します。詳細については、「[最初のエンティティを作成する](twinmaker-gs-entity.md)」を参照してください。 + AWS IoT TwinMakerのデータコネクタに精通します。詳細については、「[AWS IoT TwinMaker データコネクタ](data-connector-interface.md)」を参照してください。 **注記** AWS IoT TwinMaker ナレッジグラフを使用するには、**標準**または**階層バンドル**の料金モードのいずれかである必要があります。詳細については、「[AWS IoT TwinMaker 価格設定モードの切り替え](tm-pricing-mode.md)」を参照してください。 次の手順では、クエリを作成、実行、保存、および編集する方法を示します。 **クエリエディタを開く** **ナレッジグラフクエリエディタに移動するには** 1. [AWS IoT TwinMaker コンソール](https://console.aws.amazon.com/iottwinmaker/) を開きます。 1. ナレッジグラフを使用したいワークスペースを開きます。 1. 左のナビゲーションメニューの **[クエリエディタ]** を選択します。 1. クエリエディタが開きます。ワークスペースのリソースに対してクエリを実行できるようになりました。 **クエリを実行する** **クエリを実行してグラフを生成するには** 1. クエリエディタで、**[エディタ]** タブを選択して構文エディタを開きます。 1. エディタスペースに、ワークスペースのリソースに対して実行するクエリを書き込みます。 ![\[クエリが入力されたエディタスペース。\]](http://docs.aws.amazon.com/ja_jp/iot-twinmaker/latest/guide/images/kg-query-updated.png) 次の例では、リクエストは名前`vav_%`に を含むエンティティを検索し、次のコードを使用して、それらのエンティティ間の`feed`関係によってこれらのエンティティを整理します。 ``` SELECT ahu, vav, r FROM EntityGraph MATCH (vav)<-[r:feed]-(ahu) WHERE vav.entityName LIKE 'vav_%' ``` **注記** ナレッジグラフ構文は [PartiQL](https://partiql.org/) を使用します。この構文の詳細については、「」を参照してください[AWS IoT TwinMaker ナレッジグラフの追加リソース](tm-knowledge-graph-resources.md)。 1. **クエリの実行**を選択して、作成したリクエストを実行します。 グラフはリクエストに基づいて生成されます。 ![\[前のステップで詳述したクエリの結果を示すグラフ。\]](http://docs.aws.amazon.com/ja_jp/iot-twinmaker/latest/guide/images/tm-kg-graph-output.png) 上記のグラフ例は、ステップ 2 のクエリ例に基づいています。 1. クエリの結果もリストに表示されます。**結果**を選択して、クエリ結果をリストに表示します。 1. 必要に応じて、 **としてエクスポート**を選択してクエリ結果を JSON または CSV 形式でエクスポートします。 コンソールでのナレッジグラフの基本的な使用方法を説明します。ナレッジグラフ構文の詳細と例については、「[AWS IoT TwinMaker ナレッジグラフの追加リソース](tm-knowledge-graph-resources.md)」を参照してください。 # ナレッジグラフシーンの統合 シーングラフの生成 AWS IoT アプリキットコンポーネントを使用して、ナレッジグラフを AWS IoT TwinMaker シーンに統合するウェブアプリケーションを構築できます。これにより、シーン内に存在する 3D ノード (機器またはシステムを表す 3D モデル) に基づいてグラフを生成できます。シーンから 3D ノードをグラフ化するアプリケーションを作成するには、まず 3D ノードをワークスペース内のエンティティにバインドします。このマッピングでは、 はシーンに存在する 3D モデルとワークスペース内のエンティティとの関係を AWS IoT TwinMaker グラフ化します。その後、ウェブアプリケーションを作成し、シーンで 3D モデルを選択し、グラフ形式で他のエンティティとの関係を調べることができます。 ![\[3D モデル間の関係を示すナレッジグラフを含む TwinMaker シーン。\]](http://docs.aws.amazon.com/ja_jp/iot-twinmaker/latest/guide/images/intro_kg_scene.png) AWS IoT アプリケーションキットコンポーネントを使用して AWS IoT TwinMaker シーンでグラフを生成する動作中のウェブアプリケーションの例については、github [AWS IoT TwinMaker のサンプル反応アプリケーション](https://github.com/awslabs/iot-app-kit/blob/3DKG_Demo/examples/react-app/src/components/index.tsx)を参照してください。 ## AWS IoT TwinMaker シーングラフの前提条件 シーンで AWS IoT TwinMaker ナレッジグラフを使用するウェブアプリを作成する前に、次の前提条件を完了してください。 + AWS IoT TwinMaker ワークスペースを作成します。ワークスペースは、[AWS IoT TwinMaker コンソール](https://console.aws.amazon.com/iottwinmaker/)で作成できます。 + AWS IoT TwinMakerのエンティティコンポーネントシステムおよびエンティティの作成方法を理解します。詳細については、「[最初のエンティティを作成する](twinmaker-gs-entity.md)」を参照してください。 + 3D モデルが入力された AWS IoT TwinMaker シーンを作成します。 + AWS IoT TwinMakerの AWS IoT アプリキットコンポーネントに精通してください。 AWS IoT TwinMaker コンポーネントの詳細については、「」を参照してください[AWS IoT TwinMaker UI コンポーネントを使用してカスタマイズされたウェブアプリケーションを作成する](tm-app-kit.md)。 + ナレッジグラフの概念と主要な用語に精通します。「[AWS IoT TwinMaker ナレッジグラフの主な概念](tm-knowledge-graph.md#tm-knowledge-graph-concepts)」を参照してください。 **注記** AWS IoT TwinMaker ナレッジグラフと関連する機能を使用するには、**標準**または**階層バンドル**の料金モードのいずれかである必要があります。 AWS IoT TwinMaker 料金の詳細については、「」を参照してください[AWS IoT TwinMaker 価格設定モードの切り替え](tm-pricing-mode.md)。 ## シーンで 3D ノードをバインドする ナレッジグラフをシーンと統合するウェブアプリを作成する前に、シーンに存在する 3D ノードと呼ばれる 3D モデルを関連するワークスペースエンティティにバインドします。たとえば、シーンにミキサー機器のモデルがあり、 という対応するエンティティがある場合は`mixer_0`、ミキサーのモデルとミキサーを表すエンティティの間に**データバイン**ディングを作成し、モデルとエンティティをグラフ化できるようにします。 **データバインディングアクションを実行するには** 1. [AWS IoT TwinMaker コンソール](https://console.aws.amazon.com/iottwinmaker/)にログインします。 1. ワークスペースを開き、バインドしたい 3D ノードを含むシーンを選択します。 1. シーンコンポーザーでノード (3D モデル) を選択します。ノードを選択すると、画面の右側にインスペクターパネルが開きます。 1. インスペクターパネルで、パネルの上部に移動し、**\$1** ボタンを選択します。次に、**エンティティバインディングの追加**オプションを選択します。これによりドロップダウンが開き、現在選択されているノードにバインドするエンティティを選択できます。 ![\[Inspector パネルでプラス記号が選択され、エンティティバインディングを追加が強調表示されたシーン。\]](http://docs.aws.amazon.com/ja_jp/iot-twinmaker/latest/guide/images/binding-step-4.png) 1. データバインディングドロップダウンメニューから、3D モデルにマッピングするエンティティ ID を選択します。**コンポーネント名**フィールドと**プロパティ名**フィールドで、バインドするコンポーネントとプロパティを選択します。 ![\[Inspector パネルでコンポーネント名とプロパティ名が選択されたシーン。\]](http://docs.aws.amazon.com/ja_jp/iot-twinmaker/latest/guide/images/binding-step-6.png) **[エンティティ ID]**、**[コンポーネント名]**、**[プロパティ名]** の各フィールドを選択したら、バインドは完了です。 1. グラフ化したいすべてのモデルとエンティティに対してこのプロセスを繰り返します。 **注記** シーンタグでも同じデータバインディング操作を実行できます。エンティティの代わりにタグを選択し、同じ手順でタグをノードにバインドします。 ## ウェブアプリケーションを作成 エンティティをバインドしたら、 AWS IoT アプリキットライブラリを使用して、シーンを表示し、シーンノードとエンティティ間の関係を調べることができるナレッジグラフウィジェットを持つウェブアプリを構築します。 以下のリソースを使用して独自のアプリを作成します。 + AWS IoT TwinMaker サンプル react app github [ Readme](https://github.com/awslabs/iot-app-kit/blob/3DKG_Demo/examples/react-app/README.md) ドキュメント。 + github のサンプル AWS IoT TwinMaker 反応アプリケーション[ソース](https://github.com/awslabs/iot-app-kit/blob/3DKG_Demo/examples/react-app/src/components/index.tsx)。 + AWS IoT アプリキット[入門](https://awslabs.github.io/iot-app-kit/?path=/docs/overview-getting-started--docs)ドキュメント。 + AWS IoT アプリキット [ Video Player コンポーネントの](https://awslabs.github.io/iot-app-kit/?path=/docs/components-videoplayer--docs)ドキュメント。 + AWS IoT アプリケーションキット [Scene Viewer コンポーネントの](https://awslabs.github.io/iot-app-kit/?path=/docs/components-sceneviewer--docs)ドキュメント。 次の手順は、ウェブアプリのシーンビューワーコンポーネントの機能を示しています。 **注記** この手順は、 AWS IoT TwinMaker サンプル反応 AWS IoT アプリでのアプリキットシーンビューワーコンポーネントの実装に基づいています。 1. AWS IoT TwinMaker サンプル反応アプリケーションのシーンビューワーコンポーネントを開きます。検索フィールドにエンティティ名または部分的なエンティティ名 (大文字と小文字を区別する検索) を入力し、**検索**ボタンを選択します。モデルがエンティティ ID にバインドされている場合、シーン内のモデルが強調表示され、エンティティのノードがシーンビューワーパネルに表示されます。 ![\[ナレッジグラフのシーンビューワーパネルが表示されたシーン。\]](http://docs.aws.amazon.com/ja_jp/iot-twinmaker/latest/guide/images/search_select_kg_event.png) 1. すべての関係のグラフを生成するには、シーンビューワーウィジェットでノードを選択し、**Explore** ボタンを選択します。 ![\[関係のグラフを表示するナレッジグラフシーンビューワーパネルを持つシーン。\]](http://docs.aws.amazon.com/ja_jp/iot-twinmaker/latest/guide/images/explore_select_kg.png) 1. **クリア**ボタンを押して現在のグラフ選択をクリアし、最初からやり直します。 # Grafana で AWS IoT TwinMaker ナレッジグラフを使用する方法 ナレッジグラフ Grafana パネル このセクションでは、クエリエディタパネルを AWS IoT TwinMaker Grafana ダッシュボードに追加してクエリを実行および表示する方法について説明します。 ## AWS IoT TwinMaker クエリエディタの前提条件 AWS IoT TwinMaker クエリエディタの前提条件 Grafana で AWS IoT TwinMaker ナレッジグラフを使用する前に、次の前提条件を完了してください。 + AWS IoT TwinMaker ワークスペースを作成します。ワークスペースは、[AWS IoT TwinMaker コンソール](https://console.aws.amazon.com/iottwinmaker/)で作成できます。 + Grafana で使用する AWS IoT TwinMaker ように を設定します。手順については、「[AWS IoT TwinMaker Grafana ダッシュボードの統合](grafana-integration.md)」を参照してください。 **注記** AWS IoT TwinMaker ナレッジグラフを使用するには、**標準**または**階層バンドル**の料金モードのいずれかである必要があります。詳細については、「[AWS IoT TwinMaker 価格設定モードの切り替え](tm-pricing-mode.md)」を参照してください。 ## AWS IoT TwinMaker クエリエディタのアクセス許可 ナレッジグラフ Grafana アクセス許可 Grafana で AWS IoT TwinMaker クエリエディタを使用するには、アクション のアクセス許可を持つ IAM ロールが必要です`iottwinmaker:ExecuteQuery`。この例に示すように、ワークスペースダッシュボードロールにそのアクセス許可を追加します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket", "arn:aws:s3:::amzn-s3-demo-bucket/*" ] }, { "Effect": "Allow", "Action": [ "iottwinmaker:GetEntity", "iottwinmaker:ListEntities", "iottwinmaker:ExecuteQuery" ], "Resource": [ "arn:aws:iottwinmaker:us-east-2:111122223333:workspace/workspaceId", "arn:aws:iottwinmaker:us-east-2:111122223333:workspace/workspaceId/*" ] }, { "Effect": "Allow", "Action": "iottwinmaker:ListWorkspaces", "Resource": "*" } ] } ``` ------ **注記** AWS IoT TwinMaker Grafana データソースを設定するときは、ロールの**引き受け ARN フィールドにこのアクセス許可を持つロール**を使用してください。追加したら、**[ワークスペース]** の横にあるドロップダウンからワークスペースを選択できます。 詳細については、「[ダッシュボード IAM ロールの作成](dashboard-IAM-role.md#dashboard-IAM-role.title)」を参照してください。 ### AWS IoT TwinMaker クエリエディタパネルを設定する ナレッジグラフ Grafana パネル **ナレッジグラフ用に新しい Grafana ダッシュボードパネルを設定するには** 1. AWS IoT TwinMaker Grafana ダッシュボードを開きます。 1. 新しい **[ダッシュボードパネル]** を作成します。パネルの作成方法の詳細については、Grafana ドキュメントの[「ダッシュボードの作成](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/create-dashboard/)」を参照してください。 1. 視覚化のリストから、**AWS IoT TwinMaker クエリエディタ**を選択します。 ![\[AWS IoT TwinMaker ダッシュボードのドロップダウンリストには、 AWS IoT TwinMaker クエリエディタのオプションが含まれています。\]](http://docs.aws.amazon.com/ja_jp/iot-twinmaker/latest/guide/images/tw-query-editor-dropdown.png) 1. クエリを実行するデータソースを選択します。 1. **(オプション)** 表示されたフィールドに新しいパネルの名前を追加します。 1. **適用** を選択して、新しいパネルを保存して確認します。 ナレッジグラフパネルは、 AWS IoT TwinMaker コンソールで提供されるクエリエディタと同様に機能します。パネルで作成したクエリを実行、記述、クリアできます。クエリの書き込み方法の詳細については、「」を参照してください[AWS IoT TwinMaker ナレッジグラフの追加リソース](tm-knowledge-graph-resources.md)。 #### AWS IoT TwinMaker クエリエディタの使用方法 クエリエディタを使用する クエリの結果は、次の画像のとおり、グラフで視覚化、表で一覧表示、および実行サマリーとして表示、の 3 つの方法で表示されます。 + **グラフの視覚化** ![\[AWS IoT TwinMaker ビジュアルグラフとして表示されるクエリエディタの結果。\]](http://docs.aws.amazon.com/ja_jp/iot-twinmaker/latest/guide/images/kg-vis-graph.png) ビジュアルグラフには、結果に少なくとも 1 つのリレーションを含むクエリのデータのみが表示されます。グラフには、エンティティがノードとして表示され、関係が有向エッジとしてグラフに表示されます。 + **表形式データ:** ![\[AWS IoT TwinMaker クエリエディタの結果が表形式データとして表示されます。\]](http://docs.aws.amazon.com/ja_jp/iot-twinmaker/latest/guide/images/kg-table-data.png) 表形式のデータには、すべてのクエリのデータ表示されます。テーブルで特定の結果または結果のサブセットを検索できます。データは JSON 形式または CSV 形式でエクスポートできます。 + **実行サマリー** ![\[AWS IoT TwinMaker クエリエディタの結果が実行概要として表示されます。\]](http://docs.aws.amazon.com/ja_jp/iot-twinmaker/latest/guide/images/kg-run-sum.png) 実行サマリーには、クエリとクエリのステータスに関するメタデータが表示されます。 # AWS IoT TwinMaker ナレッジグラフの追加リソース ナレッジグラフのその他のリソース このセクションでは、ナレッジグラフにクエリを書き込むために使用される PartiQL 構文の基本的な例と、ナレッジグラフのデータモデルに関する情報を提供する PartiQL ドキュメントへのリンクを示します。 + [PartiQL グラフデータモデルに関するドキュメント](https://partiql.org/gpml/graph_model.html) + [PartiQL グラフクエリに関するドキュメント](https://partiql.org/gpml/graph_query.html) この一連の例は、レスポンスを含む基本的なクエリを示しています。これをリファレンスとして使用して、独自のクエリを記述します。 **基本的なクエリ** + **フィルターを使用してすべてのエンティティを取得** ``` SELECT entity FROM EntityGraph MATCH (entity) WHERE entity.entityName = 'room_0' ``` このクエリは、ワークスペース内のすべてのエンティティを という名前で返します`room_0`。 `FROM` 句: `EntityGraph` は、ワークスペース内のすべてのエンティティとその関係を含むグラフコレクションです。このコレクションは、ワークスペース内のエンティティ AWS IoT TwinMaker に基づいて によって自動的に作成および管理されます。 `MATCH` 句: グラフの一部と一致するパターンを指定します。この場合、パターン `(entity)` はグラフ内のすべてのノードと一致し、エンティティ変数にバインドされます。`FROM` 句の後には `MATCH` 句が続く必要があります。 `WHERE` 句: ノードの `entityName`フィールドでフィルターを指定します。値は と一致する必要があります`room_0`。 `SELECT` 句: エンティティノード全体が返されるように `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` です。これはノード全体が返されたことを示しています。型の他の値は、関係を示す`EDGE`か、整数や文字列などのスカラー値`VALUE`を示すことができます。 `rows` は行のリストを返します。一致したエンティティは 1 つだけなので、エンティティのすべてのフィールドを含む 1 つの `rowData` が返されます。 **注記** スカラー値しか返せない SQL とは異なり、PartiQL を使用してオブジェクトを (JSON として) 返すことができます。 各ノードには、`entityId`、、 `arn` などのエンティティレベルのフィールド`components`、、 `componentName`などのコンポーネントレベルのフィールド、`componentTypeId``properties`および `propertyName`や などのプロパティレベルのフィールド`propertyValue`がすべてネストされた JSON として含まれます。 + **すべてのリレーションシップをフィルターで取得**: ``` 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`。これは、エンティティで定義されているリレーションシッププロパティ名と同じです。、`sourceComponentName`、および は`sourceEntityId`、リレーションシッププロパティが定義されたエンティティとコンポーネントに関する情報`sourceComponentTypeId`を提供します。は、この関係が指すエンティティ`targetEntityId`を指定します。 + **特定のエンティティと特定の関係を持つすべてのエンティティを取得する** ``` SELECT e2.entityName FROM EntityGraph MATCH (e1)-[r]->(e2) WHERE relationship.relationshipName = 'isLocationOf' AND e1.entityName = 'room_0' ``` このクエリは、エンティティと`isLocationOf`関係があるすべてのエンティティのすべての`room_0`エンティティ名を返します。 `MATCH` 句: 有向エッジ (`e2`) を持つ任意の 2 つのノード (`e1`、) に一致するパターンを指定します`r`。 `WHERE` 句: リレーションシップ名とソースエンティティ名のフィルターを指定します。 `SELECT` 句: `e2`ノードの `entityName`フィールドを返します。 **レスポンス** ``` { "columnDescriptions": [ { "name": "entityName", "type": "VALUE" } ], "rows": [ { "rowData": [ "floor_0" ] } ] } ``` columnDescriptions では、列のタイプは `VALUE` であるため、 は文字列`entityName`です。 1 つのエンティティ `floor_0`が返されます。 **MATCH** `MATCH` 句では、次のパターンがサポートされています。 + ノード 'a' を指す一致ノード 'b': ``` FROM EntityGraph MATCH (a)-[rel]-(b) ``` + ノード 'b' を指す一致ノード 'a': ``` FROM EntityGraph MATCH (a)-[]->(b) ``` リレーションシップにフィルターを指定する必要がないと仮定して、リレーションシップに変数がバインドされることはありません。 + ノード「b」を指すノード「a」とノード「a」を指すノード「b」を一致させます。 ``` FROM EntityGraph MATCH (a)-[rel]-(b) ``` これにより 2 つの一致が返されます。1 つは「a」から「b」、もう 1 つは「b」から「a」であるため、可能な限り有向エッジを使用することをお勧めします。 + 関係名はプロパティグラフ のラベルでもあるため`EntityGraph`、 `WHERE``rel.relationshipName`句で にフィルターを指定する代わりに、コロン (:) の後に関係名を簡単に指定できます。 ``` FROM EntityGraph MATCH (a)-[:isLocationOf]-(b) ``` + チェーン: 複数のリレーションシップに一致するようにパターンを連鎖させることができます。 ``` FROM EntityGraph MATCH (a)-[rel1]->(b)-[rel2]-(c) ``` + 変数ホップパターンは、複数のノードやエッジにまたがっていることもあります。 ``` FROM EntityGraph MATCH (a)-[]->{1,5}(b) ``` このクエリは、1～5 ホップ内のノード「a」からの送信エッジを持つ任意のパターンに一致します。指定できる格量指定子は次のとおりです。 `{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`は、変数をネストされていない変数にバインドして、 `WHERE`または `SELECT`句で使用できるようにします。このクエリは、コンポーネントタイプ ID `com.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` + 値に '%' がある場合は、 にエスケープ文字を入力し`LIKE`、 でエスケープ文字を指定します`ESCAPE`。 ``` 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) ``` このクエリは、*b* を介して *a* と *c* を接続する 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`クエリレスポンスは、*b* を介して *a* と *c* の間の各パス/パターンのすべてのノードとエッジを識別するメタデータのみで構成されます。 **制限**と**オフセット**: ``` SELECT e.entityName FROM EntityGraph MATCH (e) WHERE e.entityName LIKE 'room_%' LIMIT 10 OFFSET 5 ``` `LIMIT` はクエリで返される結果の数を指定し、`OFFSET` はスキップする結果の数を指定します。 **LIMIT** と **maxResults**: 次の例は、合計 500 件の結果を返すクエリを示していますが、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 アクション](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ExecuteQuery.html)のオプションパラメータです。 は API と、上記のクエリの範囲内で結果がどのように読み取られるか`max-results`にのみ適用されます。 クエリ`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` 文字列は、結果の次のページを指定します。詳細については、[ExecuteQuery API ](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ExecuteQuery.html#API_ExecuteQuery_RequestSyntax)アクション」を参照してください。 AWS IoT TwinMaker ナレッジグラフクエリには次の制限があります。 **** | 制限の名前 | クォータ | 引き上げ可能 | | --- | --- | --- | | クエリ実行タイムアウト | 10 秒 | いいえ | | ホップの最大数 | 10 | [Yes (はい)] | | セルフ の最大数 `JOIN` | 20 | はい | | 投影フィールドの最大数 | 20 | はい | | 条件式の最大数 (`AND`、`OR`、`NOT`) | 10 | [Yes (はい)] | | `LIKE` 式パターンの最大長 (ワイルドカードとエスケープを含む) | 20 | はい | | IN 句で指定できる項目の最大数 | 10 | [Yes (はい)] | | の最大値 OFFSET | 3000 | はい | | の最大値 `LIMIT` | 3000 | はい | | トラバーサルの最大値 (`OFFSET` \$1 `LIMIT`) | 3000 | はい |