Simple Query

Eine Simple Query ruft rohe Zeitreihenzeilen aus CrateDB ab. Sie wählen aus, welche Spalten zurückgegeben werden, und können Filter, Sortierung und Zeitraumeinschränkungen anwenden. Dies ist der grundlegendste Streamdaten-Abfragetyp – verwenden Sie ihn, wenn Sie einzelne Datenpunkte statt aggregierter Zusammenfassungen benötigen.

Transiente Simple Query

Eine transiente Abfrage erlaubt es Ihnen, Abfrageparameter direkt in der Anfrage anzugeben, ohne zuvor eine Abfragedefinition zu speichern. Verwenden Sie das Feld transientStreamDataQuery unter streamData.

Grundlegende Verwendung

query {
  streamData {
    transientStreamDataQuery(
      ckId: "Industry.Energy/EnergyMeter"
      columnPaths: ["voltage", "power"]
    ) {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
      items {
        rtId
        ckTypeId
        timestamp
        rtWellKnownName
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Antwort:

{
  "data": {
    "streamData": {
      "transientStreamDataQuery": {
        "totalCount": 4826,
        "pageInfo": {
          "hasNextPage": true,
          "endCursor": "YXJyYXljb25uZWN0aW9uOjI0"
        },
        "items": [
          {
            "rtId": "65dc6d24cc529cdc46c84fcc",
            "ckTypeId": "Industry.Energy/EnergyMeter",
            "timestamp": "2024-03-21T16:22:47.676Z",
            "rtWellKnownName": "EnergyMeter-001",
            "cells": {
              "items": [
                { "attributePath": "voltage", "value": 230.5 },
                { "attributePath": "power", "value": 1450.2 }
              ]
            }
          },
          {
            "rtId": "65dc6d24cc529cdc46c84fcc",
            "ckTypeId": "Industry.Energy/EnergyMeter",
            "timestamp": "2024-03-21T16:23:50.675Z",
            "rtWellKnownName": "EnergyMeter-001",
            "cells": {
              "items": [
                { "attributePath": "voltage", "value": 231.1 },
                { "attributePath": "power", "value": 1465.8 }
              ]
            }
          }
        ]
      }
    }
  }
}

Jede Ergebniszeile enthält die Systemfelder (rtId, ckTypeId, timestamp, rtWellKnownName) und eine cells-Connection mit den angeforderten Spaltenwerten.

Parameter

Parameter	Typ	Erforderlich	Beschreibung
ckId	`String!`	Ja	Der abzufragende CK-Typ (z. B. `"Industry.Energy/EnergyMeter"`)
columnPaths	`[String!]!`	Ja	Namen der zurückzugebenden Data-Stream-Attribute (z. B. `["voltage", "power"]`)
arg	`StreamDataArguments`	Nein	Overrides für Zeitraum und Limit
fieldFilter	`[FieldFilter]`	Nein	Feldbezogene Vergleichsfilter
sortOrder	`[Sort]`	Nein	Sortierspezifikation
rtIds	`[OctoObjectId]`	Nein	Ergebnisse auf bestimmte Runtime-Entitäts-IDs eingrenzen
first	`Int`	Nein	Maximale Anzahl der zurückzugebenden Elemente (Paginierung)
after	`String`	Nein	Cursor für die Paginierung (aus `pageInfo.endCursor`)

Column Paths

Der Parameter columnPaths gibt an, welche Data-Stream-Attribute in das Ergebnis aufgenommen werden. Verwenden Sie die im CK-Typ definierten Attributnamen.

# Single column
transientStreamDataQuery(
  ckId: "Industry.Energy/EnergyMeter"
  columnPaths: ["voltage"]
)

# Multiple columns
transientStreamDataQuery(
  ckId: "Industry.Energy/EnergyMeter"
  columnPaths: ["voltage", "power", "current", "frequency"]
)

Die Systemfelder rtId, ckTypeId, timestamp und rtWellKnownName werden unabhängig von den angegebenen Column Paths immer eingeschlossen.

Filterung

Verwenden Sie fieldFilter, um Ergebnisse anhand von Attributwerten einzuschränken. Jeder Filter gibt einen Attributpfad, einen Operator und einen Vergleichswert an.

Nach Attributwert filtern

query {
  streamData {
    transientStreamDataQuery(
      ckId: "Industry.Energy/EnergyMeter"
      columnPaths: ["voltage", "power"]
      fieldFilter: [
        {
          attributePath: "voltage"
          operator: GREATER_THAN
          comparisonValue: 220
        }
      ]
    ) {
      totalCount
      items {
        timestamp
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Mehrere Filter

Mehrere Filter werden mit UND-Logik kombiniert:

fieldFilter: [
  {
    attributePath: "voltage"
    operator: GREATER_EQUAL_THAN
    comparisonValue: 220
  },
  {
    attributePath: "voltage"
    operator: LESS_EQUAL_THAN
    comparisonValue: 240
  }
]

Verfügbare Filteroperatoren

Operator	Beschreibung
`EQUALS`	Exakte Übereinstimmung
`NOT_EQUALS`	Ungleich
`GREATER_THAN`	Größer als
`GREATER_EQUAL_THAN`	Größer oder gleich
`LESS_THAN`	Kleiner als
`LESS_EQUAL_THAN`	Kleiner oder gleich
`LIKE`	Mustervergleich (`%` als Platzhalter verwenden)
`MATCH_REG_EX`	Übereinstimmung mit regulärem Ausdruck
`IN`	Wert in Liste
`NOT_IN`	Wert nicht in Liste
`ANY_EQ`	Ein Element ist gleich (für Array-Felder)
`ANY_LIKE`	Ein Element passt zum Muster (für Array-Felder)

Zeitraumfilterung

Verwenden Sie StreamDataArguments, um Ergebnisse auf ein bestimmtes Zeitfenster einzuschränken:

query {
  streamData {
    transientStreamDataQuery(
      ckId: "Industry.Energy/EnergyMeter"
      columnPaths: ["voltage"]
      arg: {
        queryMode: DEFAULT
        from: "2024-03-21T00:00:00Z"
        to: "2024-03-22T00:00:00Z"
        limit: 1000
      }
    ) {
      totalCount
      items {
        timestamp
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Feld	Beschreibung
from	Beginn des Zeitraums (inklusive)
to	Ende des Zeitraums (inklusive)
limit	Maximale Anzahl der von CrateDB zurückzugebenden Datenpunkte
queryMode	`DEFAULT` liefert rohe Zeilen. `DOWNSAMPLING` reduziert das Ergebnis auf `limit` Zeit-Buckets – siehe Downsampling einer Simple Query unten.

Das limit in StreamDataArguments steuert, wie viele Zeilen CrateDB zurückgibt, bevor die Paginierung angewendet wird. Der Parameter first auf dem Abfragefeld steuert, wie viele Elemente pro Seite zurückgegeben werden.

Downsampling einer Simple Query

Das Setzen von queryMode: DOWNSAMPLING (zusammen mit from, to und limit) verwandelt eine Simple Query in ein serverseitiges Downsample: Statt jede rohe Zeile zurückzugeben, wird das Ergebnis auf genau limit gleich breite Zeit-Buckets reduziert – ideal für Diagramme, die nur Platz für einige hundert Punkte haben.

Anders als bei der dedizierten Downsampling Query – bei der Sie eine Aggregation pro Spalte wählen – lässt eine Simple Query im Downsampling-Modus den Server für jede angeforderte Spalte einen sinnvollen Standard-Reducer wählen, basierend auf ihrem Werttyp:

Werttyp der Spalte	Angewendete(r) Reducer
Numerisch (integer, double)	`AVG` + `MIN` + `MAX` – das Min/Max-Paar bildet eine Hüllkurve, die Spitzen bewahrt, die der Durchschnitt glätten würde
String / enum / boolean / timestamp	`MAX` – ein stabiler repräsentativer Wert pro Bucket
Records, Arrays, Binärdaten	übersprungen (nicht auf einen darstellbaren Wert reduzierbar)

Die Ergebnisse werden zusätzlich nach der Quell-Runtime-Entität (rtId) gruppiert, sodass ineinander verschachtelte Serien getrennt bleiben – Sie erhalten limit Buckets pro Serie statt einer zusammengeführten Serie.

query {
  streamData {
    transientStreamDataQuery(
      ckId: "Industry.Energy/EnergyMeter"
      columnPaths: ["voltage", "power"]
      arg: {
        queryMode: DOWNSAMPLING
        from: "2024-03-21T00:00:00Z"
        to: "2024-03-22T00:00:00Z"
        limit: 300
      }
    ) {
      totalCount
      items {
        rtId
        timestamp
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Jede Ergebniszeile ist ein Bucket pro Serie. Die reduzierten Zellen tragen einen Funktionssuffix: Die numerische Hüllkurve kommt als voltage_avg, voltage_min und voltage_max zurück; nicht-numerische Spalten als <column>_max. Die Startzeit des Buckets steht im timestamp der Zeile. Leere Buckets (keine Daten in diesem Intervall) werden mit null-Zellwerten zurückgegeben, sodass Clients Lücken darstellen können, anstatt zu interpolieren.

hinweis

from, to und limit sind für das Downsampling alle erforderlich – ohne alle drei fällt die Abfrage darauf zurück, rohe Zeilen zurückzugeben. Verwenden Sie stattdessen die Downsampling Query, wenn Sie explizite Kontrolle darüber benötigen, welche Aggregation auf welche Spalte angewendet wird.

Sortierung

Verwenden Sie sortOrder, um die Reihenfolge der Ergebnisse zu steuern:

query {
  streamData {
    transientStreamDataQuery(
      ckId: "Industry.Energy/EnergyMeter"
      columnPaths: ["voltage"]
      sortOrder: [
        { attributePath: "timestamp", sortOrder: DESCENDING }
      ]
    ) {
      items {
        timestamp
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Dies gibt die neuesten Datenpunkte zuerst zurück. Sie können nach jeder Spalte in der Ergebnismenge sortieren.

Auf bestimmte Entitäten eingrenzen

Verwenden Sie rtIds, um Ergebnisse auf Daten bestimmter Runtime-Entitäten zu beschränken:

query {
  streamData {
    transientStreamDataQuery(
      ckId: "Industry.Energy/EnergyMeter"
      columnPaths: ["voltage", "power"]
      rtIds: [
        "65dc6d24cc529cdc46c84fcc",
        "65dc6d24cc529cdc46c84fcd"
      ]
    ) {
      totalCount
      items {
        rtId
        rtWellKnownName
        timestamp
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Dies gibt Streamdaten nur für die beiden angegebenen Energiezähler zurück.

Paginierung

Alle Streamdaten-Abfragen verwenden cursorbasierte Paginierung. Verwenden Sie first, um die Seitengröße festzulegen, und after, um nachfolgende Seiten abzurufen.

Erste Seite

query {
  streamData {
    transientStreamDataQuery(
      ckId: "Industry.Energy/EnergyMeter"
      columnPaths: ["voltage"]
      first: 50
    ) {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
      items {
        timestamp
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Nächste Seite

Verwenden Sie den Wert endCursor aus der vorherigen Antwort als Parameter after:

query {
  streamData {
    transientStreamDataQuery(
      ckId: "Industry.Energy/EnergyMeter"
      columnPaths: ["voltage"]
      first: 50
      after: "YXJyYXljb25uZWN0aW9uOjQ5"
    ) {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
      items {
        timestamp
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Fahren Sie mit dem Abrufen von Seiten fort, bis hasNextPage false ist.

Parameter kombinieren

Alle Parameter lassen sich kombinieren. Dieses Beispiel fragt die letzten 24 Stunden an Spannungsdaten für einen bestimmten Energiezähler ab, gefiltert auf Werte über 220 V, sortiert nach Zeitstempel absteigend, mit Paginierung:

query {
  streamData {
    transientStreamDataQuery(
      ckId: "Industry.Energy/EnergyMeter"
      columnPaths: ["voltage", "power"]
      arg: {
        queryMode: DEFAULT
        from: "2024-03-20T16:00:00Z"
        to: "2024-03-21T16:00:00Z"
        limit: 5000
      }
      rtIds: ["65dc6d24cc529cdc46c84fcc"]
      fieldFilter: [
        { attributePath: "voltage", operator: GREATER_THAN, comparisonValue: 220 }
      ]
      sortOrder: [
        { attributePath: "timestamp", sortOrder: DESCENDING }
      ]
      first: 100
    ) {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
      items {
        rtId
        rtWellKnownName
        timestamp
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Typed vs. Transient

Für einen Vergleich der typisierten und transienten Abfrageansätze siehe den Streamdaten-Zugriff – Überblick. Zusammengefasst:

	Typed	Transient
Spaltenauswahl	Alle Attribute des Typs	Expliziter Parameter `columnPaths`
Ergebnisformat	Benannte Felder (z. B. `voltage`)	`cells` mit `attributePath`/`value`-Paaren
Typsicherheit	GraphQL-Schema-Validierung	Laufzeitvalidierung
Anwendungsfall	Bekannter Typ, alle Attribute benötigt	Dynamische Spaltenauswahl, Ad-hoc-Analyse

Transiente Simple Query​

Grundlegende Verwendung​

Parameter​

Column Paths​

Filterung​

Nach Attributwert filtern​

Mehrere Filter​

Verfügbare Filteroperatoren​

Zeitraumfilterung​

Downsampling einer Simple Query​

Sortierung​

Auf bestimmte Entitäten eingrenzen​

Paginierung​

Erste Seite​

Nächste Seite​

Parameter kombinieren​

Typed vs. Transient​