Daten-Backend
IronFlock stellt für jedes Projekt eine private Datenbank bereit, basierend auf TimescaleDB. Ihre App definiert das Datenschema; IronFlock erstellt die Tabellen und beginnt mit der Datenerfassung, sobald ein Gerät zur App hinzugefügt wird.
Funktionsweise
- Definieren Sie Ihr Datenschema in
.ironflock/data-template.yml. - Verwenden Sie das IronFlock SDK, um Daten aus Ihrem Edge-Code zu veröffentlichen.
- IronFlock richtet die Datenbanktabellen automatisch in jedem Projekt ein, in dem die App installiert ist.
- Daten fließen von den Geräten über das Messaging-System in die Projektdatenbank.
Jedes Projekt erhält seine eigene physische Datenbank — es gibt keinen Datenaustausch zwischen Projekten.
Der Benutzer hat die volle Kontrolle über die von Ihrer App in seinem Projekt erfassten Daten. Als Entwickler haben Sie keinen Zugriff auf diese Daten.
Datenschema definieren
Erstellen Sie eine data-template.yml-Datei im .ironflock/-Verzeichnis:
data:
tables:
- tablename: sensordata
columns:
- id: tsp
name: Timestamp
description: Timestamp of measurement
path: args[0].timestamp
dataType: timestamp
- id: temperature
name: Temperature
description: Temperature reading in Celsius
path: args[0].temperature
dataType: numeric
- id: humidity
name: Humidity
description: Relative humidity percentage
path: args[0].humidity
dataType: numeric
- id: device_id
name: Device ID
description: Source device identifier
path: args[0].device_id
dataType: stringSpaltenoptionen
| Feld | Beschreibung |
|---|---|
id | Interner Spaltenbezeichner (verwenden Sie tsp für Zeitstempel-Spalten) |
name | Benutzerfreundlicher Spaltenname, der in Boards angezeigt wird |
description | Optionale Beschreibung |
path | Pfad zum Wert im veröffentlichten Datenobjekt (z. B. args[0].temperature) |
dataType | Einer von: timestamp, numeric, string, boolean |
secret | Diese Spalte verschlüsselt speichern und bei einem normalen Lesezugriff nie im Klartext zurückgeben — siehe Geheime Spalten weiter unten |
Geheime Spalten
Manche Werte müssen gespeichert werden, dürfen aber niemals angezeigt werden: ein API-Token, ein Gerätepasswort, ein Lizenzschlüssel. Markieren Sie die Spalte mit secret: true, und das Daten-Backend verschlüsselt sie beim Einfügen:
- tablename: credentials
columns:
- id: tsp
dataType: timestamp
- id: device_id
dataType: string
- id: api_token
dataType: string
secret: trueVon da an gibt kein gewöhnlicher Lesezugriff den Klartext zurück — nicht einmal an die App, die ihn geschrieben hat:
| Lesepfad | Was Sie zurückerhalten |
|---|---|
| Verlaufslesevorgänge und Echtzeit-Zeilen: was Boards, Widgets, das SDK und andere Apps erhalten, wenn sie die Tabelle lesen | den Platzhalter __secret__ |
| SQL (die SQL-Abfragekonsole, Datenexporte und der Postgres-Login FleetDB Access) und Datenbank-Backups | das gespeicherte Chiffrat, ifsec:1:… |
| Die Reveal-Funktion des SDK | den entschlüsselten Wert |
NULL bleibt überall NULL, sodass „gesetzt, aber verborgen“ von „nie geschrieben“ unterscheidbar bleibt.
Ein Geheimnis im Klartext zurückzulesen, ist ausschließlich aus den eigenen Containern der App heraus möglich, über das SDK — siehe Geheime Spalten in der SDK-Referenz. Boards und andere Apps können es überhaupt nicht erhalten, und genau das macht „wird nie im Klartext angezeigt“ wahr statt bloß kosmetisch.
Eine Zeile aktualisieren, ohne ihr Geheimnis zu verlieren. Auf einer Entitätstabelle kann ein Client, der eine Zeile bearbeitet, das echte Geheimnis nie zurücksenden — Lesezugriffe haben ihm immer nur den Platzhalter geliefert. Das Daten-Backend behandelt den Platzhalter __secret__ (und die Maske ••••••••, die Boards anzeigen) beim Schreiben daher als vorherigen Wert behalten, und eine ausgelassene geheime Spalte behält ihn ebenfalls. Ein explizites null löscht das Geheimnis. Die Beschreibung einer Maschine über ein Board-Formular zu bearbeiten, löscht daher niemals ihren Zugangscode.
Daraus folgen zwei Konsequenzen: Die Zeichenketten __secret__ und •••••••• können selbst nicht als geheime Werte gespeichert werden (und rohes ifsec:…-Chiffrat wird als Eingabe abgelehnt), und auf einer Tabelle ohne Entitätsschlüssel wird ein Platzhalter-Schreibzugriff abgelehnt — es gibt keine vorherige Zeile, die behalten werden könnte.
Drei Konsequenzen sollten Sie von vornherein einplanen, denn es sind harte Grenzen und keine Empfehlungen:
- Geheime Spalten sind ausschließlich Strings. Verschlüsselung erzeugt Text, daher können
numeric-,boolean- undtimestamp-Spalten nicht geheim sein. Auch die verpflichtende Spaltetspkann nicht geheim sein. - Sie können nicht nach einer geheimen Spalte filtern, gruppieren oder sortieren. Jede Zeile wird unter einem eigenen Zufallswert verschlüsselt, sodass zwei Zeilen mit demselben Geheimnis unterschiedliche Chiffrate speichern. Gleichheitsfilter,
GROUP BY,ORDER BYundDISTINCTüber eine geheime Spalte können schlicht nicht funktionieren. Um die Frage „stimmt dieser Wert überein?“ zu beantworten, verwenden Sie die Verify-Funktion des SDK, die innerhalb des Daten-Backends vergleicht, statt irgendetwas zurückzugeben. - Eine geheime Spalte kann kein Entitätsschlüssel sein. Da sich das Chiffrat jeder Zeile unterscheidet, würde das Lesen der neuesten Zeile pro Entität jede Zeile als eigene Entität behandeln — eine geheime Spalte in
maintainLatestFlagForzu nennen, wird daher rundweg abgelehnt.
Die letzten beiden Einschränkungen werden bei der Validierung Ihrer data-template.yml geprüft, sodass eine Tabelle, die sie verletzt, bereits beim Release fehlschlägt, statt sich später fehlerhaft zu verhalten.
Tabellenoptionen
Neben columns akzeptiert eine Tabelle einige optionale Schlüssel, die steuern, wie sie beschrieben wird und wie ihre Daten altern:
data:
tables:
- tablename: sensordata
description: Umgebungsmesswerte aus der Fertigung
chunkTimeInterval: 1 hour
dropAfter: 30 days
columns:
# ...| Feld | Beschreibung |
|---|---|
tablename | Name der Tabelle |
description | Optionale Beschreibung, wird in der UI angezeigt und von KI-Agenten zum Verständnis der Tabelle genutzt |
chunkTimeInterval | Größe der Zeitpartitionen, in die die Tabelle aufgeteilt wird. Standard: 7 days |
dropAfter | Aufbewahrungsfenster — Partitionen, die älter sind, werden automatisch verworfen |
downsample | Pflegt eine vor-aggregierte Kopie für schnelle Diagramme über lange Zeitfenster — siehe Kontinuierliches Downsampling weiter unten |
maintainLatestFlagFor | Spalten, die eine eindeutige Entität identifizieren — siehe Den aktuellen Zustand einer Entität verfolgen weiter unten |
private | Diese Tabelle vor anderen Apps verbergen — siehe Daten mit anderen Apps teilen weiter unten |
chunkTimeInterval bestimmt, wie die Zeitreihendaten auf der Festplatte partitioniert werden. Wählen Sie den Wert so, dass eine Partition ungefähr dem entspricht, was Sie in einer Abfrage lesen: Hochfrequente Daten, die im Sekundentakt erfasst werden, profitieren von kleinen Chunks (Minuten bis Stunden), langsam veränderliche Daten von großen (Wochen). Das ist lediglich die Voreinstellung der App — der Projektinhaber kann sie später in seinem eigenen Data Backend anpassen.
dropAfter macht aus der Tabelle ein gleitendes Zeitfenster. Ganze Partitionen, die älter als das angegebene Intervall sind, werden verworfen — das ist weit günstiger als das Löschen einzelner Zeilen. Der Aufräumjob läuft im Takt von dropAfter / 4, ein Datensatz kann sein Ablaufdatum also um bis zu ein Viertel des Intervalls überleben, bevor seine Partition entfernt wird. Lassen Sie dropAfter weg, um Daten unbegrenzt aufzubewahren.
Beide erwarten PostgreSQL-Intervall-Strings — 30 minutes, 1 hour, 7 days, 6 months.
Kontinuierliches Downsampling
Dashboards können die Datenbank bitten, Daten zu aggregieren — Stundendurchschnitte, Tagessummen, Anzahlen pro Maschine. Diese aus Rohdatensätzen zu berechnen, ist für einen Tag unproblematisch und für ein Jahr teuer. Ergänzen Sie eine Tabelle um downsample, und die Plattform pflegt eine kontinuierlich aktualisierte, vor-aggregierte Kopie davon und beantwortet Abfragen über lange Zeitfenster stattdessen aus dieser Kopie:
data:
tables:
- tablename: sensordata
dropAfter: 30 days
downsample:
bucket: 1 minute
keepFor: 2 years
paths:
- payload.temperature
columns:
# ...| Feld | Beschreibung |
|---|---|
bucket | Granularität der vor-aggregierten Kopie. Standard: 1 minute |
keepFor | Wie lange die heruntergerechnete Historie aufbewahrt wird. Weglassen, um sie unbegrenzt zu behalten |
paths | Einzubeziehende JSON-Feldpfade, in derselben Notation, die Dashboards verwenden |
bucket ist die feinste Auflösung, aus der ein Diagramm bedient werden kann — ein Diagramm, das deutlich feinere Intervalle anfordert, liest stattdessen die Rohtabelle. Zulässig sind feste Intervalle von 1 second bis 1 day, die einen Tag gleichmäßig teilen (1 minute, 5 minutes, 1 hour). Der Standardwert 1 minute passt praktisch für jedes Dashboard; ein gröberes Intervall kostet weniger Speicher und weniger Schreibdurchsatz.
keepFor ist das, was lange Historien überhaupt erst möglich macht. Rohdatensätze verschwinden mit dropAfter, doch die heruntergerechnete Kopie hat ihre eigene Aufbewahrung: Behalten Sie Rohdaten 30 Tage und heruntergerechnete Daten 2 Jahre, und ein Board kann weiterhin zwei Jahre an Stundendurchschnitten darstellen — mit einem Bruchteil des Speichers. Setzen Sie den Wert länger als dropAfter — den umgekehrten Fall lehnt die Plattform als Fehlkonfiguration ab.
paths erweitert das Downsampling auf Werte innerhalb von JSON-Spalten. Numerische Spalten werden automatisch einbezogen; JSON-Felder müssen ausdrücklich benannt werden, da eine JSON-Spalte keine feste Menge an Schlüsseln besitzt. Nicht deklarierte Felder funktionieren in Dashboards weiterhin — sie werden dann einfach aus der Rohtabelle berechnet.
Alles Weitere läuft automatisch. Für jede numerische Spalte werden die Kennzahlen gepflegt (Durchschnitt, Summe, Minimum, Maximum, erster Wert, letzter Wert und eine Datensatzanzahl), gruppiert nach dem Entitätsschlüssel der Tabelle (maintainLatestFlagFor, sonst nach dem publizierenden Gerät). Dashboards brauchen dafür keine Konfiguration und müssen davon nichts wissen: Ein Widget fragt wie gewohnt ab, und die Plattform entscheidet pro Abfrage, ob die vor-aggregierte Kopie sie beantworten kann — und fällt transparent auf die Rohtabelle zurück, wenn nicht, etwa wenn ein Filter eine Spalte anspricht, nach der die Kopie nicht gruppiert.
Schemaänderungen bauen die Kopie neu auf. Das Hinzufügen, Entfernen oder Umtypisieren einer Spalte einer heruntergerechneten Tabelle — oder das Ändern des
downsample-Blocks selbst — baut die vor-aggregierte Kopie aus der Rohtabelle neu auf. Alles, was älter alsdropAfterist, lässt sich nicht rekonstruieren und geht verloren. Richten Sie den Block nach Möglichkeit gleich zusammen mit der Tabelle ein, und behandeln Sie spätere Schemaänderungen an langlebigen Tabellen als bewusste Entscheidung.
Daten aus dem Edge-Code veröffentlichen
Verwenden Sie das IronFlock SDK, um Daten aus Ihrer App zu senden:
Python
from ironflock import IronFlock
flock = IronFlock()
await flock.start()
await flock.publish_to_table("sensordata", {
"timestamp": "2025-01-15T10:30:00Z",
"temperature": 23.5,
"humidity": 62.1,
"device_id": "sensor-001"
})Jede Zeile braucht einen Wert für die verpflichtende Spalte tsp: Das Daten-Backend lehnt eine Zeile ohne ihn ab. Der Tabellenschreibvorgang des SDK schlägt mit einem Fehler fehl; eine Zeile, die ein Board veröffentlicht, wird verworfen, und nur ein Eintrag in der error-logs-Tabelle der App zeugt davon. Die Definition von sensordata oben bildet diese Spalte mit path: args[0].timestamp ab, sodass tsp aus dem Feld timestamp der Zeile stammt. Eine Spalte ohne path liest das gleichnamige Feld der Zeile (args[0].<id>): Ohne diese Zuordnung bräuchte jede Zeile ein eigenes Feld tsp.
Für hochfrequente Daten senden Sie mehrere Zeilen in einer einzigen Nachricht, anstatt einen Roundtrip pro Zeile auszuführen — mit publish_rows_to_table / publishRowsToTable / PublishRowsToTable oder append_rows_to_table / appendRowsToTable / AppendRowsToTable — beide sind gleich und melden das Ergebnis des Inserts. Jeder Stapel wird atomar eingefügt — Alles-oder-nichts. Weitere Details finden Sie in der SDK-Referenz.
Transformationstabellen
Sie können SQL-Transformationen definieren, die Ihre Rohdaten automatisch aggregieren oder verarbeiten:
data:
tables:
- tablename: sensordata
columns:
# ... raw data columns ...
transforms:
- tablename: hourly_averages
materialize: true
schedule: "0 * * * *"
sql: >
SELECT
time_bucket('1 hour', tsp) AS hour,
avg(temperature) AS avg_temp,
avg(humidity) AS avg_humidity
FROM sensordata
GROUP BY hour
columns:
- id: hour
name: Hour
dataType: timestamp
- id: avg_temp
name: Average Temperature
dataType: numeric
- id: avg_humidity
name: Average Humidity
dataType: numeric| Feld | Beschreibung |
|---|---|
tablename | Name der abgeleiteten Tabelle |
materialize | Wenn true, wird das Ergebnis gespeichert und nach dem Zeitplan aktualisiert. Wenn false, ist die Transformation eine View, die bei jedem Lesezugriff berechnet wird |
schedule | Cron-Ausdruck für die Läufe der Transformation: fünf Felder (Minute, Stunde, Tag des Monats, Monat, Wochentag) oder sechs mit vorangestelltem Sekundenfeld. */5 * * * * läuft alle 5 Minuten, */10 * * * * * alle 10 Sekunden. Jeder Lauf aktualisiert ein materialisiertes Ergebnis und sendet das aktuelle Ergebnis an die Boards, die an die Transformation gebunden sind. Der Code der App kann einen solchen Lauf auch bei Bedarf ausführen, siehe Bei Bedarf aktualisieren |
sql | SQL-Abfrage, die die Transformation berechnet |
columns | Spaltendefinitionen für die Ausgabe |
Transformationstabellen sind in Boards und über das SDK zugänglich, genau wie reguläre Tabellen.
Eine Transformation wird genau so gelesen, wie ihr eigenes SQL sie zurückgibt: Zeitfenster von Widgets, Kalenderfilter und der Modus latest gelten für Tabellen und werden bei einer Transformation ignoriert. Daraus folgen drei Regeln. Grenzen Sie den Zeitbereich in der Abfrage ein (WHERE tsp > now() - interval '7 days'), sortieren Sie Zeitreihen mit den neuesten Zeilen zuerst (ORDER BY <Zeitspalte> DESC), damit ein Zeilenlimit die neuesten Zeilen behält, und wählen Sie jede Spalte aus, die ein Board darstellen oder nach der es filtern soll — eine Transformation hat keine impliziten Zeitstempel- oder Gerätespalten. Ein einzelner Lesezugriff liefert höchstens 3000 Zeilen; aggregieren Sie daher in der Abfrage.
Eine Transformation ist für das da, was ein Lesezugriff auf eine Tabelle nicht ausdrücken kann: einen Join, ein Verhältnis, eine Aggregation über die aktuellen Zeilen mehrerer Tabellen. Sie ist nicht der Weg, den aktuellen Zustand von Entitäten anzuzeigen oder gelöschte Datensätze auszublenden. Das sind Lesemodi der Tabelle selbst, der latest-Schalter und ein Filter auf eine deleted-Spalte (siehe unten), und sie arbeiten live: Ein an die Tabelle gebundenes Widget folgt jeder neuen Zeile innerhalb einer Sekunde. Eine Transformation erreicht ein Board nur nach ihrem Zeitplan (oder wenn der Code der App sie nach seinen eigenen Schreibvorgängen aktualisiert, was ein Speichern aus einem Board heraus nie auslöst), sodass eine View, die die neueste Zeile pro Entität auswählt oder gelöschte Zeilen weglässt, dasselbe Ergebnis verspätet zeigt. Braucht eine Transformation doch den aktuellen Zustand einer Entitätstabelle, etwa um sie mit einer anderen Tabelle zu verknüpfen, wählen Sie ihn in ihrem SQL mit DISTINCT ON aus und wenden die deleted-Prüfung dort an, in der Reihenfolge, die unter Soft Delete von Datensätzen gezeigt wird.
Eine Transformation mit der App auszuliefern ist nicht der einzige Weg, zu einer zu kommen: Ein Projektmitglied mit der Berechtigung Datenzugriff kann dieselbe Art von Transformation aus der Datenansicht des Projekts heraus speichern, ganz ohne App — und der KI-Assistent ebenso. Siehe Benutzerdefinierte Transformationen.
Wann sich eine materialisierte Transformation aktualisiert
Ein geplanter Lauf aktualisiert eine materialisierte Transformation nur, wenn seit ihrer letzten Aktualisierung in eine Tabelle geschrieben wurde, die sie liest, und unabhängig davon mindestens alle 10 Minuten. Ein Lauf, für den es nichts Neues zu lesen gibt, lässt das gespeicherte Ergebnis unverändert: Eine minütlich geplante Transformation über einer Tabelle, die eine Zeile pro Stunde erhält, aktualisiert sich nach dieser Zeile und sonst alle 10 Minuten.
Eine materialisierte Transformation aktualisiert sich bei jedem Lauf, wenn sich ihr Ergebnis ohne einen Schreibvorgang ändern kann:
- ihr SQL verwendet die aktuelle Zeit oder Zufall, etwa
now(),CURRENT_DATEoderrandom(); - sie ruft eine Funktion auf, die für dieselbe Eingabe ein anderes Ergebnis liefern kann: eine volatile Funktion oder eine stabile Funktion, die nicht in PostgreSQL eingebaut ist;
- sie liest etwas anderes als App-Tabellen und materialisierte Transformationen, zum Beispiel eine nicht materialisierte Transformation, eine heruntergerechnete Kopie oder eine der eigenen Tabellen der Plattform.
Wenn viele Transformationen zum selben Zeitpunkt fällig sind, aktualisiert die Plattform jeweils einige wenige, und die übrigen warten, bis sie an der Reihe sind. Eine Aktualisierung kann daher später fertig werden als zu ihrem geplanten Zeitpunkt. Ein Lauf, der fällig wird, während die vorherige Aktualisierung derselben Transformation noch läuft oder wartet, wird übersprungen.
Bei Bedarf aktualisieren
Der eigene Code der App kann den Lauf einer Transformation ausführen, ohne auf ihren Zeitplan zu warten: refresh_transform / refreshTransform / RefreshTransform des SDK aktualisiert das materialisierte Ergebnis (eine einfache View wird nur gelesen) und sendet das aktuelle Ergebnis an die Boards, die an die Transformation gebunden sind, sodass ein Board einen Stapel, den die App gerade geschrieben hat, sofort anzeigt. Es gelten dieselben Regeln wie für einen geplanten Lauf: Die Aktualisierung wird übersprungen — und als übersprungen gemeldet —, wenn seit der letzten in keine Tabelle geschrieben wurde, die die Transformation liest; ein Aufruf, der eintrifft, während eine Aktualisierung derselben Transformation läuft, wartet auf die eine dahinter eingereihte Aktualisierung; und pro Transformation startet höchstens eine Aktualisierung pro Sekunde. Die Tabellenschreibvorgänge des SDK sind festgeschrieben, bevor sie zurückkehren, sodass eine Aktualisierung nach einem Schreibvorgang diesen nie verpasst. Nur die eigenen Container der App können ihre Transformationen aktualisieren; ein Board erhält die Zeilen, und eine App, die die Daten einer anderen App konsumiert, liest deren Transformationen, kann sie aber nicht aktualisieren. Transformationen, die aus der Datenansicht des Projekts gespeichert wurden, gehören zu keiner App und laufen nur nach ihrem Zeitplan. Siehe refreshTransform / refresh_transform / RefreshTransform.
Den aktuellen Zustand einer Entität verfolgen
Für Tabellen, die den aktuellen Zustand realer Objekte darstellen — Maschinen, Anlagen, Fertigungsaufträge — unterstützt IronFlock ein Muster namens Latest-State-Tracking.
Anstatt eine Zeile bei einer Änderung zu überschreiben, fügen Sie immer eine neue Zeile hinzu. Sie deklarieren, welche Spalten eine eindeutige Entität identifizieren, und IronFlock leitet bei jedem Lesezugriff auf die Tabelle die aktuellste Zeile pro Entität ab. So erhalten Sie einen vollständigen Verlauf aller Änderungen und können gleichzeitig einfach nur den aktuellen Zustand abfragen.
Aktivieren Sie dies auf einer Tabelle mit maintainLatestFlagFor:
- tablename: machineform
maintainLatestFlagFor: ['machinename']
columns:
- id: tsp
dataType: timestamp
- id: machinename
dataType: string
- id: machinetype
dataType: string
- id: active
dataType: boolean
- id: description
dataType: stringmaintainLatestFlagFor nimmt eine Liste von Spalten entgegen, die zusammen eine eindeutige Entität identifizieren. In die Zeile selbst wird dabei nichts geschrieben: IronFlock indiziert die Tabelle nach diesem Entitätsschlüssel plus Zeitstempel und wählt zur Abfragezeit die neueste Zeile pro Entität aus. Eine Zeile, die verspätet oder außer der Reihe eintrifft, kann daher niemals eine veraltete Markierung hinterlassen.
Eine Entitätstabelle enthält eine Zeile pro Entität und Zeitstempel. Eine Zeile, die sowohl den Entitätsschlüssel als auch den tsp einer gespeicherten Zeile wiederholt, wird abgelehnt, ebenso ein Stapel, in dem zwei Zeilen das tun: Der Schreibvorgang des SDK schlägt mit URI_ENTITY_KEY_CONFLICT fehl, und die error-logs-Tabelle der App verzeichnet die Ablehnung. Geben Sie jeder Version einer Entität ihren eigenen tsp. Eine Zeile, deren Entitätsschlüsselspalte leer (NULL) ist, gehört zu keiner Entität: Sie wird nie als Wiederholung abgelehnt, und Lesezugriffe im Modus latest lassen sie aus.
Eine Entität mit einer Teilzeile aktualisieren
Eine Zeile, die an eine Entitätstabelle angehängt wird, ist eine neue Version dieser Entität — und sie muss nicht vollständig sein. Spalten, die die Zeile nicht liefert, werden von der vorherigen aktuellsten Zeile der Entität geerbt; ein einzelnes Feld zu aktualisieren bedeutet also, nur den Entitätsschlüssel, einen Zeitstempel und dieses Feld zu veröffentlichen:
| Die Spalte der neuen Zeile ist | Die gespeicherte Version enthält |
|---|---|
angegeben (0, false und "" zählen als angegeben) | den angegebenen Wert |
explizit null | NULL — die Spalte wird geleert |
| nicht vorhanden | den Wert aus der vorherigen aktuellsten Zeile |
Um eine Spalte zu leeren, senden Sie sie als null (None in Python, nil in Go, null in C#). Lassen Sie sie weg, bleibt der vorherige Wert erhalten. Achten Sie auf Code, der ein Feld unbeabsichtigt weglässt: Eine JavaScript-Eigenschaft mit dem Wert undefined etwa fällt aus dem Payload heraus. Die SDK-Referenz führt diese Fälle pro Sprache auf.
Zwei Details sind wissenswert:
- Eine Zeile, die jede Spalte liefert, überspringt das Nachschlagen der vorherigen Zeile vollständig — vollständige Zeilen bleiben also genau so günstig, wie sie es immer waren. Senden Sie auf hochfrequenten Pfaden weiterhin vollständige Zeilen.
- Die Vererbung respektiert die Zeit: Eine Zeile, die mit einem älteren Zeitstempel eintrifft (ein Backfill), erbt nur von Zeilen mit gleichem oder früherem
tsp, niemals von neueren.
Tabellen ohne maintainLatestFlagFor behalten die reine Append-Semantik: Eine Spalte, die die Zeile nicht liefert, wird als NULL gespeichert.
Um nur aktuelle Maschinenzustände abzufragen:
SELECT DISTINCT ON (machinename) *
FROM machineform
ORDER BY machinename, tsp DESCUm den vollständigen Verlauf einer bestimmten Maschine anzuzeigen:
SELECT * FROM machineform WHERE machinename = 'Assembly-Line-01' ORDER BY tspDiese Abfrage schreiben Sie nur selten von Hand, und Sie sollten sie nicht als Transformation speichern. Widgets auf einem Board, die mit dieser Tabelle verbunden sind, haben in ihren Filtereinstellungen einen latest-Schalter, sodass Benutzer immer aktuelle Werte sehen, ohne zusätzlichen Aufwand. Der Schalter arbeitet live: Das Widget erhält jede neue Zeile der Tabelle, sobald sie eintrifft, und ersetzt damit die vorherige Zeile der Entität, sodass eine Änderung innerhalb einer Sekunde nach dem Schreiben sichtbar wird, während die Tabelle jede Version behält. Nichts wird nach einem Zeitplan neu berechnet — mehr als das würde eine Transformation nicht hinzufügen. Aus dem SDK fordern Sie denselben Modus an, indem Sie {"latest": true} zu filterAnd hinzufügen — siehe getHistory.
Migration von
latest_flag: Frühere Versionen von IronFlock speicherten eine physische boolesche Spalte namenslatest_flag. Diese Spalte existiert nicht mehr — der aktuelle Zustand wird stattdessen in SQL abgeleitet, was ihn auch dann korrekt hält, wenn Zeilen außer der Reihe eintreffen. Bestehende Boards und SDK-Aufrufe, die nachlatest_flag = truefiltern, funktionieren weiterhin: IronFlock erkennt sie und wendet den Latest-State-Modus an. Neuer Code sollte den latest-Schalter oder den Filtereintrag{"latest": true}verwenden.
Den Entitätsschlüssel ändern
Sobald eine App-Version als Release veröffentlicht ist, steht der Entitätsschlüssel jeder ihrer Tabellen fest. Datenstruktur aktualisieren im Seitenpanel der Cloud-IDE und der Build eines neuen Releases lehnen eine data-template.yml ab, die den Entitätsschlüssel einer Tabelle ändert, die das neueste Release der App enthält:
- eine Spalte zu
maintainLatestFlagForhinzufügen, eine entfernen, eine ersetzen oder ihre Reihenfolge ändern; maintainLatestFlagForzu einer Tabelle hinzufügen, die es bisher nicht hatte, oder es entfernen.
Eine solche Änderung würde stillschweigend ändern, was die Tabelle in jedem Projekt zurückgibt, das die App installiert hat. Eine Spalte, die neu im Schlüssel ist, ist in jeder bestehenden Zeile leer, und Lesezugriffe im Modus latest lassen Zeilen mit einer leeren Schlüsselspalte aus, sodass alle bestehenden Entitäten verschwinden würden. Eine aus dem Schlüssel entfernte Spalte kann Entitäten zusammenlegen, deren Zeilen sich einen Zeitstempel teilen, während die Tabelle nur eine Zeile pro Entität und Zeitstempel enthalten kann.
Um einen anderen Entitätsschlüssel zu verwenden, legen Sie eine neue Tabelle mit dem neuen Schlüssel an und übertragen die Daten dorthin, zum Beispiel aus dem Code Ihrer App. Die Daten zu übertragen, ist Sache der App. Eine Tabelle, die noch in keinem Release enthalten ist, kann ihren Entitätsschlüssel während der Entwicklung weiterhin ändern. Eine App-Version, die veröffentlicht wurde, bevor es diese Regel gab, kann einen Entitätsschlüssel noch ändern: Ein Projekt, das auf sie aktualisiert, lehnt die Aktualisierung der Datenstruktur ab und behält die vorherige.
Zeilen, die eine Entität und einen Zeitstempel wiederholen
Tabellen, die geschrieben wurden, bevor IronFlock eine Zeile pro Entität und Zeitstempel durchsetzte, können noch Wiederholungen enthalten, ebenso eine Entwicklungstabelle, deren Entitätsschlüssel Sie geändert haben. Wenn der Datendienst eine solche Tabelle einrichtet, bei seinem Start oder nach einer Aktualisierung der Datenstruktur, verschiebt er jede Zeile jeder wiederholten Gruppe in eine Tabelle namens <table>__entitykey_dupes im selben Daten-Backend und schreibt aus jeder Gruppe eine Zeile zurück. Von da an lehnt die Tabelle Wiederholungen ab. Ein Eintrag in der error-logs-Tabelle der App gibt an, wie viele Zeilen verschoben wurden.
Die neue Tabelle bewahrt jede verschobene Zeile unverändert auf, dazu zwei Spalten: quarantined_at, den Zeitpunkt der Verschiebung, und restored, das die zurückgeschriebene Zeile markiert. Welche Zeile zurückgeschrieben wird, ist beliebig, wie schon bisher bei Lesezugriffen im Modus latest. Fragen Sie sie in der Abfragekonsole der Datenansicht des Projekts als databackend_<key>.<table>__entitykey_dupes ab. Ist die ursprüngliche Tabelle privat, ist auch die neue Tabelle privat. Können die Zeilen nicht verschoben werden, nennt der error-logs-Eintrag den Grund, und der Datendienst versucht es bei seinem nächsten Start erneut.
Soft Delete von Datensätzen
Das Append-Only-Modell von IronFlock bedeutet, dass Datensätze niemals physisch gelöscht werden. Verwenden Sie stattdessen eine boolesche Spalte deleted, um einen Datensatz als entfernt zu markieren. Dies bewahrt den vollständigen Audit-Trail und blendet gleichzeitig gelöschte Datensätze in Dashboards aus.
Fügen Sie jeder Entitätstabelle eine deleted-Spalte hinzu:
- id: deleted
name: Deleted
dataType: booleanWenn ein Benutzer einen Datensatz löscht (z. B. über ein Formular auf dem Board), veröffentlicht Ihre App eine neue Zeile für diese Entität mit deleted: true. In Kombination mit maintainLatestFlagFor wird diese neue Zeile zum aktuellen Zustand. Spätere Teilzeilen erben die deleted-Markierung wie jede andere Spalte, sodass ein Update, das deleted nicht erwähnt, die Entität weder wiederbelebt noch ausblendet.
Um nur aktive (nicht gelöschte) aktuelle Datensätze abzufragen:
SELECT * FROM (
SELECT DISTINCT ON (machinename) *
FROM machineform
ORDER BY machinename, tsp DESC
) latest
WHERE deleted IS NULL OR deleted = falseDie deleted-Prüfung läuft, nachdem die neueste Zeile pro Maschine ausgewählt wurde. Diese Reihenfolge ist entscheidend: Würden die gelöschten Zeilen zuerst herausgefiltert, würde die vorherige, nicht gelöschte Zeile wieder als aktueller Zustand auftauchen.
Board-Widgets und das SDK wenden dieselbe Reihenfolge automatisch an — kombinieren Sie den latest-Schalter (oder {"latest": true}) mit einem deleted-Filter, und Sie erhalten genau dieses Verhalten. Gelöschte Datensätze verschwinden sofort nach dem Absenden des Formulars aus dem Dashboard, verbleiben aber für Verlaufs- und Prüfzwecke in der Datenbank.
Auf dem Board löscht ein Löschformular einen Datensatz: ein Formular, auf dessen Absenden-Button Löschen steht und dessen verstecktes Checkbox-Feld true in die deleted-Spalte schreibt, neben dem Schlüssel des Datensatzes (siehe Daten löschen). Die Widgets, die die Datensätze auflisten, filtern die Tabelle selbst. Um die Liste zu bereinigen, ist keine View und keine Transformation nötig — und eine würde eine Löschung erst bei ihrem nächsten geplanten Lauf zeigen.
Daten mit anderen Apps teilen
Ihr Data Backend gehört allein Ihrer App: Keine andere im Projekt installierte App sieht Ihre Tabellen. Zwei optionale Schlüssel in data-template.yml ändern das.
Um Daten einer anderen App zu lesen, listen Sie die gewünschten Apps in einem Abschnitt consumes: auf oberster Ebene auf — neben data:, nicht darin:
consumes:
- app: machine-monitor
reason: "Berechnet die OEE aus den Maschinenzustands- und Zählerströmen des Monitors"
data:
tables:
- tablename: oee_results
columns:
# ... die eigenen Tabellen Ihrer App, wie gewohntapp ist der technische Name der bereitstellenden App oder "*" (Anführungszeichen erforderlich) für alle Apps im Projekt. reason wird dem Nutzer im Zustimmungsdialog angezeigt — die Deklaration allein gewährt nichts, solange er nicht zustimmt.
Um einzelne Tabellen zurückzuhalten, markieren Sie sie mit private: true. Alles, was Sie definieren, ist standardmäßig teilbar; eine private Tabelle oder Transformation taucht im Katalog, den andere Apps sehen, überhaupt nicht auf.
data:
tables:
- tablename: measurements # geteilt (Standard)
columns: [ ... ]
- tablename: calibration_state # intern — für andere Apps nie sichtbar
private: true
columns: [ ... ]Der Zugriff ist ausschließlich lesend, wird vom Nutzer pro Projekt erteilt und ist jederzeit widerrufbar. Das vollständige Modell und die SDK-Aufrufe zum Lesen von Verlauf und Live-Streams einer bereitstellenden App finden Sie unter Daten anderer Apps nutzen.
Privilegierter Zugriff
Die Container einer App laufen vom Gerät isoliert, mit den Standardrechten von Docker. Manche Apps brauchen mehr: eine serielle Schnittstelle oder einen USB-Adapter, GPIO, eine CAN- oder Bluetooth-Schnittstelle, das Host-Netzwerk. Das ist privilegierter Zugriff. Eine App mit privilegiertem Zugriff kann das gesamte Gerät steuern, auch andere Apps und deren Daten. Deshalb muss Ihre App ihn anfordern, und der Nutzer entscheidet, ob sie ihn bekommt.
Um ihn anzufordern, fügen Sie einen Abschnitt privileged: auf oberster Ebene mit einem reason hinzu — neben data:, nicht darin:
privileged:
reason: "Liest die SPS über die serielle Schnittstelle /dev/ttyUSB0"
data:
tables:
# ... die eigenen Tabellen Ihrer App, wie gewohntreason ist erforderlich. Er wird dem Nutzer im Zustimmungsdialog angezeigt; schreiben Sie ihn also für jemanden, der entscheidet, ob er Ihrer App vertraut.
Eine App ohne Tabellen schreibt data: {} neben privileged: Eine data-template.yml ohne den Schlüssel data: lässt sich nicht veröffentlichen.
Was der Nutzer erlaubt, hängt davon ab, wie die App gebaut ist:
- Eine App aus einem einzelnen Image (nur ein
Dockerfile) läuft privilegiert, wenn der Nutzer es erlaubt: mit allen Linux-Capabilities, dem/devdes Geräts und dem D-Bus des Hosts. Ohne die Deklaration läuft sie ohne Geräte des Hosts, ohne zusätzliche Capabilities und ohne den D-Bus des Hosts; das Release wird trotzdem veröffentlicht, und sein Build-Log weist darauf hin. - Eine Docker-Compose-App erhält genau die Einstellungen, die ihre
docker-compose.ymlanfordert, und der Zustimmungsdialog listet sie auf. Verwendet die Compose-Datei eine der unten genannten Einstellungen, muss die Appprivilegeddeklarieren, sonst schlägt die Veröffentlichung des Releases mit einer Fehlermeldung fehl, die den Dienst und die Einstellung nennt. Auch eine Deklaration vonprivileged, obwohl die Compose-Datei keine davon verwendet, schlägt fehl.
Diese Compose-Einstellungen gelten als privilegiert:
| Einstellung | Privilegiert, wenn |
|---|---|
privileged | jeder Wert außer false |
cap_add, devices, device_cgroup_rules | ein Eintrag vorhanden ist |
security_opt | ein anderer Eintrag als no-new-privileges vorhanden ist |
network_mode, pid, ipc, uts, userns_mode, cgroup | auf host oder container:… gesetzt |
cgroup_parent | ein Wert gesetzt ist |
volumes eines Dienstes | ein Host-Pfad (/…, ~/…, C:\…), ein Pfad außerhalb des App-Ordners (../…) oder eine Named Pipe eingebunden wird. Schreibgeschützte /etc/localtime und /etc/timezone sind erlaubt. |
volumes_from | container:… genannt wird |
volumes auf oberster Ebene | ein Volume driver_opts, external oder einen festen name hat |
networks auf oberster Ebene | ein Netzwerk einen anderen driver als bridge (etwa macvlan, ipvlan oder host) oder driver_opts setzt, external ist oder einen festen name hat |
secrets, configs auf oberster Ebene | ein Eintrag eine Datei (file) außerhalb des App-Ordners liest |
Named Volumes, Netzwerke mit dem Standardtreiber bridge, Bind-Mounts innerhalb des App-Ordners (./config:/config), veröffentlichte Ports und GPU-Reservierungen (gpus, deploy.resources.reservations.devices) sind nicht privilegiert.
Ein Platzhalter ${VAR} in einer dieser Einstellungen ist erlaubt und gilt als privilegiert, braucht also ebenfalls die Deklaration. So kann ein App-Parameter die Nutzer die serielle Schnittstelle wählen lassen:
services:
plc:
build: .
devices:
- "${SERIAL_PORT}:/dev/ttyS0"Eine Compose-Datei, die include oder extends mit einer Datei (file) verwendet, lässt sich nicht veröffentlichen, mit oder ohne Deklaration: Ein Release enthält nur die docker-compose.yml. Führen Sie die anderen Dateien darin zusammen.
Fordern Sie nicht mehr an, als die App braucht. Braucht sie eine serielle Schnittstelle, schreiben Sie eine Compose-Datei mit einem einzigen Dienst und devices: [/dev/ttyUSB0] statt eines einzelnen Images oder privileged: true. Der Nutzer sieht genau, was die App bekommt, und die App kann nicht mehr als das.
Zustimmung und Widerruf
- Bei der Installation sieht der Nutzer Ihren
reasonund bei einer Compose-App die Liste der Einstellungen, und schaltet den privilegierten Zugriff ein oder aus. Eine Ablehnung blockiert die Installation nie. - Bei einem Update fragt der Update-Dialog nach, wenn die neue Version privilegierten Zugriff anfordert und das Projekt ihn nicht erlaubt hat. Auch bei einer Ablehnung wird die App aktualisiert; die neue Version läuft dann ohne privilegierten Zugriff.
- Danach ist der privilegierte Zugriff ein Schalter in den App-Einstellungen des Projekts, wo Nutzer ihn jederzeit widerrufen oder erlauben können. Laufende Geräte starten die App mit der neuen Einstellung neu.
Ein Lauf im Entwicklungsmodus aus der Cloud-IDE folgt der Deklaration und hat keinen Schalter: Der Entwicklungs-Build läuft privilegiert, wenn .ironflock/data-template.yml privileged deklariert, und sonst ohne privilegierten Zugriff. Verwendet die Compose-Datei privilegierte Einstellungen ohne Deklaration, schlägt der Entwicklungs-Build mit demselben Fehler fehl wie eine Veröffentlichung.
Ohne Zustimmung
Die App startet trotzdem. Eine App aus einem einzelnen Image läuft mit den Standardrechten von Docker: kein /dev, keine zusätzlichen Capabilities, kein D-Bus des Hosts. Bei einer Compose-App entfernt der Geräte-Agent die privilegierten Einstellungen aus der Compose-Datei, bevor er die App startet, und schreibt ins Log der App, welche Einstellungen er aus welchem Dienst entfernt hat. Sorgen Sie dafür, dass Ihr Code meldet, was er nicht erreicht, etwa eine serielle Schnittstelle, die er nicht öffnen kann, statt abzustürzen.
Ältere Releases
Releases, die veröffentlicht wurden, bevor Apps privilegierten Zugriff deklarieren mussten, gelten so, als forderten sie ihn an, und bestehende Installationen behalten ihn, sodass diese Apps wie bisher laufen. Nutzer können ihn wie bei jeder anderen App in den App-Einstellungen des Projekts widerrufen. Ab Ihrem nächsten Release deklarieren Sie privileged, wenn die App es braucht.