Persisted Queries

Persistierte Abfragen sind gespeicherte Abfragedefinitionen, die als Runtime-Entitäten abgelegt werden. Anstatt jedes Mal alle Abfrageparameter anzugeben, erstellen Sie eine Abfragedefinition einmal und führen sie über ihre rtId aus. Das ist nützlich für Dashboard-Widgets, wiederkehrende Berichte und jedes Szenario, in dem dieselbe Abfrage wiederholt ausgeführt werden muss.

Abfragetypen

Es gibt vier persistierte Abfragetypen, die den vier transienten Abfragetypen entsprechen:

CK-Typ	Zweck	Schlüsselfelder
System/StreamDataSimpleQuery	Rohe Zeitreihenzeilen	columns (String-Array), sorting
System/StreamDataAggregationQuery	Aggregierte Werte	columns (mit Aggregationstyp)
System/StreamDataGroupingAggregationQuery	Gruppierte Aggregation	groupingColumns, columns (mit Aggregationstyp)
System/StreamDataDownsamplingQuery	Zeit-Bucket-Aggregation	columns (mit Aggregationstyp), erforderlich from/to/limit

Gemeinsame Felder

Alle persistierten Abfragetypen teilen sich diese Konfigurationsfelder:

Feld	Typ	Beschreibung
name	String	Anzeigename der Abfrage
description	String	Optionale Beschreibung
queryCkTypeId	String	Der abzufragende CK-Typ (z. B. "Industry.Energy/EnergyMeter")
navigationFilterMode	String	Filtermodus für die Runtime-Navigation
rtIds	[String]	Optional: auf bestimmte Runtime-Entitäts-IDs eingrenzen
from	DateTime	Optional: Beginn des Zeitraums
to	DateTime	Optional: Ende des Zeitraums
limit	Int	Optional: maximale Anzahl zurückzugebender Zeilen
fieldFilter	[FieldFilter]	Optional: feldbezogene Vergleichsfilter

hinweis

Persistierte Abfragen verwenden den CK-generierten Enum AggregationTypes mit den Werten COUNT, MINIMUM, MAXIMUM, AVERAGE und SUM. Dies unterscheidet sich vom Enum AggregationType der transienten Abfrage, das die Kurzformen AVG, MIN, MAX, COUNT und SUM verwendet.

---

Persistierte Abfragen erstellen

Simple Query

Erstellt eine gespeicherte Abfrage, die rohe Zeitreihenzeilen mit Spaltenauswahl abruft.

mutation {
  runtime {
    systemStreamDataSimpleQuerys {
      create(entities: [
        {
          name: "Voltage readings last 24h"
          description: "Raw voltage data for all energy meters"
          queryCkTypeId: "Industry.Energy/EnergyMeter"
          columns: ["voltage", "power"]
          from: "2024-03-21T00:00:00Z"
          to: "2024-03-22T00:00:00Z"
          limit: 5000
          sorting: [
            { attributePath: "timestamp", sortOrder: DESCENDING }
          ]
        }
      ]) {
        rtId
        ckTypeId
        name
        description
        queryCkTypeId
        columns
        from
        to
        limit
        sorting {
          attributePath
          sortOrder
        }
        fieldFilter {
          attributePath
          operator
          comparisonValue
        }
      }
    }
  }
}

Die Antwort enthält die rtId der neu erstellten Abfrage – verwenden Sie diese, um sie später auszuführen.

Aggregation Query

Erstellt eine gespeicherte Aggregationsabfrage mit angegebenen Aggregationsfunktionen pro Spalte.

mutation {
  runtime {
    systemStreamDataAggregationQuerys {
      create(entities: [
        {
          name: "Energy meter statistics"
          description: "Average, min, and max voltage"
          queryCkTypeId: "Industry.Energy/EnergyMeter"
          columns: [
            { attributePath: "voltage", aggregationType: AVERAGE },
            { attributePath: "voltage", aggregationType: MINIMUM },
            { attributePath: "voltage", aggregationType: MAXIMUM }
          ]
          from: "2024-03-21T00:00:00Z"
          to: "2024-03-22T00:00:00Z"
        }
      ]) {
        rtId
        ckTypeId
        name
        queryCkTypeId
        columns {
          aggregationType
          attributePath
        }
      }
    }
  }
}

Grouping Aggregation Query

Erstellt eine gespeicherte Abfrage, die Werte gruppiert nach einer oder mehreren Spalten aggregiert.

mutation {
  runtime {
    systemStreamDataGroupingAggregationQuerys {
      create(entities: [
        {
          name: "Average voltage per meter"
          description: "Grouped by entity"
          queryCkTypeId: "Industry.Energy/EnergyMeter"
          groupingColumns: ["rtId"]
          columns: [
            { attributePath: "voltage", aggregationType: AVERAGE },
            { attributePath: "power", aggregationType: MAXIMUM }
          ]
        }
      ]) {
        rtId
        ckTypeId
        name
        queryCkTypeId
        groupingColumns
        columns {
          aggregationType
          attributePath
        }
      }
    }
  }
}

Downsampling Query

Erstellt eine gespeicherte Downsampling-Abfrage. Die Felder from, to und limit definieren den Zeitraum und die Anzahl der Buckets.

mutation {
  runtime {
    systemStreamDataDownsamplingQuerys {
      create(entities: [
        {
          name: "Hourly voltage trend"
          description: "24h downsampled to hourly buckets"
          queryCkTypeId: "Industry.Energy/EnergyMeter"
          columns: [
            { attributePath: "voltage", aggregationType: AVERAGE },
            { attributePath: "voltage", aggregationType: MINIMUM },
            { attributePath: "voltage", aggregationType: MAXIMUM }
          ]
          from: "2024-03-21T00:00:00Z"
          to: "2024-03-22T00:00:00Z"
          limit: 24
        }
      ]) {
        rtId
        ckTypeId
        name
        queryCkTypeId
        columns {
          aggregationType
          attributePath
        }
        from
        to
        limit
      }
    }
  }
}

---

Persistierte Abfragen ausführen

Führen Sie eine gespeicherte Abfrage aus, indem Sie ihre rtId übergeben. Jeder Abfragetyp hat seinen eigenen Ausführungsendpunkt.

Simple Query

query {
  streamData {
    streamDataQuery(
      rtId: "67e1a2b3c4d5e6f7a8b9c0d1"
      first: 100
    ) {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
      items {
        rtId
        ckTypeId
        timestamp
        rtWellKnownName
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Aggregation Query

query {
  streamData {
    streamDataAggregationQuery(
      rtId: "67e1a2b3c4d5e6f7a8b9c0d2"
    ) {
      totalCount
      items {
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Grouping Aggregation Query

query {
  streamData {
    streamDataGroupingAggregationQuery(
      rtId: "67e1a2b3c4d5e6f7a8b9c0d3"
    ) {
      totalCount
      items {
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Downsampling Query

query {
  streamData {
    streamDataDownsamplingQuery(
      rtId: "67e1a2b3c4d5e6f7a8b9c0d4"
    ) {
      totalCount
      items {
        timestamp
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Parameter zur Ausführungszeit überschreiben

Alle Ausführungsendpunkte für persistierte Abfragen akzeptieren einen optionalen Parameter arg vom Typ StreamDataArguments. Damit können Sie den gespeicherten Zeitraum und das Limit zur Ausführungszeit überschreiben, ohne die Abfragedefinition zu ändern.

query {
  streamData {
    streamDataQuery(
      rtId: "67e1a2b3c4d5e6f7a8b9c0d1"
      arg: {
        queryMode: DEFAULT
        from: "2024-03-20T00:00:00Z"
        to: "2024-03-21T00:00:00Z"
        limit: 10000
      }
      first: 100
    ) {
      totalCount
      items {
        timestamp
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Die Ausführung der Simple Query unterstützt außerdem sortOrder, um die Sortierung zur Ausführungszeit zu überschreiben:

streamDataQuery(
  rtId: "67e1a2b3c4d5e6f7a8b9c0d1"
  arg: { queryMode: DEFAULT }
  sortOrder: [{ attributePath: "timestamp", sortOrder: ASCENDING }]
)

---

Abfragedetails abrufen

Rufen Sie die Konfiguration einer gespeicherten Abfrage ab:

query {
  runtime {
    systemStreamDataSimpleQuery(rtId: "67e1a2b3c4d5e6f7a8b9c0d1") {
      totalCount
      items {
        rtId
        name
        description
        queryCkTypeId
        columns
        rtIds
        from
        to
        limit
        sorting {
          attributePath
          sortOrder
        }
        fieldFilter {
          attributePath
          operator
          comparisonValue
        }
      }
    }
  }
}

Analog für die anderen Typen:

• systemStreamDataAggregationQuery(rtId: "...")
• systemStreamDataGroupingAggregationQuery(rtId: "...")
• systemStreamDataDownsamplingQuery(rtId: "...")

---

Persistierte Abfragen aktualisieren

Aktualisieren Sie eine gespeicherte Abfrage, indem Sie ihre rtId und die zu ändernden Felder angeben:

mutation {
  runtime {
    systemStreamDataSimpleQuerys {
      update(entities: [
        {
          rtId: "67e1a2b3c4d5e6f7a8b9c0d1"
          name: "Updated voltage query"
          columns: ["voltage", "power", "current"]
          limit: 10000
        }
      ]) {
        rtId
        name
        columns
        limit
      }
    }
  }
}

Dasselbe Muster gilt für die anderen Abfragetypen mit systemStreamDataAggregationQuerys, systemStreamDataGroupingAggregationQuerys und systemStreamDataDownsamplingQuerys.

---

Persistiert vs. transient im Vergleich

	Persistiert	Transient
Einrichtung	Einmal erstellen, über rtId ausführen	Alle Parameter pro Anfrage angeben
Wiederverwendbarkeit	Dieselbe Abfrage vielfach ausführen	Einmalige Abfragen
Dashboard-Integration	rtId in der Datenquellen-Konfiguration des Widgets verwenden	Nicht für Widgets geeignet
Parameter-Flexibilität	from/to/limit zur Ausführungszeit über arg überschreiben	Volle Kontrolle pro Anfrage
Verwaltung	Als Runtime-Entitäten gespeichert, können aufgelistet, aktualisiert und gelöscht werden	Keine Speicherung
Anwendungsfall	Produktions-Dashboards, wiederkehrende Berichte, geteilte Abfragen	Ad-hoc-Exploration, einmalige Analyse