本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
AWS IoT TwinMaker 知識圖表其他資源
本節提供用於在知識圖表中撰寫查詢的 PartiQL 語法的基本範例,以及提供知識圖資料模型相關資訊的 PartiQL 文件連結。
這組示例顯示了基本查詢及其響應。使用此作為編寫自己的查詢的參考。
- 基本查詢
-
-
使用過濾器獲取所有實體
SELECT entity FROM EntityGraph MATCH (entity) WHERE entity.entityName = 'room_0'
此查詢會傳回名稱為工作區中的所有實體
room_0
。FROM
clause:EntityGraph
是包含工作區中所有實體及其關係的圖形集合。系統會 AWS IoT TwinMaker 根據工作區中的實體自動建立和管理此集合。MATCH
子句:指定與圖形的一部分匹配的模式。在這種情況下,模式(entity)
匹配圖中的每個節點,並綁定到實體變量。該FROM
條款之後必須接有MATCH
條款。WHERE
clause:在節點的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
、元件層級欄位 (例如componentTypeId
和properties
)componentName
,以及屬性層級欄位 (例如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" ] } ] }
在列說明中,列的類型
entityName
是VALUE
一個字符串。傳回一個實體
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
用來將變數繫結至非巢狀變數,以便在WHERE
或SELECT
子句中使用它們。此查詢返回包含與組件類型 ID 的組件meeting
中roomFunction
的 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%'
強烈建議使用別名是明確的,提高可讀性,並避免查詢中的任何歧義。
-
- 哪裡:
-
支援的邏輯運算子為
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'
- 喜歡:
-
如果您不知道某個字段的確切值,並且可以在指定的字段上執行全文本搜索,則非常有用。
%
代表零個或更多。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
巢狀複雜欄位和圖形模式欄位不支援。COUNT
DISTINCT
和巢狀查詢不支援彙總。例如,不支援
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 連接 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 之間的每個路徑/模式的所有節點和邊緣。
- 限制和偏移:
-
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-results
是 ExecuteQuery 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 | 是 |
自我 |
20 | 是 |
投影欄位的最大數目 |
20 | 是 |
條件運算式的最大數目 ( |
10 | 是 |
|
20 | 是 |
可在IN 子句中指定的項目數目上限 |
10 | 是 |
最大值 OFFSET |
3000 | 是 |
最大值 |
3000 | 是 |
遍歷的最大值 (+) |
3000 | 是 |