本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# Amazon 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`是包含工作空间中所有实体及其关系的图表集合。此集合是 Amazon 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`、组件级字段（例如和）以及属性级字段（`properties`例如`componentTypeId`和）`componentName`，全部作为嵌套 JSO `propertyName` N `propertyValue`。
+ **使用筛选器获取所有关系**：

  ```
  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`子句：指定一种模式，该模式与具有定向边 (`e2`) 的任意两个节点 (`e1`,`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)
  ```

  此查询匹配任何具有从节点 '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`用于将变量绑定到未嵌套的变量，以便它们可以在 o `WHERE` r `SELECT` 子句中使用。此查询返回在组件类型为 ID `com.example.query.construction.room` 的组件中包含名为 `roomFunction`、值为 `meeting` 的属性的所有实体   
要访问一个字段的多个嵌套字段，例如实体中的多个组件，请使用逗号表示法进行连接。  

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

**路径**  
使用路径投影进行查询时支持以下模式投影：  
+ 可变跳查询

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

  此查询以 1 跳模式匹配并投影通过 *b* 连接 *a* 和 *c* 的节点的元数据。

  ```
  {
      "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 path/pattern * 之间每个节点和边的所有节点和边。

**限制**和**抵消**：  

```
SELECT e.entityName
FROM EntityGraph MATCH (e)
WHERE e.entityName LIKE 'room_%'
LIMIT 10
OFFSET 5
```
`LIMIT` 指定要在查询中返回的结果数，`OFFSET` 指定要跳过的结果数。

**限制**和**最大结果**：  
以下示例显示了一个查询，该查询总共返回 500 个结果，但每次 API 调用一次仅显示 50 个结果。此模式可用于需要限制显示结果数量的地方，例如，当用户界面中只能显示 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.amazonaws.cn//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.amazonaws.cn//iot-twinmaker/latest/apireference/API_ExecuteQuery.html#API_ExecuteQuery_RequestSyntax)API 操作。

Amazon IoT TwinMaker 知识图谱查询有以下限制：


****  

| 限制名称 | 配额 | 可调整 | 
| --- | --- | --- | 
| 查询执行超时值 | 10 秒 | 否 | 
| 最大跃点数 | 10 | 是 | 
| 自我`JOIN`的最大数量 | 20 | 是 | 
| 投影字段最大数量 | 20 | 是 | 
| 条件表达式的最大数量 (`AND`,`OR`,`NOT`) | 10 | 是 | 
| `LIKE`表达式模式的最大长度（包括通配符和转义符） | 20 | 是 | 
| 一个IN子句中可以指定的最大项目数 | 10 | 是 | 
| 的最大值 OFFSET | 3000 | 是 | 
| 的最大值 `LIMIT` | 3000 | 是 | 
| 遍历的最大值 (\+) `OFFSET` `LIMIT` | 3000 | 是 |