Zum Hauptinhalt springen

GetStreamData@1

Der Node GetStreamData@1 liest Zeilen direkt aus einem Stream-Data-Archiv. Er ist das Ad-hoc-Gegenstück zu GetQueryById@1: Archiv, Spalten, Zeitraum, Filter und Sortierung werden direkt am Node konfiguriert, eine persistierte Query-Entität wird nicht benötigt.

Der Node schreibt ein Query-Ergebnis (Spalten und Zeilen) nach targetPath, das QueryResultToMarkdownTable@1 direkt weiterverarbeiten kann. Optional meldet der Node zusätzlich, ob der abgefragte Zeitraum lückenlos mit Daten abgedeckt ist (Lückenerkennung).

Adapter-Voraussetzungen​

Node-Konfiguration​

Zu den Feldern targetPath, targetValueWriteMode und targetValueKind siehe Überblick. Das Feld path wird in diesem Node nicht verwendet.

transformations:
  - type: GetStreamData@1
    archiveRtId: 68a1f0c5de73e7b175575401 # Runtime-ID des Archivs (muss aktiviert sein)
    columns: # Zu projizierende Attributpfade, leer liest das gesamte Archiv
      - Energy
      - DataQuality
    wellKnownNames: # Einschränkung auf Quell-Entitäten mit diesen Well-Known Names
      - METER-4711
    wellKnownNamesPath: $.meters # Alternativ: Well-Known Names aus dem Payload lesen
    rtIds: # Einschränkung auf diese Quell-Entitäten
      - 68a2b1c4de73e7b175575402
    rtIdsPath: $.rtIds # Alternativ: Runtime-IDs aus dem Payload lesen
    fieldFilters: # Zusätzliche Filter, mit UND verknüpft
      - attributePath: DataQuality
        operator: GreaterEqualsThan
        comparisonValue: 90
    sortOrders: # Sortierung, mit den Spaltennamen des Ergebnisses
      - attributeName: Timestamp
        sortOrder: Ascending
    skip: 0 # Anzahl der zu überspringenden Zeilen
    take: 100 # Anzahl der zu lesenden Zeilen
    from: 2026-07-01T00:00:00 # Beginn des Zeitraums (UTC)
    fromPath: $.from # Alternativ: Beginn des Zeitraums aus dem Payload lesen
    to: 2026-08-01T00:00:00 # Ende des Zeitraums (UTC)
    toPath: $.to # Alternativ: Ende des Zeitraums aus dem Payload lesen
    limit: 10000 # Obergrenze der gelesenen Zeilen, unabhängig von skip/take
    limitPath: $.limit # Alternativ: Obergrenze aus dem Payload lesen
    targetPath: $.data # Pfad, unter dem die Zeilen im Payload abgelegt werden

Parameter​

ParameterTypErforderlichBeschreibung
archiveRtIdstringJaRuntime-ID des Archivs, aus dem gelesen wird. Das Archiv muss aktiviert sein
columnsArray von stringNeinZu projizierende Attributpfade (z. B. Energy, Amount.Value) oder der Name einer Formelspalte. Leer liest das gesamte Archiv
wellKnownNamesArray von stringNeinSchränkt das Ergebnis auf Quell-Entitäten mit diesen Well-Known Names ein
wellKnownNamesPathstringNeinJSONPath-Alternative zu wellKnownNames; akzeptiert einen Einzelwert, ein Array oder einen Multi-Match-Pfad
rtIdsArray von stringNeinSchränkt das Ergebnis auf diese Quell-Entitäten ein
rtIdsPathstringNeinJSONPath-Alternative zu rtIds
fieldFiltersArray von FieldFilterWithPathDtoNeinZusätzliche Filter auf projizierte oder Standardspalten, mit UND verknüpft
sortOrdersArray von SortOrderDtoNeinSortierung der zurückgegebenen Zeilen
skipintegerNeinAnzahl der zu überspringenden Zeilen (Paginierung)
takeintegerNeinAnzahl der zu lesenden Zeilen (Paginierung)
fromDatum/ZeitNeinBeginn des Zeitraums (UTC). Ohne Wert bleibt der Zeitraum am Anfang offen
fromPathstringNeinJSONPath zum Beginn des Zeitraums im Payload
toDatum/ZeitNeinEnde des Zeitraums (UTC). Ohne Wert bleibt der Zeitraum am Ende offen
toPathstringNeinJSONPath zum Ende des Zeitraums im Payload
limitintegerNeinObergrenze der gelesenen Zeilen, muss größer als null sein. Unabhängig von skip / take
limitPathstringNeinJSONPath zur Obergrenze im Payload
gapsTargetPathstringNeinPfad, unter dem der Abdeckungsbericht abgelegt wird. Setzen aktiviert die Lückenerkennung
expectedIntervalZeitspanneNeinIntervall, in dem die Lücken gezählt werden, z. B. PT15M. Standard ist die am Archiv deklarierte Periode
gapsOnlybooleanNeinNur die Lücken melden und die Daten selbst nicht lesen. Erfordert gapsTargetPath
maxGapScanRowsintegerNeinObergrenze der Zeilen für den Abdeckungs-Scan (Standard 200000), muss größer als null sein

Die verfügbaren Filteroperatoren und Sortierrichtungen sind bei GetRtEntitiesByType@1 beschrieben.

Vorrang und Zeitzone​

Je Wert gewinnt das Literal gegenüber seiner JSONPath-Variante: from vor fromPath, to vor toPath, limit vor limitPath, wellKnownNames vor wellKnownNamesPath und rtIds vor rtIdsPath.

hinweis

Zeitstempel werden als UTC gelesen. Ein Wert ohne Zeitzonen-Offset (2026-07-01T00:00:00) wird als UTC interpretiert, nicht als Lokalzeit des Adapter-Hosts. Der abgefragte Zeitraum verschiebt sich damit nie mit der Zeitzone des Servers.

Ein Pfad, der ins Leere zeigt, lässt den Wert ungesetzt und erzeugt eine Warnung. Ein vorhandener, aber nicht datumsartiger Wert (bzw. kein ganzzahliger Wert bei limitPath) lässt den Node fehlschlagen, statt den Zeitraum still zu erweitern.

Ergebnisform​

Das Ergebnis beginnt mit einer Timestamp-Spalte, gefolgt von den projizierten Spalten. Bei einem Archiv mit Fenstern (TimeRange oder Rollup) werden nach Timestamp zusätzlich WindowStart und WindowEnd eingefügt — solche Archive haben keine eigene timestamp-Spalte, die Zeitachse ist das Fensterende.

Bleibt columns leer, werden alle Datenspalten des Archivs projiziert und davor eine WellKnownName-Spalte gestellt. Damit liefert schon die Minimalkonfiguration — nur ein archiveRtId — brauchbare Daten:

Timestamp | WindowStart | WindowEnd | WellKnownName | Energy | DataQuality

Formelspalten (Computed Columns) sind enthalten und werden über ihren Namen angesprochen, nicht über einen Attributpfad. Eine Spalte, deren Backfill noch nicht abgeschlossen ist, fehlt und erscheint, sobald der Backfill fertig ist.

Ist columns gesetzt, gilt die Liste unverändert — es wird kein WellKnownName ergänzt, und die Spalte lässt sich dort wie jede andere anfordern (rtWellKnownName). Ausnahme sind Zeitachse und Zeilenfenster: Timestamp, WindowStart und WindowEnd werden ohnehin für jede Zeile ausgegeben, eine Nennung in columns erzeugt deshalb keine zweite, identische Spalte.

Spaltennamen in sortOrders und fieldFilters​

Verwenden Sie die Namen so, wie sie im Ergebnis erscheinen: Timestamp, WindowStart / WindowEnd (nur bei Archiven mit Fenstern), WellKnownName oder jede vom Archiv deklarierte Spalte. Der Node übersetzt diese auf die physischen Speicherspalten.

Ein Name, der weder Ergebnisspalte noch Archivspalte ist, lässt den Node fehlschlagen; die Fehlermeldung nennt die gültigen Namen. Sortieren oder Filtern nach WindowStart auf einem Raw-Archiv wird aus demselben Grund abgelehnt — ein solches Archiv hat kein Zeilenfenster.

Lückenerkennung​

Ist gapsTargetPath gesetzt, prüft der Node zusätzlich, ob der abgefragte Zeitraum tatsächlich mit Daten abgedeckt ist, und schreibt einen Bericht dorthin:

transformations:
  - type: GetStreamData@1
    archiveRtId: 68a1f0c5de73e7b175575401
    from: 2026-07-01T00:00:00
    to:   2026-07-02T00:00:00
    expectedInterval: PT15M
    targetPath:     $.data
    gapsTargetPath: $.gaps

Gemeldet wird je Quell-Entität — eine fehlende Viertelstunde bei einem Zähler darf nicht dadurch verdeckt werden, dass ein anderer Zähler geliefert hat. Der Bericht sieht so aus:

from: 2026-07-01T00:00:00Z
to:   2026-07-02T00:00:00Z
interval: PT15M
seriesCount: 2
seriesWithGapsCount: 1
isComplete: false
series:
  - rtId: 68a2b1c4de73e7b175575402
    wellKnownName: METER-4711
    expectedIntervals: 96
    presentIntervals: 94
    missingIntervals: 2
    hasOverlaps: false
    isComplete: false
    gaps:
      - from: 2026-07-01T12:30:00Z
        to:   2026-07-01T13:00:00Z
        duration: PT30M
        durationSeconds: 1800
        missingIntervals: 2
  - rtId: 68a2b1c4de73e7b175575403
    wellKnownName: METER-4712
    expectedIntervals: 96
    presentIntervals: 96
    missingIntervals: 0
    hasOverlaps: false
    isComplete: true
    gaps: []

Zeitspannen werden sowohl als ISO-8601-Zeichenkette (duration) als auch in Sekunden (durationSeconds) ausgegeben — lesbar und in nachgelagerten Nodes rechenbar. Da der Bericht insgesamt ein isComplete trägt, kann ein nachfolgender If@1 anhand eines einzigen Feldes verzweigen.

Funktionsweise: Jedes gespeicherte Fenster im Zeitraum wird auf diesen Zeitraum beschnitten, überlappende und angrenzende Fenster werden verschmolzen, und was dabei nicht abgedeckt wird, ist eine Lücke. Dafür wird keine deklarierte Periode benötigt, und unterschiedlich lange Fenster sind unproblematisch. Ein bekanntes Intervall (expectedInterval, sonst die Periode des Archivs) ergänzt lediglich die Zählwerte; ohne Intervall werden die Lücken weiterhin als Zeitbereiche gemeldet und der Node warnt einmalig.

vorsicht

Drei Einschränkungen sind zu beachten:

  • Die Lückenerkennung setzt ein Archiv mit Fenstern voraus (TimeRange oder Rollup) sowie beide Zeitgrenzen. Ein Raw-Archiv speichert einzelne Zeitstempel und hat keine Intervallabdeckung, die sich beurteilen ließe — der Node lehnt ab, statt eine Antwort zu erfinden.
  • Der Scan führt eine eigene Abfrage aus, bewusst getrennt von der Datenabfrage, deren limit / skip / take Zeilen ausblenden und den Scan Lücken melden lassen würden, die es nicht gibt. maxGapScanRows (Standard 200000) begrenzt ihn; wird die Grenze überschritten, schlägt der Node fehl, statt aus einem abgeschnittenen Scan zu berichten. Zur Einordnung: ein Jahr Viertelstundenwerte sind rund 35.000 Zeilen je Entität.
  • Eine Entität, die überhaupt nichts geliefert hat, ist für einen Abdeckungs-Scan unsichtbar — sie hat schlicht keine Zeilen. Sind über rtIds oder wellKnownNames die erwarteten Entitäten benannt, wird jede Entität ohne Zeilen stattdessen als Lücke über den gesamten Zeitraum gemeldet; andernfalls bleibt die Einschränkung bestehen und der Node protokolliert sie.

Überlappende Fenster sind keine Lücken und lassen nichts fehlschlagen — das Speicherkonzept erlaubt sie —, werden aber je Serie als hasOverlaps ausgewiesen und einmalig als Warnung protokolliert, denn eine Summe über sie zählt den Überlappungsbereich doppelt.

Anwendungsbeispiel​

Die folgende Pipeline liest einen Tag Messwerte eines Zählers, prüft den Tag auf Vollständigkeit und rendert daraus eine Tabelle:

triggers:
  - type: FromHttpRequest@1
    path: /streamdata-report
    method: POST
transformations:
  - type: GetStreamData@1
    archiveRtId: 68a1f0c5de73e7b175575401
    columns:
      - Energy
      - DataQuality
    wellKnownNames:
      - METER-4711
    from: 2026-07-01T00:00:00
    to:   2026-07-02T00:00:00
    sortOrders:
      - attributeName: Timestamp
        sortOrder: Ascending
    expectedInterval: PT15M
    targetPath:     $.data
    gapsTargetPath: $.gaps
  - type: QueryResultToMarkdownTable@1
    path: $.data
    targetPath: $.table
tipp

Mit gapsOnly: true erhalten Sie eine günstige Vollständigkeitsprüfung vor einem teuren Schritt — der Node meldet dann die Lücken, ohne die Daten selbst zu lesen.

Anwendungsfälle​

  • Ad-hoc-Archivabfragen: Stream Data lesen, ohne zuvor eine persistierte Query-Entität anzulegen
  • Reporting: Messwerte eines Zeitraums sortiert und gefiltert für Tabelle oder Export abrufen
  • Datenqualitätsprüfung: Vor der Abrechnung sicherstellen, dass ein Abrechnungszeitraum vollständig vorliegt
  • Monitoring: Fehlende Lieferungen je Zähler oder Sensor erkennen und eine Folgeaktion auslösen
  • Backfill-Steuerung: Über gapsOnly ermitteln, welche Zeitbereiche noch nachimportiert werden müssen

Einschränkungen​

Downsampling und auflösungsabhängige Rollup-Auswahl sind nicht Teil dieses Nodes. Beides deckt GetQueryById@1 mit einer persistierten Downsampling-Query ab. GetStreamData@1 liest immer exakt das konfigurierte Archiv, die Werte hängen damit nie von einer im Hintergrund getroffenen Archivauswahl ab.

Siehe auch​