Retrieve
GraphQL allows to query and mutate data. Mutations are operations like create, update and delete. This chapter describes how data can be retrieved.
Simple query
The area runtime allows access to entities fo the Runtime Model Let's start with simple sample that requests the name of all energy meters and return the runtime identifier (rtId), construction kit type identifier (ckTypeId) and the name of the energy meter.
query {
runtime {
industryEnergyEnergyMeter {
items {
rtId
ckTypeId
name
}
}
}
}
The result of that query
{
"data": {
"runtime": {
"industryEnergyEnergyMeter": {
"items": [
{
"rtId": "65dc6d24cc529cdc46c84fcc",
"ckTypeId": "Industry.Energy/EnergyMeter",
"name": "EnergyMeter1"
}
]
}
}
}
}
This query has some disadvantages. The amount of objects returned depends on the amount of objects stored. The next sample uses pagination to limit the amount of objects returned.
Pagination
query {
runtime {
industryEnergyEnergyMeter(first: 1) {
pageInfo {
endCursor
startCursor
}
items {
rtId
ckTypeId
name
}
}
}
}
This query uses an argument first that limits the result to 1. We use pageInfo to retrieve the start and end cursor to continue pagination.
{
"data": {
"runtime": {
"industryEnergyEnergyMeter": {
"pageInfo": {
"endCursor": "YXJyYXljb25uZWN0aW9uOjA=",
"startCursor": "YXJyYXljb25uZWN0aW9uOjA="
},
"items": [
{
"rtId": "65dc6d24cc529cdc46c84fcc",
"ckTypeId": "Industry.Energy/EnergyMeter",
"name": "EnergyMeter1"
}
]
}
}
}
}
The end cursor can be used for the next pagination:
query {
runtime {
industryEnergyEnergyMeter(first: 1, after:"YXJyYXljb25uZWN0aW9uOjA=") {
pageInfo {
endCursor
startCursor
}
items {
rtId
ckTypeId
name
}
}
}
}
The result will be the next page:
{
"data": {
"runtime": {
"industryEnergyEnergyMeter": {
"pageInfo": {
"endCursor": "YXJyYXljb25uZWN0aW9uOjE=",
"startCursor": "YXJyYXljb25uZWN0aW9uOjE="
},
"items": [
{
"rtId": "662532d5241639b42933057e",
"ckTypeId": "Industry.Energy/EnergyMeter",
"name": "Hello, World!"
}
]
}
}
}
}
Filter options
There are different types of filters available to request data based on specific conditions. Typically, filters can be used in a parallel way.
RtId filter
The rtId filter allows to request data based on the runtime identifier. The type of argument rtId is a runtime identifier, the type of argument rtIds is an array of runtime identifiers.
query {
runtime {
industryEnergyEnergyMeter(rtId: "6628101bf163c7c8f8676a33") {
totalCount
items {
rtId
name
}
}
}
}
The result will be the energy meter with the runtime identifier "6628101bf163c7c8f8676a33".
{
"data": {
"runtime": {
"industryEnergyEnergyMeter": {
"totalCount": 1,
"items": [
{
"rtId": "6628101bf163c7c8f8676a33",
"name": "EnergyMeter1"
}
]
}
}
}
}
Field filters
Field filters allow to request data based on specific conditions of different fields
There are different operators available:
| Operator | Description |
|---|---|
| EQUALS | Checks for equality between scalar value of the field and comparison value |
| NOT_EQUALS | Checks for non-equality between scalar value of the field and comparison value |
| LESS_THAN | Checks if a numerical value of a field is less than the comparison value |
| LESS_EQUAL_THAN | Checks if a numerical value of a field is less or equal than the comparison value |
| GREATER_THAN | Checks if a numerical value of a field is greater than the comparison value |
| GREATER_EQUAL_THAN | Checks if a numerical value of a field is greater or equal than the comparison value |
| IN | Checks if the value of a field is one of the values of the comparison value |
| NOT_IN | Checks if the value of a field is not one of the values of the comparison value |
| LIKE | Use wildcards (*) to compare string scalar value to the value of a field (e. g. demo) |
| MATCH_REG_EX | Use regex to compare string scalar value to the value of a field (e. g. ^demo$) |
| ANY_EQ | For fields that are scalar arrays, it is checked in any element is equal to the comparison value |
Field filters are an array that are combined using AND logical operator.
query {
runtime {
systemCommunicationDataPipeline(fieldFilter:[{attributeName:"name", operator:EQUALS, comparisonValue:"Simulation Pipeline"}]) {
items {
rtId
name
children {
systemCommunicationPipeline {
items {
name
rtId
executedBy {
systemCommunicationAdapter {
items {
rtId
ckTypeId
name
}
}
}
}
}
}
}
}
}
}
geoNear filter
geoNear filter allow to filter for data from nearest to farthest on a geospatial point. The type of argument geoNearFilter is a complex object to configure the filter.
| Property | Description |
|---|---|
| attributeName | The attribute name that represents a geospatial point |
| minDistance | Minimal distance from point to filter for data in meter |
| maxDistance | Maximal distance from point to filter for data in meter |
| point | A point that specifies a point. |
query getFireReports($position:PositionInput!, $minDistance:Float, $maxDistance:Float) {
runtime {
fireGuardiansFireReport(
first: 200,
geoNearFilter: {
attributeName: "location"
minDistance: $minDistance
maxDistance: $maxDistance
point: { coordinates: $position }
}
) {
items {
rtId
rtCreationDateTime
name
description
location {
distance
point {
coordinates {
latitude
longitude
}
}
}
}
}
}
}
Geospatial data types contains a field that describes, when geoNear filter is used, the distance in meter from the in the filter specified point.
{
"data": {
"runtime": {
"fireGuardiansFireReport": {
"items": [
{
"rtId": "65d5c447b420da3fb12381b9",
"rtCreationDateTime": "2022-02-22T09:00:00Z",
"name": "FireReport1",
"description": "FireReport1",
"location": {
"distance": 4508,
"point": {
"coordinates": {
"latitude": 48.123456,
"longitude": 11.123456
}
}
}
}
]
}
}
}
}
Sort order
The default sort order is based on the rtId. The sort order can be changed using the argument orderBy. The argument orderBy is an array of objects that contains the field name and the sort order.
| Sort Order | Description |
|---|---|
| ASCENDING | Sorts the given attribute ascending |
| DESCENDING | Sorts the given attribute descending |
| DEFAULT | Uses the default sort from database |
Sample to sort the energy meters by name in ascending order:
query {
runtime {
industryEnergyEnergyMeter(sortOrder:[{attributeName:"name", sortOrder:ASCENDING}]) {
items {
rtId
name
}
}
}
}
The result will be sorted by the name in ascending order.
{
"data": {
"runtime": {
"industryEnergyEnergyMeter": {
"items": [
{
"rtId": "65dc6d24cc529cdc46c84fcc",
"name": "EnergyMeter1"
},
{
"rtId": "662532d5241639b42933057e",
"name": "Hello, World!"
}
]
}
}
}
}
Grouping
Grouping allows to group data based on fields. The type of argument groupBy is a complex object that allows to group by multiple fields and the type of aggregation.
| Aggregation | Description |
|---|---|
| groupByAttributeNameList | List of attribute names the grouping is applied |
| minValueAttributeNameList | List of attribute names the min value within the group is applied |
| maxValueAttributeNameList | List of attribute names the max value within the group is applied |
| countAttributeNameList | List of attribute names the values not null are counted |
| avgAttributeNameList | List of attribute names the average value within the group is applied |
The next sample groups the energy meters by state and retrieves the measured max voltage
query {
runtime {
industryEnergyEnergyMeter(
groupBy: {
groupByAttributeNameList: ["state"]
maxValueAttributeNameList: ["voltage"]
}
) {
totalCount
groupings {
keys
count
maxStatistics {
attributeName
value
}
}
}
}
}
The result will be grouped by the state and the max voltage will be retrieved.
{
"data": {
"runtime": {
"industryEnergyEnergyMeter": {
"totalCount": 2,
"groupings": [
{
"keys": [
"OFF"
],
"count": 10,
"maxStatistics": [
{
"attributeName": "voltage",
"value": 243
}
]
},
{
"keys": [
"ON"
],
"count": 13,
"maxStatistics": [
{
"attributeName": "voltage",
"value": 235
}
]
}
]
}
}
}
}
Associations
Available associations can be accessed using the corresponding navigation properties.
query {
runtime {
systemCommunicationDataPipeline {
items {
rtId
name
children {
systemCommunicationPipeline {
items {
name
rtId
executedBy {
systemCommunicationAdapter {
items {
rtId
ckTypeId
name
}
}
}
}
}
}
}
}
}
}
This sample returns the children of data pipeline that are edge or mesh pipelines and the children of them are adapters.
{
"data": {
"runtime": {
"systemCommunicationDataPipeline": {
"items": [
{
"rtId": "65d5c447b420da3fb12381bd",
"name": "Simulation Pipeline",
"children": {
"systemCommunicationPipeline": {
"items": [
{
"name": null,
"rtId": "65d5c447b420da3fb12381be",
"executedBy": {
"systemCommunicationAdapter": {
"items": [
{
"rtId": "65d5c447b420da3fb12381bc",
"ckTypeId": "System.Communication/EdgeAdapter",
"name": "Simulation Demo Adapter"
}
]
}
}
},
{
"name": null,
"rtId": "65d5c447b420da3fb12381bf",
"executedBy": {
"systemCommunicationAdapter": {
"items": [
{
"rtId": "66004fda527ac79a03ecedd7",
"ckTypeId": "System.Communication/MeshAdapter",
"name": "meshtest Adapter"
}
]
}
}
}
]
}
}
}
]
}
}
}
}
Query indirect associations
Indirect associations can be queried by using the navigation properties of the association.
query {
runtime {
basicEquipmentGroup(rtId: "667acc3be06025c7329fc57c") {
items {
rtId
ckTypeId
associations(
roleId: "System/ParentChild"
direction: INBOUND
ckId: "Industry.Basic/Machine"
includeIndirect:true
) {
items {
rtId
ckTypeId
}
}
}
}
}
}
This sample returns the indirect children of type Industry.Basic/Machine of an equipment group
{
"data": {
"runtime": {
"basicEquipmentGroup": {
"items": [
{
"rtId": "667acc3be06025c7329fc57c",
"ckTypeId": "Basic/EquipmentGroup",
"associations": {
"items": [
{
"rtId": "667acc3be06025c7329fc5a9",
"ckTypeId": "Industry.Basic/Machine"
},
{
"rtId": "667acc3be06025c7329fc5a4",
"ckTypeId": "Industry.Basic/Machine"
},
{
"rtId": "667acc3be06025c7329fc595",
"ckTypeId": "Industry.Basic/Machine"
},
{
"rtId": "667acc3be06025c7329fc585",
"ckTypeId": "Industry.Basic/Machine"
},
{
"rtId": "667acc3be06025c7329fc58a",
"ckTypeId": "Industry.Basic/Machine"
},
{
"rtId": "667acc3be06025c7329fc580",
"ckTypeId": "Industry.Basic/Machine"
},
{
"rtId": "667acc3be06025c7329fc5aa",
"ckTypeId": "Industry.Basic/Machine"
},
{
"rtId": "667acc3be06025c7329fc5ab",
"ckTypeId": "Industry.Basic/Machine"
},
{
"rtId": "667acc3be06025c7329fc5ad",
"ckTypeId": "Industry.Basic/Machine"
},
{
"rtId": "667acc3be06025c7329fc58f",
"ckTypeId": "Industry.Basic/Machine"
}
]
}
}
]
}
}
}
}