本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 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` 會傳回資料列清單。由於只有一個實體相符，`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` 子句：指定符合兩個節點 （由 表示`()`) 的模式，這些節點由導向邊緣 （由 表示`-[]->`) 連接，並繫結至名為 的變數`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` 子句：指定符合任何兩個具有導向邊緣的節點 (`e1`、`e2`) 的模式 (`r`)。

  `WHERE` 子句：指定關係名稱和來源實體名稱的篩選條件。

  `SELECT` 子句：傳回`e2`節點中的 `entityName` 欄位。

  **回應**

  ```
  {
    "columnDescriptions": [
      {
         "name": "entityName",
         "type": "VALUE"
      }
    ],
     "rows": [
      {
         "rowData": [
           "floor_0"
        ]
      }
    ]
  }
  ```

  在 columnDescriptions 中，資料欄的類型為 ，`VALUE`因為 `entityName` 是字串。

  `floor_0`傳回一個實體 。

**配對**  
子`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)
  ```

  這將傳回兩個相符項目：一個從 'a' 到 'b'，另一個從 '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 或多個重複。

**從**：  
實體節點可以包含巢狀資料，例如元件本身包含其他巢狀資料，例如屬性。您可以透過解除 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 為 之元件`meeting`中`roomFunction`值為 之屬性的所有實體 `com.example.query.construction.room`   
若要存取欄位的多個巢狀欄位，例如實體中的多個元件，請使用逗號標記法進行聯結。  

```
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`。在這裡，`roomfunction`傳回的不是回應中的`propertyValue`資料欄名稱。
+ 傳回別名：

  ```
  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)`。

**PATH**  
使用路徑投影查詢時支援下列模式投影：  
+ 變數躍點查詢

  ```
  SELECT p FROM EntityGraph MATCH p = (a)-[]->{1, 3}(b)
  ```

  此查詢會比對任何模式的節點中繼資料，並在 1 到 3 個躍點**內從節點傳出邊緣。
+ 已修正跳轉查詢

  ```
  SELECT p FROM EntityGraph MATCH p = (a)-[]->(b)<-[]-(c)
  ```

  此查詢符合並將實體的中繼資料和傳入邊緣投影至 *b*。
+ 無方向查詢

  ```
  SELECT p FROM EntityGraph MATCH p = (a)-[]-(b)-[]-(c)
  ```

  此查詢會以透過 *b* 連接 **和 *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* 識別 **和 *c* 之間每個路徑/模式的所有節點和邊緣的中繼資料。

**LIMIT** 和 **OFFSET**：  

```
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)的選用參數。 `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` 字串會指定結果的下一頁。如需詳細資訊，請參閱 [ ExecuteQuery](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ExecuteQuery.html#API_ExecuteQuery_RequestSyntax) API 動作。

AWS IoT TwinMaker 知識圖表查詢具有下列限制：


****  

| 限制名稱 | 配額 | 可調整 | 
| --- | --- | --- | 
| 查詢執行逾時 | 10 秒 | 否 | 
| 躍點數量上限 | 10 | 是 | 
| 自我數量上限 `JOIN` | 20 | 是 | 
| 預計欄位數量上限 | 20 | 是 | 
| 條件式表達式數目上限 (`AND`、`OR`、`NOT`) | 10 | 是 | 
| `LIKE` 表達式模式的長度上限 （包括萬用字元和逸出） | 20 | 是 | 
| 可在 IN子句中指定的項目數量上限 | 10 | 是 | 
| 的最大值 OFFSET | 3000 | 是 | 
| 的最大值 `LIMIT` | 3000 | 是 | 
| 周遊的最大值 (`OFFSET` \+ `LIMIT`) | 3000 | 是 |