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

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

AWS IoT TwinMaker 知識圖表其他資源

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

這組示例顯示了基本查詢及其響應。使用此作為編寫自己的查詢的參考。

基本查詢
  • 使用過濾器獲取所有實體

    SELECT entity FROM EntityGraph MATCH (entity) WHERE entity.entityName = 'room_0'

    此查詢會傳回名稱為工作區中的所有實體room_0

    FROMclause: EntityGraph 是包含工作區中所有實體及其關係的圖形集合。系統會 AWS IoT TwinMaker 根據工作區中的實體自動建立和管理此集合。

    MATCH子句:指定與圖形的一部分匹配的模式。在這種情況下,模式(entity)匹配圖中的每個節點,並綁定到實體變量。該FROM條款之後必須接有MATCH條款。

    WHEREclause:在節點的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、元件層級欄位 (例如和)componentName,以及屬性層級欄位 (例propertiescomponentTypeId和) 全部以巢狀 JSON 形式顯示。propertyName 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。這與實體上定義的關聯屬性名稱相同。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" ] } ] }

    在列說明中,列的類型entityNameVALUE一個字符串。

    傳回一個實體floor_0,。

比賽

MATCH子句支援下列模式:

  • 匹配節點 'b' 指向節點 'a':

    FROM EntityGraph MATCH (a)-[rel]-(b)
  • 匹配節點 'a' 指向節點 'b':

    FROM EntityGraph MATCH (a)-[]->(b)

    假設不需要在關係上指定過濾器,則沒有綁定到關係的變量。

  • 匹配節點 'a' 指向節點 'b' 和節點 'b' 指向節點 'a':

    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的 value 命名屬性的所有實體 com.example.query.construction.room

若要存取欄位的多個巢狀欄位 (例如實體中的多個元件),請使用逗號標記法執行聯結。

SELECT e FROM EntityGraph MATCH (e), e.components AS c1, e.components AS c2
選擇
  • 返回一個節點:

    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用別名來格式化輸出欄位的名稱。在這裡,而不是propertyValue作為響應中的列名roomfunction,返回。

  • 返回別名:

    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%'

    強烈建議使用別名是明確的,提高可讀性,並避免查詢中的任何歧義。

哪裡
  • 支援的邏輯運算子為ANDNOT、和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'
喜歡

如果您不知道某個字段的確切值,並且可以在指定的字段上執行全文本搜索,則非常有用。 %代表零個或更多。

WHERE e.entityName LIKE '%room%'
  • 中綴搜索:%room%

  • 前綴搜索:room%

  • 後綴搜索:%room

  • 如果您的值中有 '%',請在中輸入逸出字元,LIKE並使用指定逸出字元ESCAPE

WHERE e.entityName LIKE 'room\%' ESCAPE '\'
不同的
SELECT DISTINCT c.componentTypeId FROM EntityGraph MATCH (e), e.components AS c
  • DISTINCT關鍵字會從最終結果中消除重複項目。

    DISTINCT複雜資料類型不支援。

伯爵
SELECT COUNT(e), COUNT(c.componentTypeId) FROM EntityGraph MATCH (e), e.components AS c
  • COUNT鍵字會計算查詢結果中的項目數。

  • COUNT巢狀複雜欄位和圖形模式欄位不支援。

  • COUNTDISTINCT和巢狀查詢不支援彙總。

    例如,不支援 COUNT(DISTINCT e.entityId)

路徑

使用路徑投影進行查詢時支援下列陣列投影:

  • 變數躍點查詢

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

    這個查詢匹配和投射任何模式的節點元數據與傳出邊緣從節點 a 內 1 到 3 跳。

  • 固定跳查詢

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

    這個查詢匹配和項目實體的元數據和傳入邊緣到 b

  • 非定向查詢

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

    此查詢會比對並投影節點的中繼資料,並以 1 個躍點模式透過 b 連接 ac

    { "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 標識 ac 之間的每個路徑/模式的所有節點和邊緣。

限制偏移
SELECT e.entityName FROM EntityGraph MATCH (e) WHERE e.entityName LIKE 'room_%' LIMIT 10 OFFSET 5

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

限制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-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串會指定結果的下一頁。如需詳細資訊,請參閱 ExecuteQueryAPI 動作。

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

限制名稱 配額 可調整

查詢執行逾時

10 秒

躍點數目上限

10

自我JOIN的最大數量

20

投影欄位的最大數目

20

條件運算式的最大數目 (ANDOR、、NOT)

10

LIKE運算式模式的最大長度 (包括萬用字元和逸出字元)

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

最大值 LIMIT

3000

遍歷的最大值 (+) OFFSET LIMIT

3000