System Queries

This chapter describes how to create System Queries. For an overview of System Queries and their use cases, see System Queries.

Create a System Query

Use the systemQuerys.create mutation to create a new System Query:

mutation createQuery($entities: [SystemQueryInput]!) {
  runtime {
    systemQuerys {
      create(entities: $entities) {
        rtId
        ckTypeId
        name
        queryCkTypeId
        columns
        sorting {
          attributePath
          sortOrder
        }
        fieldFilter {
          attributePath
          operator
          comparisonValue
        }
        attributeSearchFilter {
          attributePaths
          searchValue
        }
        textSearchFilter {
          searchValue
        }
      }
    }
  }
}

Basic example

Create a simple query that lists energy meters sorted by name:

{
  "entities": [
    {
      "name": "All Energy Meters",
      "queryCkTypeId": "Industry.Energy/EnergyMeter",
      "columns": ["name", "voltage", "state"],
      "sorting": [
        { "attributePath": "name", "sortOrder": "ASCENDING" }
      ]
    }
  ]
}

With field filters

Create a query that only returns active energy meters:

{
  "entities": [
    {
      "name": "Active Energy Meters",
      "queryCkTypeId": "Industry.Energy/EnergyMeter",
      "columns": ["name", "voltage", "ampere", "power", "state"],
      "sorting": [
        { "attributePath": "name", "sortOrder": "ASCENDING" }
      ],
      "fieldFilter": [
        { "attributePath": "state", "operator": "EQUALS", "comparisonValue": "ON" }
      ]
    }
  ]
}

With search filter

Create a query with a predefined attribute search:

{
  "entities": [
    {
      "name": "Energy Meters Search",
      "queryCkTypeId": "Industry.Energy/EnergyMeter",
      "columns": ["name", "description", "voltage", "state"],
      "attributeSearchFilter": {
        "attributePaths": ["name", "description"],
        "searchValue": ""
      }
    }
  ]
}

Input fields

Field	Type	Required	Description
name	String	Yes	Display name of the query
queryCkTypeId	String	Yes	The entity type to query (e.g., Industry.Energy/EnergyMeter)
columns	[String]	No	List of attribute paths to include as columns
sorting	[SortInput]	No	Default sort configuration
fieldFilter	[FieldFilterInput]	No	Default attribute-based filters
attributeSearchFilter	AttributeSearchFilterInput	No	Wildcard search configuration
textSearchFilter	TextSearchFilterInput	No	Full-text search configuration

Response

The mutation returns the created System Query with its assigned rtId:

{
  "data": {
    "runtime": {
      "systemQuerys": {
        "create": [
          {
            "rtId": "693c66ce464d7d9e1396cf1f",
            "ckTypeId": "System/Query",
            "name": "Active Energy Meters",
            "queryCkTypeId": "Industry.Energy/EnergyMeter",
            "columns": ["name", "voltage", "ampere", "power", "state"],
            "sorting": [
              { "attributePath": "name", "sortOrder": "ASCENDING" }
            ],
            "fieldFilter": [
              { "attributePath": "state", "operator": "EQUALS", "comparisonValue": "ON" }
            ]
          }
        ]
      }
    }
  }
}

Use the returned rtId to execute the query via runtimeQuery(rtId: "...").

---

Create data via System Query

System Queries can also be used to create new entities. This is useful when you want to add data in a tabular format (e.g., from Excel or a data grid).

mutation createQueryData($queryRtId: OctoObjectId!, $entities: [RtQueryRowInput!]!) {
  runtime {
    runtimeQuery(rtId: $queryRtId) {
      create(entities: $entities) {
        rtId
        ckTypeId
        rtWellKnownName
        rtVersion
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Variables:

{
  "queryRtId": "693c66ce464d7d9e1396cf1f",
  "entities": [
    {
      "cells": [
        { "attributePath": "contact.firstName", "value": "John" },
        { "attributePath": "contact.lastName", "value": "Doe" },
        { "attributePath": "contact.address.street", "value": "Main Street 1" },
        { "attributePath": "contact.address.cityTown", "value": "Berlin" }
      ]
    }
  ]
}

RtQueryRowInput structure

Field	Type	Description
cells	[RtQueryCellInput!]	List of cells (attribute path and value) to set

Response

The mutation returns the created rows with their assigned rtId and cell values:

{
  "data": {
    "runtime": {
      "runtimeQuery": {
        "create": [
          {
            "rtId": "693c51af464d7d9e1396cf20",
            "ckTypeId": "EnergyCommunity/Customer",
            "rtWellKnownName": null,
            "rtVersion": 1,
            "cells": {
              "items": [
                { "attributePath": "contact.firstName", "value": "John" },
                { "attributePath": "contact.lastName", "value": "Doe" },
                { "attributePath": "contact.address.street", "value": "Main Street 1" },
                { "attributePath": "contact.address.cityTown", "value": "Berlin" }
              ]
            }
          }
        ]
      }
    }
  }
}

This approach allows tools like Office Add-ins to create new entities using the same tabular structure as when reading data via the System Query.