Überblick

Streamdaten bieten Zugriff auf Zeitreihendaten, die in CrateDB gespeichert sind. Während Runtime-Abfragen den aktuellen Zustand von Entitäten aus MongoDB abrufen, rufen Streamdaten-Abfragen historische Messwerte und Ereignisse ab, die über die Zeit aufgezeichnet wurden – etwa Sensormesswerte, Maschinenkennzahlen oder Werte der Energieerzeugung.

Zeitreihendaten werden in Stream Data Archives erfasst – CrateDB-Tabellen pro Tenant und pro CK-Typ mit typisiertem Schema, einem expliziten Lebenszyklus und einem dreistufigen Aktivierungs-Gate. Jede Abfrage und jeder Insert unten adressiert ein Archiv über dessen archiveRtId.

Streamdaten vs. Runtime-Abfragen

	Streamdaten	Runtime
Zweck	Historische Zeitreihendaten	Aktueller Entitätszustand
Speicher	CrateDB	MongoDB
Schlüsselfeld	`timestamp`	`rtId`
Typische Daten	Sensormesswerte, Messungen, Ereignisse	Entitäten, Konfigurationen, Beziehungen
Abfrage-Wurzel	`streamData`	`runtime`

API-Ansätze

OctoMesh bietet drei Möglichkeiten, Streamdaten abzufragen:

Ansatz	Endpunkt	Anwendungsfall
Typed	`streamData.[typeName]`	Stark typisierte Abfragen für einen bekannten CK-Typ. Liefert typisierte Felder direkt zurück.
Transient	`streamData.transientStreamDataQuery`	Ad-hoc-Abfragen, bei denen Spalten und Filter zur Anfragezeit angegeben werden.
Persisted	`streamData.streamDataQuery`	Eine gespeicherte Abfragedefinition über ihre `rtId` ausführen.

Abfragetypen

Abfragetyp	Beschreibung	Detailseite
Simple Query	Rohe Zeitreihenzeilen mit Spaltenauswahl, Filterung und Sortierung abrufen	Simple Query
Aggregation Query	Aggregierte Werte (AVG, MIN, MAX, COUNT, SUM) über Datenpunkte berechnen	Aggregation Queries
Grouped Aggregation Query	Werte gruppiert nach einer oder mehreren Spalten aggregieren	Aggregation Queries
Downsampling Query	Datendichte reduzieren, indem Zeiträume mit Aggregation in Buckets zusammengefasst werden	Downsampling Query

Alle Abfragetypen sind sowohl als transiente (Ad-hoc-) als auch als persistierte (gespeicherte) Variante verfügbar.

Typed Query

Die Abfrage-Wurzel streamData stellt typisierte Felder für jeden CK-Typ bereit, für den Streamdaten aktiviert sind. Die Feldnamen werden aus dem vollständigen Namen des CK-Typs (mit entfernten Punkten und Schrägstrichen) in camelCase abgeleitet. Zum Beispiel wird der CK-Typ Industry.Energy/EnergyMeter zu industryEnergyEnergyMeter.

query {
  streamData {
    industryEnergyEnergyMeter {
      items {
        rtId
        ckTypeId
        timeStamp
        voltage
      }
    }
  }
}

Eine Antwort auf diese Abfrage kann wie folgt aussehen:

{
  "data": {
    "streamData": {
      "industryEnergyEnergyMeter": {
        "items": [
          {
            "rtId": "65dc6d24cc529cdc46c84fcc",
            "ckTypeId": "Industry.Energy/EnergyMeter",
            "timeStamp": "2024-03-21T16:22:47.676Z",
            "voltage": 4.04196210149963
          },
          {
            "rtId": "65dc6d24cc529cdc46c84fcc",
            "ckTypeId": "Industry.Energy/EnergyMeter",
            "timeStamp": "2024-03-21T16:23:50.675Z",
            "voltage": -9.00808094383129
          }
        ]
      }
    }
  }
}

Typisierte Abfragen liefern Attributwerte als benannte Felder zurück (z. B. voltage). Für flexiblere Abfragen, bei denen Sie die Spalten zur Anfragezeit auswählen, verwenden Sie stattdessen den Ansatz der transienten Abfrage.

Paginierung

Streamdaten-Abfragen unterstützen cursorbasierte Paginierung über die Parameter first und after. Der Parameter first gibt die Anzahl der zurückzugebenden Elemente an, während after die Cursor-Position angibt, ab der abgerufen werden soll.

query {
  streamData {
    industryEnergyEnergyMeter(first: 2, after: "YXJyYXljb25uZWN0aW9uOjE=") {
      pageInfo {
        endCursor
        hasNextPage
      }
      items {
        rtId
        ckTypeId
        timeStamp
        voltage
      }
    }
  }
}

Die Antwort enthält pageInfo mit endCursor (als after-Wert für die nächste Seite verwenden) und hasNextPage (gibt an, ob weitere Daten verfügbar sind). Das Feld totalCount ist ebenfalls auf allen Streamdaten-Connections verfügbar.

Gemeinsame Parameter

StreamDataArguments

Der Eingabetyp StreamDataArguments wird verwendet, um beim Ausführen von Abfragen Zeitfilterung und Limits anzugeben:

Feld	Typ	Erforderlich	Beschreibung
from	`DateTime`	Nein	Beginn des abzufragenden Zeitraums
to	`DateTime`	Nein	Ende des abzufragenden Zeitraums
limit	`Int`	Nein	Maximale Anzahl der zurückzugebenden Datenpunkte
queryMode	`QueryMode`	Ja	Ausführungsmodus der Abfrage (`DEFAULT` verwenden)
interval	`Seconds`	Nein	Zeitintervall für das Downsampling

FieldFilter

Feldbezogene Filter erlauben es, Ergebnisse anhand von Attributwerten einzuschränken:

Feld	Typ	Erforderlich	Beschreibung
attributePath	`String`	Ja	Das Attribut, nach dem gefiltert wird
operator	`FieldFilterOperators`	Ja	Vergleichsoperator
comparisonValue	`SimpleScalar`	Nein	Wert, mit dem verglichen wird

Verfügbare Operatoren: EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_EQUAL_THAN, LESS_THAN, LESS_EQUAL_THAN, LIKE, NOT_IN, IN, ANY_EQ, ANY_LIKE, MATCH_REG_EX

Sort

Feld	Typ	Erforderlich	Beschreibung
attributePath	`String`	Ja	Das Attribut, nach dem sortiert wird
sortOrder	`SortOrders`	Nein	`ASCENDING`, `DESCENDING` oder `DEFAULT`

Ergebnisstruktur

Alle Streamdaten-Abfragen liefern eine StreamDataQueryRowDtoConnection mit folgender Struktur zurück:

Feld	Typ	Beschreibung
totalCount	`Int`	Gesamtzahl der übereinstimmenden Zeilen
pageInfo	`PageInfo`	Informationen zum Paginierungs-Cursor
items	`[StreamDataQueryRow]`	Die Ergebniszeilen

Jede StreamDataQueryRow enthält:

Feld	Typ	Beschreibung
rtId	`OctoObjectId`	Die Runtime-Entität, zu der dieser Datenpunkt gehört
ckTypeId	`RtCkTypeId`	Der CK-Typ-Bezeichner
timestamp	`DateTime`	Der Zeitstempel des Datenpunkts
rtWellKnownName	`String`	Optionaler Well-Known-Name der Entität
cells	`RtQueryCellDtoConnection`	Datenwerte als `attributePath`/`value`-Paare

Die cells-Connection wird von transienten und persistierten Abfragen verwendet. Jede Zelle enthält einen attributePath (den Spaltennamen) und einen value (den Wert des Datenpunkts). Typisierte Abfragen liefern Werte stattdessen als benannte Felder direkt zurück.

hinweis

Typisierte Abfragen verwenden timeStamp (großes S) als Feldnamen, während transiente und persistierte Abfragen timestamp (kleingeschrieben) verwenden. Dieser Unterschied spiegelt die zugrunde liegenden Datentypen wider, die von den jeweiligen Abfrageansätzen verwendet werden.

Weiterführende Literatur

Simple Query – Rohe Zeitreihendaten mit Filterung, Sortierung und Spaltenauswahl abfragen
Aggregation Queries – Aggregierte und gruppierte Werte berechnen
Downsampling Query – Datendichte durch Zeit-Bucketing reduzieren
Persisted Queries – Wiederverwendbare Abfragedefinitionen speichern, verwalten und ausführen

Streamdaten vs. Runtime-Abfragen​

API-Ansätze​

Abfragetypen​

Typed Query​

Paginierung​

Gemeinsame Parameter​

StreamDataArguments​

FieldFilter​

Sort​

Ergebnisstruktur​

Weiterführende Literatur​