Downsampling Query

Eine Downsampling-Abfrage reduziert die Dichte von Zeitreihendaten, indem sie einen Zeitbereich in gleich große Buckets unterteilt und auf jeden Bucket eine Aggregationsfunktion anwendet. Dies ist für die Visualisierung großer Datensätze auf Dashboards und in Diagrammen unverzichtbar – anstatt Tausende von Rohdatenpunkten zu übertragen, erhalten Sie eine handhabbare Anzahl zusammengefasster Werte.

Zwei Wege zum Downsampling

Verwenden Sie diesen Abfragetyp, wenn Sie explizite Kontrolle wünschen – Sie wählen die Aggregation (AVG, MIN, MAX, …) für jede Spalte. Wenn Sie stattdessen lediglich eine Rohzeilen-Abfrage ausdünnen möchten, ohne Aggregationen auszuwählen, setzen Sie queryMode: DOWNSAMPLING auf einer Simple Query: Der Server wendet dann pro Spaltentyp einen Standard-Reducer an (numerisch → AVG+MIN+MAX-Envelope, andere → MAX) und gruppiert automatisch pro Quellentität.

Wie Downsampling funktioniert

Downsampling nutzt die DATE_BIN-Funktion von CrateDB, um den Zeitbereich in gleichmäßig verteilte Intervalle zu unterteilen. Für jedes Intervall wird die angegebene Aggregationsfunktion (AVG, MIN oder MAX) auf alle Datenpunkte innerhalb dieses Buckets angewendet.

Berechnung der Bucket-Größe:

bucket_interval = (to - from) / limit

Zum Beispiel erzeugt die Abfrage eines 24-Stunden-Bereichs mit limit: 24 24 Buckets von je 1 Stunde. Die Abfrage von 7 Tagen mit limit: 168 erzeugt 168 Buckets von je 1 Stunde.

Zeitbereich	Limit	Bucket-Größe
1 Stunde	60	1 Minute
24 Stunden	24	1 Stunde
24 Stunden	288	5 Minuten
7 Tage	168	1 Stunde
30 Tage	720	1 Stunde
30 Tage	30	1 Tag

---

Transiente Downsampling-Abfrage

Verwenden Sie das Feld transientStreamDataDownsamplingQuery. Anders als bei anderen Streamdaten-Abfragen sind die Parameter from, to und limit erforderlich – sie definieren den Zeitbereich und die Anzahl der zu erzeugenden Buckets.

Grundlegende Verwendung

query {
  streamData {
    transientStreamDataDownsamplingQuery(
      ckId: "Industry.Energy/EnergyMeter"
      columnPaths: [
        { attributePath: "voltage", aggregationType: AVG }
      ]
      from: "2024-03-21T00:00:00Z"
      to: "2024-03-22T00:00:00Z"
      limit: 24
    ) {
      totalCount
      items {
        timestamp
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Antwort:

{
  "data": {
    "streamData": {
      "transientStreamDataDownsamplingQuery": {
        "totalCount": 24,
        "items": [
          {
            "timestamp": "2024-03-21T00:00:00.000Z",
            "cells": {
              "items": [
                { "attributePath": "Avg_voltage", "value": 229.8 }
              ]
            }
          },
          {
            "timestamp": "2024-03-21T01:00:00.000Z",
            "cells": {
              "items": [
                { "attributePath": "Avg_voltage", "value": 230.1 }
              ]
            }
          },
          {
            "timestamp": "2024-03-21T02:00:00.000Z",
            "cells": {
              "items": [
                { "attributePath": "Avg_voltage", "value": 228.5 }
              ]
            }
          }
        ]
      }
    }
  }
}

Jede Ergebniszeile repräsentiert einen Zeit-Bucket. Der timestamp ist der Beginn des Bucket-Intervalls, und die Zellenwerte sind die aggregierten Werte für diesen Bucket.

Parameter

Parameter	Typ	Erforderlich	Beschreibung
ckId	String!	Ja	Der abzufragende CK type
columnPaths	[StreamDataQueryColumnInput!]!	Ja	Spalten mit Aggregationstyp (AVG, MIN, MAX)
from	DateTime!	Ja	Beginn des Zeitbereichs
to	DateTime!	Ja	Ende des Zeitbereichs
limit	Int!	Ja	Anzahl der zu erzeugenden Zeit-Buckets
fieldFilter	[FieldFilter]	Nein	Vergleichsfilter auf Feldebene
rtIds	[OctoObjectId]	Nein	Einschränkung auf bestimmte Runtime-Entity-IDs
first	Int	Nein	Maximale Anzahl der zurückzugebenden Elemente (Paginierung)
after	String	Nein	Paginierungs-Cursor

Beachten Sie, dass from, to und limit als direkte Parameter der Downsampling-Abfrage übergeben werden – nicht innerhalb von StreamDataArguments. Dies unterscheidet sich von anderen Streamdaten-Abfragetypen.

---

Mehrere Spalten

Sie können mehrere Attribute in einer einzigen Abfrage downsampeln, jedes mit seiner eigenen Aggregationsfunktion:

query {
  streamData {
    transientStreamDataDownsamplingQuery(
      ckId: "Industry.Energy/EnergyMeter"
      columnPaths: [
        { attributePath: "voltage", aggregationType: AVG },
        { attributePath: "voltage", aggregationType: MIN },
        { attributePath: "voltage", aggregationType: MAX },
        { attributePath: "power", aggregationType: AVG }
      ]
      from: "2024-03-21T00:00:00Z"
      to: "2024-03-22T00:00:00Z"
      limit: 48
    ) {
      items {
        timestamp
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Antwort (ein Bucket):

{
  "timestamp": "2024-03-21T00:00:00.000Z",
  "cells": {
    "items": [
      { "attributePath": "Avg_voltage", "value": 229.8 },
      { "attributePath": "Min_voltage", "value": 225.3 },
      { "attributePath": "Max_voltage", "value": 234.1 },
      { "attributePath": "Avg_power", "value": 1420.5 }
    ]
  }
}

Dies ist nützlich für Diagrammvisualisierungen, die ein Band (Min-/Max-Bereich) mit einer Durchschnittslinie zeigen.

---

Einschränkung auf bestimmte Entitäten

Verwenden Sie rtIds, um Daten nur für bestimmte Runtime-Entitäten zu downsampeln:

query {
  streamData {
    transientStreamDataDownsamplingQuery(
      ckId: "Industry.Energy/EnergyMeter"
      columnPaths: [
        { attributePath: "voltage", aggregationType: AVG }
      ]
      from: "2024-03-14T00:00:00Z"
      to: "2024-03-21T00:00:00Z"
      limit: 168
      rtIds: ["65dc6d24cc529cdc46c84fcc"]
    ) {
      totalCount
      items {
        timestamp
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

---

Anwendungsfälle

Szenario	from/to	limit	Bucket-Größe	Zweck
Echtzeit-Dashboard (letzte Stunde)	1-Stunden-Fenster	60	1 Minute	Live-Monitoring mit 1-Minuten-Auflösung
Tagesübersichtsdiagramm	24 Stunden	288	5 Minuten	Detaillierte Tagestrend-Analyse
Wochentrend-Bericht	7 Tage	168	1 Stunde	Stündliche Trends über eine Woche
Monatszusammenfassung	30 Tage	30	1 Tag	Tagesaggregate für die Monatsansicht
Jahresübersicht	365 Tage	365	1 Tag	Langfristige Trendvisualisierung

Das richtige Limit wählen

• Dashboard-Diagramme: Passen Sie das limit an die Pixelbreite Ihrer Diagrammfläche an. Ein Diagramm, das 600 Pixel breit ist, benötigt höchstens 600 Datenpunkte.
• Berichte: Wählen Sie ein limit, das für den Zeitbereich sinnvolle Intervalle ergibt (z. B. stündlich für Tagesberichte, täglich für Monatsberichte).
• Performance: Downsampling reduziert die Datenübertragung erheblich. Ein Sensor, der jede Sekunde aufzeichnet, erzeugt 86.400 Punkte pro Tag – ein Downsampling auf 288 Punkte (5-Minuten-Intervalle) reduziert das Payload um 99,7 %.