翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# AWS IoT TwinMaker ナレッジグラフの追加リソース
<a name="tm-knowledge-graph-resources"></a>

このセクションでは、ナレッジグラフにクエリを書き込むために使用される 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` \+ `LIMIT`) | 3000 | はい |