本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 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)或之间的关系[ UpdateEntity](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_UpdateEntity.html) APIs。关系只是在实体组件上定义的特殊数据类型[关系](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，根据实体中的任何数据或实体之间的关系进行查询。Knowledge graph 使用灵活的 PartiQL 查询语言（许多 AWS 服务都使用），该语言具有新增的图表匹配语法支持，可帮助您编写查询。调用完成后，您可以以表格形式查看结果，也可以将其可视化为连接的节点和边的图表。 **知识图谱关键术语**： + **实体图谱**：工作区内节点和边缘的集合。 + **节点**：工作区中的每个实体都将成为实体图谱中的一个节点。 + **边缘**：在实体组件上定义的每个关系属性都将成为实体图谱中的一个边缘。此外，使用实体 parentEntityId 字段定义的分层父子关系也将成为实体图中具有 “isChildOf” 关系名称的边缘。所有边缘都是定向边缘。 + **关系**： AWS IoT TwinMaker 关系是实体组件的一种特殊类型的属性。您可以使用 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 控制台](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. 在查询编辑器中，选择**Editor**（编辑器）选项卡以打开语法编辑器。 1. 在编辑器空间中，编写要对工作区资源运行的查询。 ![\[已输入查询的编辑器空间。\]](http://docs.aws.amazon.com/zh_cn/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_%' ``` **注意** 知识图谱语法使用 P [artiQL。](https://partiql.org/)有关此语法的信息，请参见[AWS IoT TwinMaker 知识图谱其他资源](tm-knowledge-graph-resources.md)。 1. 选择 “**运行查询**” 以运行您创建的请求。图表将根据您的请求生成。 ![\[显示上述步骤中详述的查询结果的图表。\]](http://docs.aws.amazon.com/zh_cn/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 应用套件组件来构建 Web 应用程序，将知识图谱集成到您的 AWS IoT TwinMaker 场景中。这允许您根据场景中存在的 3D 节点（代表您的设备或系统的 3D 模型）生成图表。要创建用于绘制场景中 3D 节点的应用程序，请先将 3D 节点绑定到工作空间中的实体。通过此映射，可以绘制场景中存在的 3D 模型与工作空间中实体之间的关系 AWS IoT TwinMaker 图。然后，您可以创建 Web 应用程序，在场景中选择 3D 模型，并以图表格式探索它们与其他实体的关系。 ![\[带有知识图的 TwinMaker 场景，显示了三维模型之间的关系。\]](http://docs.aws.amazon.com/zh_cn/iot-twinmaker/latest/guide/images/intro_kg_scene.png) 有关利用应用套件组件在 AWS IoT TwinMaker 场景中生成图表的运行 Web AWS IoT 应用程序的示例，请参阅 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 知识图谱的 Web 应用程序之前，请完成以下先决条件： + 创建 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 用户界面组件创建自定义 Web 应用程序](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 节点在创建将知识图谱与场景集成的 Web 应用程序之前，请将场景中存在的 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/zh_cn/iot-twinmaker/latest/guide/images/binding-step-4.png) 1. 从数据绑定下拉菜单中，选择要映射到 3D 模型的实体 ID。在 “**组件名称**” 和 “**属性名称**” 字段中，选择要绑定的组件和属性。 ![\[在 Inspector 面板中选择了组件和属性名称的场景。\]](http://docs.aws.amazon.com/zh_cn/iot-twinmaker/latest/guide/images/binding-step-6.png) 选择**实体 ID**、**组件名称**和**属性名称**字段后，绑定就完成了。 1. 对要绘制图表的所有模型和实体重复此过程。 **注意** 可以对场景标签执行相同的数据绑定操作，只需选择标签而不是实体，然后按照相同的过程将标签绑定到节点。 ## 创建 Web 应用程序绑定实体后，使用 AWS IoT 应用程序套件库构建一个带有知识图谱控件的 Web 应用程序，该控件允许您查看场景并探索场景节点和实体之间的关系。使用以下资源创建自己的应用程序： + AWS IoT TwinMaker 示例反应应用程序 github [自述](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 应用程序套件[视频播放器组件](https://awslabs.github.io/iot-app-kit/?path=/docs/components-videoplayer--docs)文档。 + AWS IoT 应用程序套件 Sc [ene Viewer 组件](https://awslabs.github.io/iot-app-kit/?path=/docs/components-sceneviewer--docs)文档。以下过程演示了 Web 应用程序中场景查看器组件的功能。 **注意** 此过程基于 AWS IoT TwinMaker 示例反应 AWS IoT 应用程序中应用套件场景查看器组件的实现。 1. 打开 AWS IoT TwinMaker 示例反应应用程序的场景查看器组件。在搜索字段中键入实体名称或部分实体名称（区分大小写的搜索），然后选择**搜索**按钮。如果模型绑定到实体 ID，则场景中的模型将被突出显示，并且该实体的节点将显示在场景查看器面板中。 ![\[显示知识图谱场景查看器面板的场景。\]](http://docs.aws.amazon.com/zh_cn/iot-twinmaker/latest/guide/images/search_select_kg_event.png) 1. 要生成所有关系的图表，请在场景查看器控件中选择一个节点，然后选择 “**浏览**” 按钮。 ![\[带有知识图谱场景查看器面板的场景，显示关系图。\]](http://docs.aws.amazon.com/zh_cn/iot-twinmaker/latest/guide/images/explore_select_kg.png) 1. 按下**清除**按钮可清除当前的图表选择并重新开始。 # 如何在 Grafana 中使用 AWS IoT TwinMaker 知识图谱本节介绍如何在 AWS IoT TwinMaker Grafana 控制面板中添加查询编辑器面板以运行和显示查询。 ## AWS IoT TwinMaker 查询编辑器先决条件在 Grafana 中使用 AWS IoT TwinMaker 知识图谱之前，请完成以下先决条件： + 创建 AWS IoT TwinMaker 工作空间。您可以在 [AWS IoT TwinMaker 控制台](https://console.aws.amazon.com/iottwinmaker/)中创建工作区。 + 配置 AWS IoT TwinMaker 为与 Grafana 配合使用。有关说明，请参阅[AWS IoT TwinMaker Grafana 控制面板集成](grafana-integration.md)。 **注意** 要使用 AWS IoT TwinMaker 知识图表，您需要处于**标准**或**分层捆绑**定价模式。有关更多信息，请参阅 [切换 AWS IoT TwinMaker 定价模式](tm-pricing-mode.md)。 ## AWS IoT TwinMaker 查询编辑器权限要在 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 仪表板面板** 1. 打开你的 AWS IoT TwinMaker Grafana 控制面板。 1. 新建一个**控制面板**。有关如何创建面板的详细步骤，请参阅 Grafan [a 文档中的创建控制面板](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/zh_cn/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 查询编辑器查询结果以三种方式显示，如下图所示：在图表中可视化、在表格中列出或以运行摘要的形式呈现。 + **图表可视化：** ![\[AWS IoT TwinMaker 查询编辑器结果显示为可视化图表。\]](http://docs.aws.amazon.com/zh_cn/iot-twinmaker/latest/guide/images/kg-vis-graph.png) 可视化图表仅显示结果中至少有一个关系的查询的数据。该图表将实体显示为节点，将关系显示为图形中的定向边。 + **表格数据：** ![\[AWS IoT TwinMaker 查询编辑器结果显示为表格数据。\]](http://docs.aws.amazon.com/zh_cn/iot-twinmaker/latest/guide/images/kg-table-data.png) 表格数据格式显示所有查询的数据。可以在表格中搜索特定的结果或结果的子集。数据可以以 JSON 或 CSV 格式导出。 + **运行摘要** ![\[AWS IoT TwinMaker 查询编辑器结果显示为运行摘要。\]](http://docs.aws.amazon.com/zh_cn/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` 返回行列表。由于只有一个实体匹配，因此会返回一个包含实体中所有字段的 `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.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 | 是 | | 遍历的最大值 (\$1) `OFFSET` `LIMIT` | 3000 | 是 |