本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
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)。
每個節點都包含所有實體層級欄位,例如
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 動作的選用參數。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 | 是 |
自我數量上限 |
20 | 是 |
預計欄位數量上限 |
20 | 是 |
條件式表達式數目上限 ( |
10 | 是 |
|
20 | 是 |
可在 IN 子句中指定的項目數量上限 |
10 | 是 |
的最大值 OFFSET |
3000 | 是 |
的最大值 |
3000 | 是 |
周遊的最大值 ( |
3000 | 是 |