System Queries

System Queries are reusable query configurations stored in the repository. They allow you to define a query once and execute it from multiple places using only its ID.

Overview

Unlike ad-hoc GraphQL queries where the query structure is defined in each request, System Queries store the query configuration (columns, filters, sorting) as an entity in the repository. This enables:

• Reusability: Use the same query definition across different applications
• Centralized management: Update the query in one place, changes apply everywhere
• Integration: Execute queries from Office Add-ins, Grafana, Power BI, and other tools
• Consistency: Ensure all consumers use the same query logic

How it works

┌─────────────────────────────────────────────────────────────┐
│                    System Query (Repository)                │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ rtId: "693c66ce464d7d9e1396cf1f"                    │    │
│  │ name: "Active Energy Meters"                        │    │
│  │ queryCkTypeId: "Industry.Energy/EnergyMeter"        │    │
│  │ columns: ["name", "voltage", "state"]               │    │
│  │ fieldFilter: [{ state: EQUALS "ON" }]               │    │
│  │ sorting: [{ name: ASCENDING }]                      │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
          ▼                   ▼                   ▼
    ┌──────────┐        ┌──────────┐        ┌──────────┐
    │  Office  │        │  Grafana │        │ Power BI │
    │  Add-in  │        │          │        │          │
    └──────────┘        └──────────┘        └──────────┘

Execute a System Query

To execute a stored System Query, use runtimeQuery with the query's rtId:

query {
  runtime {
    runtimeQuery(rtId: "693c66ce464d7d9e1396cf1f") {
      items {
        queryRtId
        columns {
          attributePath
          attributeValueType
        }
        rows(first: 10) {
          items {
            rtId
            ckTypeId
            cells {
              items {
                attributePath
                value
              }
            }
          }
        }
      }
    }
  }
}

Response structure

{
  "data": {
    "runtime": {
      "runtimeQuery": {
        "items": [
          {
            "queryRtId": "693c66ce464d7d9e1396cf1f",
            "columns": [
              {
                "attributePath": "contact.firstName",
                "attributeValueType": "STRING"
              },
              {
                "attributePath": "contact.address.street",
                "attributeValueType": "STRING"
              },
              {
                "attributePath": "contact.address.cityTown",
                "attributeValueType": "STRING"
              }
            ],
            "rows": {
              "items": [
                {
                  "rtId": "693c51af464d7d9e1396cf12",
                  "ckTypeId": "EnergyCommunity/Customer",
                  "cells": {
                    "items": [
                      {
                        "attributePath": "contact.firstName",
                        "value": "Jane"
                      },
                      {
                        "attributePath": "contact.address.street",
                        "value": "Sample Street 42"
                      },
                      {
                        "attributePath": "contact.address.cityTown",
                        "value": "Berlin"
                      }
                    ]
                  }
                },
                {
                  "rtId": "693c51af464d7d9e1396cf15",
                  "ckTypeId": "EnergyCommunity/Customer",
                  "cells": {
                    "items": [
                      {
                        "attributePath": "contact.firstName",
                        "value": "Paul"
                      },
                      {
                        "attributePath": "contact.address.street",
                        "value": "Testgasse 5"
                      },
                      {
                        "attributePath": "contact.address.cityTown",
                        "value": "Zürich"
                      }
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    }
  }
}

System Query configuration

A System Query entity contains the following configuration:

Field	Type	Description
name	String	Display name of the query
queryCkTypeId	String	The entity type to query (e.g., Industry.Energy/EnergyMeter)
columns	[String]	List of attribute paths to include as columns
sorting	[Sort]	Sort configuration
fieldFilter	[FieldFilter]	Attribute-based filters
attributeSearchFilter	AttributeSearchFilter	Wildcard search configuration
textSearchFilter	TextSearchFilter	Full-text search configuration

List all System Queries

query getQueries($first: Int, $after: String) {
  runtime {
    systemQuery(first: $first, after: $after) {
      totalCount
      items {
        rtId
        ckTypeId
        name
        queryCkTypeId
      }
    }
  }
}

Get System Query details

query getQueryDetails($rtId: OctoObjectId!) {
  runtime {
    systemQuery(rtId: $rtId) {
      items {
        rtId
        name
        queryCkTypeId
        columns
        sorting {
          attributePath
          sortOrder
        }
        fieldFilter {
          attributePath
          operator
          comparisonValue
        }
        attributeSearchFilter {
          attributePaths
          searchValue
        }
        textSearchFilter {
          searchValue
        }
      }
    }
  }
}

CRUD operations

Operation	Documentation
Create	Create System Queries
Update	Update System Queries
Delete	See Delete - use runtimeEntities.delete with ckTypeId: "System/Query"

System Queries vs Transient Queries

Aspect	System Query	Transient Query
Configuration	Stored in repository	Defined in each request
Reusability	High - use by ID	None - must repeat definition
Management	Centralized	Per-request
Use case	Shared queries across tools	Ad-hoc, one-time queries
Update	Change once, applies everywhere	Change each consumer

Use System Queries when:

• Multiple applications need the same query
• Query configuration should be managed centrally
• Integration with external tools (Office, Grafana, Power BI)

Use Transient Queries when:

• Query is application-specific
• Columns/filters change dynamically based on user input
• No need for reusability

Integration examples

Office Add-in

The Office Add-in can execute System Queries by referencing their rtId, allowing users to pull data into Excel or Word documents.

Grafana

Grafana dashboards can use System Queries as data sources, ensuring consistent data visualization across teams.

Power BI

Power BI reports can connect to System Queries for business intelligence reporting with the same query logic used in other applications.