AWS IoT TwinMaker knowledge graph additional resources
This topic provides basic examples of the PartiQL syntax used to write queries in the knowledge graph, as well as links to PartiQL documentation that provide information on the knowledge graph data model.
This set of examples provides basic queries with responses. Use this as refrence to write your own queries.
- Basic queries
-
-
Get all entities with a filter
SELECT entity FROM EntityGraph MATCH (entity) WHERE entity.entityName = 'room_0'
This query returns all the entities in a workspace with name
room_0
.FROM
clause:EntityGraph
in the is a graph collection that contains all the entities and their relationships in a workspace. This collection is automatically created and managed by AWS IoT TwinMaker based on the entities in your workspace.MATCH
clause: specifies a pattern that matches a portion of the graph. In this case, the pattern()
matches every node in the graph and is bound to the entity variable. TheFROM
clause must be followed by theMATCH
clause.WHERE
clause: specifies a filter on the entityName field of the node where the value must beroom_0
.SELECT
clause: specifies the entity variable so the whole entity node is returned.Response:
{ "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 } ] } ] } ] } ] }
The
columnDescriptions
returns metadata about the column such as the name and type. The type returned isNODE
. This indicates that the whole node has been returned. Other values for type can beEDGE
which would indicate a relationship orVALUE
which would indicate a scalar value like integer or string.The
rows
returns a list of rows. As only one entity was matched, onerowData
is returned which contains all the fields in an entity.Note
Unlike SQL where you can only return scalar values, you can return an object (as JSON) using PartiQL.
Each node contains all the entity-level fields such as entityId, arn and components, component-level fields such as componentName, componentTypeId and properties as well as property-level fields such as propertyName and propertyValue all as a nested JSON.
-
Get all relationships with a filter:
SELECT relationship FROM EntityGraph MATCH (e1)-[relationship]->(e2) WHERE relationship.relationshipName = 'isLocationOf'
This query returns all the relationships in a workspace with relationship name
isLocationOf
.The
MATCH
clause: specifies a pattern that matches two nodes, indicated by()
, that are connected by a directed edge, indicated by-[]->
and bound to a variable calledrelationship
.The
WHERE
clause: specifies a filter on therelationshipName
field of the edge where the value isisLocationOf
.The
SELECT
clause: specifies the relationship variable so the whole edge node is returned.Response
{ "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 ] }
The type of the column in columnDescriptions is an
EDGE
.Each
rowData
represents an edge with fields likerelationshipName
, this is the same as the relationship property name defined on the entity. ThesourceEntityId
,sourceComponentName
andsourceComponentTypeId
gives information about which entity and component the relationship property was defined on. ThetargetEntityId
specified which entity this relationship is pointing towards. -
Get all entities with a certain relationship to a certain entity
SELECT e2.entityName FROM EntityGraph MATCH (e1)-[r]->(e2) WHERE relationship.relationshipName = 'isLocationOf' AND e1.entityName = 'room_0'
This query returns all the entity names of all entities that have a
isLocationOf
relationship withroom_0
entity.MATCH clause: specifies a pattern that matches any two nodes (e1, e2) that has a directed edge (r).
The
WHERE
clause: specifies a filter on the relationship name and source entity’s name.The
SELECT
clause: return the entityName field within the e2 node.Response
{ "columnDescriptions": [ { "name": "entityName", "type": "VALUE" } ], "rows": [ { "rowData": [ "floor_0" ] } ] }
\u0000
In the columnDescriptions, the type of the column is
VALUE
since entityName is a string.One entity
floor_0
is returned.
-
- MATCH
-
The following patterns are supported in a MATCH clause:
-
Matches node b pointing to node a:
FROM EntityGraph MATCH (a)-[rel]-(b)
-
Matches node a pointing to node b:
FROM EntityGraph MATCH (a)-[]->(b)
There is no variable bound to relationship assuming a filter doesn’t need to be specified on the relationship.
-
Matches node a pointing to node b and node b pointing to node a:
FROM EntityGraph MATCH (a)-[rel]-(b)
This will return two matches: one from a to b and another from b to a so the recommendation is to use directed edges wherever possible.
-
The relationship name is also a label of the property graph EntityGraph so you can simply specify the relationship name following a : colon instead of specify a filter on rel.relationshipName in the WHERE clause.
FROM EntityGraph MATCH (a)-[:isLocationOf]-(b)
-
Chaining: patterns can be chained to match on multiple relationships.
FROM EntityGraph MATCH (a)-[rel1]->(b)-[rel2]-(c)
-
Variable hop patterns can span multiple nodes and edges as well:
FROM EntityGraph MATCH (a)-[]->{1,5}(b)
his query matches any pattern with outgoing edges from node a within 1 to 5 hops.The allowed quantifiers are:
{m,n}
- between m and n repetitions{m,}
- m or more repetitions.
-
- FROM:
-
An entity node can contain nested data such as components which themselves contain further nested data such as properties. These can be accessed by unnesting the result of the MATCH pattern.
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'
Access nested fields by dotting
.
into a variable. A comma,
is used to unnest (or join) entities with the components inside and then the properties inside those components.AS
is used to bind a variable to the unnested variables so that they can be used in theWHERE
orSELECT
clauses. This query returns all entities that contains a property namedroomFunction
with valuemeeting
in a component with component type idcom.example.query.construction.room
To access multiple nested fields of a field such as multiple components in an entity, use the comma notation to do a join.
SELECT e FROM EntityGraph MATCH (e), e.components AS c1, e.components AS c2
- SELECT:
-
-
Return a node:
SELECT e FROM EntityGraph MATCH (e)
-
Return an edge:
SELECT r FROM EntityGraph MATCH (e1)-[r]->(e2)
-
Return a scalar value:
SELECT floor.entityName, room.description, p.propertyValue AS roomfunction FROM EntityGraph MATCH (floor)-[:isLocationOf]-(room), room.components AS c, c.properties AS p
Format the name of the output field by aliasing it using
AS
. Here, instead ofpropertyValue
as column name in the response,roomfunction
is returned. -
Return aliases:
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%'
Using aliases is highly recommended to be explicit, increase readability and avoid any ambiguities in your queries.
-
- WHERE:
-
The supported logical operators are
AND
,NOT
andOR
.The supported comparison operators are
<
,<=
,>
,=>
,=
, and!=
.Use the
IN
keyword if you want to specify multiple or conditions on the same field.-
Filter on an entity, component or property field:
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'
-
Filter on property configuration. Here
unit
is the key in the configuration map and Celsius is the value.WHERE p.definition.configuration.unit = 'Celsius'
-
Check if a map property contains a given key and value:
WHERE p.propertyValue.length = 20.0
-
Check if a map property contains a given key:
WHERE NOT p.propertyValue.length IS MISSING
-
Check if a list property contains a given value:
WHERE 10.0 IN p.propertyValue
-
Use the
lower()
function for case insensitive comparisons. By default, all comparisons are case sensitive.WHERE lower(p.propertyValue) = 'meeting'
- LIKE:
-
Useful if you do not know the exact value for a field and can perform full text search on the specified field.
%
represents zero or more.WHERE e.entityName LIKE '%room%'
-
Infix search:
%room%
-
Prefix search:
room%
-
Suffix search:
%room
-
If you have
%
in your values, then put an escape character inLIKE
and specify the character inESCAPE
.
WHERE e.entityName LIKE 'room\%' ESCAPE '\'
-
- DISTINCT:
-
SELECT DISTINCT c.componentTypeId FROM EntityGraph MATCH (e), e.components AS c
-
The
DISTINCT
keyword eliminates duplicates from the final result. -
DISTINCT
is not supported on complex data types.
-
- LIMIT and OFFSET:
-
SELECT e.entityName FROM EntityGraph MATCH (e) WHERE e.entityName LIKE 'room_%' LIMIT 10 OFFSET 5
LIMIT
specifies the number of results to be returned in the query, andOFFSET
specifies the number of results to skip.
Listed below are the AWS IoT TwinMaker knowledge graph query limits:
Limit Name | Quota | Adjustable |
---|---|---|
Query execution timeout |
10 seconds | No |
Maximum number of hops |
10 | Yes |
Maximum number of self JOINs |
20 | Yes |
Maximum number of projected fields |
20 | Yes |
Maximum number of conditional expressions (AND, OR, NOT) |
10 | Yes |
Maximum length of a LIKE expression pattern (including wildcards and escapes) |
20 | Yes |
Maximum number of items that can be specified in an IN clause | 10 | Yes |
Maximum value for OFFSET | 3000 | Yes |
Maximum value for LIMIT |
3000 | Yes |
Maximum value for traversals (OFFSET + LIMIT) |
3000 | Yes |