Systemabfragen

Systemabfragen sind wiederverwendbare Abfragekonfigurationen, die im Repository gespeichert werden. Sie erlauben es Ihnen, eine Abfrage einmal zu definieren und sie von mehreren Stellen aus nur über ihre ID auszuführen.

Überblick

Anders als bei Ad-hoc-GraphQL-Abfragen, bei denen die Abfragestruktur in jeder Anfrage definiert wird, speichern Systemabfragen die Abfragekonfiguration (Spalten, Filter, Sortierung) als Entität im Repository. Das ermöglicht:

• Wiederverwendbarkeit: Dieselbe Abfragedefinition über verschiedene Anwendungen hinweg verwenden
• Zentrale Verwaltung: Die Abfrage an einer Stelle aktualisieren, Änderungen wirken sich überall aus
• Integration: Abfragen aus Office-Add-ins, Grafana, Power BI und anderen Werkzeugen ausführen
• Konsistenz: Sicherstellen, dass alle Konsumenten dieselbe Abfragelogik verwenden

Funktionsweise

┌─────────────────────────────────────────────────────────────┐
│                    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  │        │          │        │          │
    └──────────┘        └──────────┘        └──────────┘

Eine Systemabfrage ausführen

Um eine gespeicherte Systemabfrage auszuführen, verwenden Sie runtimeQuery mit der rtId der Abfrage:

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

Struktur der Antwort

{
  "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"
                      }
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    }
  }
}

Konfiguration der Systemabfrage

Eine Systemabfrage-Entität enthält die folgende Konfiguration:

Feld	Typ	Beschreibung
name	String	Anzeigename der Abfrage
queryCkTypeId	String	Der abzufragende Entitätstyp (z. B. Industry.Energy/EnergyMeter)
columns	[String]	Liste von Attributpfaden, die als Spalten aufgenommen werden
sorting	[Sort]	Sortierkonfiguration
fieldFilter	[FieldFilter]	Attributbasierte Filter
attributeSearchFilter	AttributeSearchFilter	Wildcard-Suchkonfiguration
textSearchFilter	TextSearchFilter	Volltextsuchkonfiguration

Alle Systemabfragen auflisten

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

Details einer Systemabfrage abrufen

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-Operationen

Operation	Dokumentation
Erstellen	Systemabfragen erstellen
Aktualisieren	Systemabfragen aktualisieren
Löschen	Siehe Löschen – verwenden Sie runtimeEntities.delete mit ckTypeId: "System/Query"

Systemabfragen vs. Transiente Abfragen

Aspekt	Systemabfrage	Transiente Abfrage
Konfiguration	Im Repository gespeichert	In jeder Anfrage definiert
Wiederverwendbarkeit	Hoch – Verwendung über ID	Keine – Definition muss wiederholt werden
Verwaltung	Zentral	Pro Anfrage
Anwendungsfall	Gemeinsame Abfragen über Werkzeuge hinweg	Ad-hoc-, Einmal-Abfragen
Aktualisierung	Einmal ändern, gilt überall	Jeden Konsumenten ändern

Verwenden Sie Systemabfragen, wenn:

• Mehrere Anwendungen dieselbe Abfrage benötigen
• Die Abfragekonfiguration zentral verwaltet werden soll
• Integration mit externen Werkzeugen (Office, Grafana, Power BI)

Verwenden Sie Transiente Abfragen, wenn:

• Die Abfrage anwendungsspezifisch ist
• Sich Spalten/Filter dynamisch basierend auf Benutzereingaben ändern
• Keine Wiederverwendbarkeit erforderlich ist

Integrationsbeispiele

Office Add-in

Das Office-Add-in kann Systemabfragen ausführen, indem es deren rtId referenziert, sodass Benutzer Daten in Excel- oder Word-Dokumente ziehen können.

Grafana

Grafana-Dashboards können Systemabfragen als Datenquellen verwenden und so eine konsistente Datenvisualisierung über Teams hinweg sicherstellen.

Power BI

Power-BI-Berichte können sich mit Systemabfragen verbinden, um Business-Intelligence-Berichte mit derselben Abfragelogik zu erstellen, die auch in anderen Anwendungen verwendet wird.