本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 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之間的關係。關係只是在實體元件上定義之特殊資料類型 [ 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 服務使用），該語言有新增的圖形比對語法支援，可協助您撰寫查詢。呼叫完成後，您可以將結果檢視為資料表，或將其視覺化為已連線節點和邊緣的圖形。 **知識圖表關鍵術語**： + **實體圖表**：工作區內的節點和邊緣集合。 + **節點**：工作區中的每個實體都會成為實體圖表中的節點。 + **Edge**：實體元件上定義的每個關係屬性都會成為實體圖表中的邊緣。此外，使用實體的 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. 在查詢編輯器中，選擇**編輯器**索引標籤以開啟語法編輯器。 1. 在編輯器空間中，撰寫您要針對工作區資源執行的查詢。 ![\[輸入查詢的編輯器空間。\]](http://docs.aws.amazon.com/zh_tw/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/zh_tw/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 節點繫結至工作區中的實體。透過此映射，可 AWS IoT TwinMaker 繪製場景中 3D 模型與工作區中實體之間的關係。然後，您可以建立 Web 應用程式、使用場景選取 3D 模型，並以圖形格式探索它們與其他實體的關係。 ![\[TwinMaker 場景具有知識圖表，顯示 3D 模型之間的關係。\]](http://docs.aws.amazon.com/zh_tw/iot-twinmaker/latest/guide/images/intro_kg_scene.png) 如需使用 AWS IoT 應用程式套件元件在 AWS IoT TwinMaker 場景中產生圖形的工作 Web 應用程式範例，請參閱 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 UI 組件創建自定義 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** 按鈕。然後選擇**新增實體繫結**選項。這會開啟下拉式清單，您可以在其中選取要繫結至目前所選節點的實體。 ![\[在檢查器面板中選取加號，並反白新增實體繫結的場景。\]](http://docs.aws.amazon.com/zh_tw/iot-twinmaker/latest/guide/images/binding-step-4.png) 1. 從資料繫結下拉式功能表中，選取要映射至 3D 模型的實體 ID。針對**元件名稱**和**屬性名稱**欄位，選取您要繫結的元件和屬性。 ![\[在檢查器面板中選取元件和屬性名稱的場景。\]](http://docs.aws.amazon.com/zh_tw/iot-twinmaker/latest/guide/images/binding-step-6.png) 一旦您選取**實體 ID**、**元件名稱**和**屬性名稱**欄位，繫結即完成。 1. 針對您要繪製圖形的所有模型和實體重複此程序。 **注意** 您可以在場景標籤上執行相同的資料繫結操作，只要選取標籤而非實體，然後依照相同的程序將標籤繫結至節點即可。 ## 建立 Web 應用程式繫結實體之後，請使用 AWS IoT 應用程式套件程式庫建置具有知識圖表小工具的 Web 應用程式，讓您檢視場景並探索場景節點和實體之間的關係。使用下列資源建立您自己的應用程式： + AWS IoT TwinMaker 範例反應應用程式 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 應用程式套件[影片播放器元件](https://awslabs.github.io/iot-app-kit/?path=/docs/components-videoplayer--docs)文件。 + AWS IoT 應用程式套件[場景檢視器元件](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_tw/iot-twinmaker/latest/guide/images/search_select_kg_event.png) 1. 若要產生所有關係的圖形，請在場景檢視器小工具中選取節點，然後選取**探索**按鈕。 ![\[知識圖表場景檢視器面板的場景會顯示關係圖表。\]](http://docs.aws.amazon.com/zh_tw/iot-twinmaker/latest/guide/images/explore_select_kg.png) 1. 按下**清除**按鈕以清除您目前的圖形選擇並重新開始。 # 如何搭配 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/)中建立工作區。 + 設定 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. 建立新的**儀表板面板**。如需如何建立面板的詳細步驟，請參閱 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/zh_tw/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_tw/iot-twinmaker/latest/guide/images/kg-vis-graph.png) 視覺化圖形只會針對結果中至少具有一個關係的查詢顯示資料。圖形會將實體顯示為節點，並將關係顯示為圖形中的導向邊緣。 + **表格式資料：** ![\[AWS IoT TwinMaker 查詢編輯器結果顯示為表格式資料。\]](http://docs.aws.amazon.com/zh_tw/iot-twinmaker/latest/guide/images/kg-table-data.png) 表格式資料格式會顯示所有查詢的資料。您可以搜尋資料表以取得特定結果或結果子集。資料可以 JSON 或 CSV 格式匯出。 + **執行摘要** ![\[AWS IoT TwinMaker 查詢編輯器結果顯示為執行摘要。\]](http://docs.aws.amazon.com/zh_tw/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`、元件層級欄位，例如 `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` \$1 `LIMIT`) | 3000 | 是 |