Zeitreihendaten

Yggio speichert numerische und String-Daten in einer Zeitreihendatenbank.

Über die REST-API können Sie Zeitreihendaten eines bestimmten Attributs von einem Iotnode abrufen.

Das Folgende ist das Format von Zeitreihendaten für ein Attribut eines Iotnodes:

[
  {
    "time": String,
    "value": Number || String
  },
  ...
]

time ist ein ISO-8601-Zeitstempel. Z. B.: 2019-08-07T12:30:00.00Z.
value ist der gespeicherte Wert.

Zeitintervall festlegen

Sie können die Daten mit einem festgelegten Zeitabstand zwischen den einzelnen Datenpunkten abrufen. Dies kann sinnvoll sein, wenn keine hohe Datenauflösung benötigt wird. Es kann die Ladezeiten und die Leistung verbessern. Die Datenbank verwendet dann Interpolation, um die Werte für die Datenpunkte festzulegen.

Wenn ein festgelegtes Zeitintervall verwendet wird, haben die Daten folgendes Format:

[
  {
    "time": String,
    "value": Number,
    "min": Number,
    "max": Number,
    "stddev": Number
  },
  ...
]

time ist ein ISO-8601-Zeitstempel. Z. B.: 2019-08-07T12:30:00.00Z.
value ist der interpolierte Wert.
min ist der Wert des kleinsten Punkts im interpolierten Bereich.
max ist der Wert des größten Punkts im interpolierten Bereich.
stddev ist die Standardabweichung der Punkte im Interpolationsbereich.

Daten mit valueFunction downsamplen

Die Funktion valueFunction ermöglicht es Ihnen, Operationen auf Daten auszuführen, die innerhalb bestimmter Zeitfenster gruppiert sind. Dies kann nützlich sein, um Datentrends über die Zeit zu analysieren, indem die Datenpunkte innerhalb jedes Fensters zusammengefasst werden.

Unterstützte Operationen

Die folgenden Operationen können mit valueFunction durchgeführt werden:

• mean: Berechnet den Durchschnitt aller Werte innerhalb des Fensters.
• timeWeightedMean: Berechnet den zeitgewichteten Durchschnitt innerhalb des Fensters.
• max: Findet den maximalen Wert innerhalb des Fensters.
• min: Findet den minimalen Wert innerhalb des Fensters.
• first: Verwendet den ersten Wert innerhalb des Fensters.
• last: Verwendet den letzten Wert innerhalb des Fensters.
• sum: Berechnet die Summe aller Werte innerhalb des Fensters.
• count: Zählt die Anzahl der Werte innerhalb des Fensters.
• difference: Berechnet die Differenz zwischen dem ersten Wert aufeinanderfolgender Fenster

Definieren des Zeitfensters

Das Zeitfenster für valueFunction wird durch die Option distance bestimmt. Diese gibt die Länge jedes Fensters in Sekunden an.

Zeitgewichtete Durchschnittsfunktion

Der zeitgewichtete Durchschnitt wird berechnet, indem ermittelt wird, wie lange eine Messung innerhalb eines bestimmten Zeitintervalls in einem bestimmten Zustand verblieben ist.

Beispiel: Ein Sensor misst die Belegung eines Schreibtisches:

[
    {time: "2025-03-18T13:00:00.000Z", value: 0},
    {time: "2025-03-18T13:30:00.000Z", value: 1},
    {time: "2025-03-18T13:45:00.000Z", value: 0},
    {time: "2025-03-18T14.15:00.000Z", value: 1},
    {time: "2025-03-18T14.30:00.000Z", value: 1},
    {time: "2025-03-18T14.45:00.000Z", value: 0},
    {time: "2025-03-18T15.00:00.000Z", value: 1},
    {time: "2025-03-18T15.45:00.000Z", value: 0},
]

Die folgende Anfrage berechnet die zeitgewichtete durchschnittliche Belegung für jede Stunde:

$ curl -X 'GET' \
  'https://staging.yggio.net/api/iotnodes/<iotnode._id>/stats?measurement=occupancy&distance=3600&valueFunction=timeWeightedMean' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Die Antwort:

 [
     {"time": "13.00", "value": 0.25}
     {"time": "14.00", "value": 0.5}
     {"time": "15.00", "value": 0.75}
 ]

Erklärung:

• Stunde 1 (13:00–14:00): Es wurden drei Beobachtungen aufgezeichnet. Der Schreibtisch war 45 Minuten unbelegt (Wert 0) und 15 Minuten belegt (Wert 1). Der zeitgewichtete Durchschnitt ist 0,25.
• Stunde 2 (14:00–15:00): Es wurden drei Beobachtungen aufgezeichnet. Die ersten 15 Minuten verwendeten den Zustand der vorherigen Stunde (0), gefolgt von zwei Messungen mit Wert 1. Dies ergibt 30 Minuten mit Wert 0 und 30 Minuten mit Wert 1, was einen Durchschnitt von 0,5 ergibt.
• Stunde 3 (15:00–16:00): Es wurden zwei Beobachtungen aufgezeichnet. Der Schreibtisch war 45 Minuten belegt (Wert 1) und 15 Minuten unbelegt (Wert 0), was einen Durchschnitt von 0,75 ergibt.

Hinweis:

Wenn die erste Beobachtung nach dem Beginn des ersten Intervalls erfolgt, ist das Ergebnis für dieses Intervall null. Das liegt daran, dass wir den Wert vor der ersten Beobachtung nicht kennen und daher den Zustand für das gesamte Intervall nicht bestimmen können.

Beispiel:

Wenn das erste Intervall um 13:00 Uhr beginnt, die erste Beobachtung jedoch um 13:15 Uhr erfolgt, fehlen uns Informationen über den Zustand zwischen 13:00 und 13:15 Uhr. Da der Zustand vor 13:00 Uhr unbekannt ist, kann das System keinen Wert annehmen oder extrapolieren, was zu null für dieses erste Intervall führt. Alle folgenden Intervalle sind davon nicht betroffen, da sie sich auf zuvor bekannte Werte stützen.

Antwortformat

Bei Verwendung der Funktion valueFunction hat die Antwort folgendes JSON-Format:

[
  {
    "time": String,
    "value": Number
  },
  ...
]

time: Ein ISO-8601-Zeitstempel (z. B. 2019-08-07T12:30:00.00Z), der den Beginn des Zeitfensters angibt.
value: Das Ergebnis der angegebenen valueFunction-Operation für das Zeitfenster.

Umgang mit leeren Fenstern

Wenn innerhalb eines bestimmten Zeitfensters keine Datenpunkte vorhanden sind, wird dieses Fenster in der Antwort übersprungen.

Beispiel

Hier ist ein Beispiel für eine Antwort auf eine API-Anfrage mit valueFunction=mean und distance=3600 (1 Stunde):

[
  {
    "time": "2019-08-07T12:00:00.00Z",
    "value": 23.5
  },
  {
    "time": "2019-08-07T13:00:00.00Z",
    "value": 19.8
  },
  ...
]

In diesem Beispiel ist der value bei jedem Zeitstempel der Durchschnitt aller Werte innerhalb des entsprechenden Ein-Stunden-Fensters.

Aufbewahrungsrichtlinie (Retention Policy)

Eine optionale Aufbewahrungsrichtlinie kann auf einem Iotnode festgelegt werden; sie ermöglicht das automatische Entfernen von Zeitreihendaten nach einer bestimmten Zeitspanne. Die Aufbewahrungsrichtlinie eines Nodes wird durch das Feld retentionPolicy am Node bestimmt und ist standardmäßig auf keine Aufbewahrungsrichtlinie gesetzt, wenn nicht angegeben. Hinweis: Das Ändern der Aufbewahrungsrichtlinie an einem bestehenden Iotnode wird nicht empfohlen, da dadurch die vorhandenen Zeitreihendaten unzugänglich werden

Optionen für die Aufbewahrungsrichtlinie

• retentionForever
• retention2days
• retention30days
• retention183days
• retention365days
• retention730days
• retention1826days

Effektive Aufbewahrung

Messwerte werden in Buckets gespeichert, die jeweils eine Zeitspanne abdecken, und ein Bucket wird erst entfernt, wenn jeder Messwert darin abgelaufen ist. Ein Messwert bleibt daher bis zum Ende der Spanne seines Buckets erhalten, das heißt Daten können die nominale Aufbewahrungsfrist um bis zu diese Spanne überdauern:

Policy	Nominale Aufbewahrung	Bucket-Spanne	Effektive Aufbewahrung
retention2days	2 Tage	6 Stunden	bis zu 2 Tage 6 Stunden
retention30days	30 Tage	1 Tag	bis zu 31 Tage
retention183days	183 Tage	7 Tage	bis zu 190 Tage
retention365days	365 Tage	7 Tage	bis zu 372 Tage
retention730days	730 Tage	7 Tage	bis zu 737 Tage
retention1826days	1826 Tage	7 Tage	bis zu 1833 Tage
retentionForever	keine Entfernung	7 Tage	keine Entfernung

Betrachten Sie die nominale Frist als den frühesten Zeitpunkt, zu dem ein Messwert entfernt werden kann, nicht als den spätesten. Daten werden nie vorzeitig entfernt.