AWS IoT TwinMaker 知識圖表其他資源 - AWS IoT TwinMaker

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

AWS IoT TwinMaker 知識圖表其他資源

本節提供用於在知識圖表中寫入查詢的 PartiQL 語法基本範例,以及提供知識圖表資料模型資訊之 PartiQL 文件的連結。

這組範例顯示基本查詢及其回應。使用此做為撰寫您自己的查詢的參考。

基本查詢
  • 使用篩選條件取得所有實體

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

    每個節點都包含所有實體層級欄位,例如 entityIdarncomponents、元件層級欄位,例如 componentNamecomponentTypeIdproperties 以及 屬性層級欄位,例如 propertyNamepropertyValue,全部都是巢狀 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 ] }

    中的資料欄類型columnDescriptionsEDGE

    每個 rowData代表具有 等欄位的邊緣relationshipName。這與實體上定義的關係屬性名稱相同。sourceEntityIdsourceComponentNamesourceComponentTypeId提供有關關係屬性在哪個實體和元件上定義的資訊。targetEntityId 指定此關係指向的實體。

  • 取得與特定實體具有特定關係的所有實體

    SELECT e2.entityName FROM EntityGraph MATCH (e1)-[r]->(e2) WHERE relationship.relationshipName = 'isLocationOf' AND e1.entityName = 'room_0'

    此查詢會傳回與實體有isLocationOf關係之所有實體的所有room_0實體名稱。

    MATCH 子句:指定符合任何兩個具有導向邊緣的節點 (e1e2) 的模式 (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 用於將變數繫結至未巢狀變數,以便在 WHERESELECT子句中使用。此查詢會傳回包含名為 且元件類型 ID 為 之元件meetingroomFunction值為 的所有實體 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
  • 支援的邏輯運算子為 ANDNOTOR

  • 支援的比較運算子為 <<==>=>!=

  • 如果您想要在相同欄位中指定多個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 之間每個路徑/模式的所有節點和邊緣的中繼資料。

LIMITOFFSET
SELECT e.entityName FROM EntityGraph MATCH (e) WHERE e.entityName LIKE 'room_%' LIMIT 10 OFFSET 5

LIMIT 指定要在查詢中傳回的結果數目,並OFFSET指定要略過的結果數目。

LIMITmaxResults

下列範例顯示的查詢總共傳回 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-resultsExecuteQuery API 動作的選用參數。 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 API 動作。

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

限制名稱 配額 可調整

查詢執行逾時

10 秒

躍點數量上限

10

自我數量上限 JOIN

20

預計欄位數量上限

20

條件式表達式數目上限 (ANDORNOT)

10

LIKE 表達式模式的長度上限 (包括萬用字元和逸出)

20
可在 IN子句中指定的項目數量上限 10
的最大值 OFFSET 3000

的最大值 LIMIT

3000

周遊的最大值 (OFFSET + LIMIT)

3000