Referenzdaten

Referenzdaten sind strukturierte Tabellen (Parquet-Dateien), die Sie pro Projekt in feld.ai hinterlegen — zum Beispiel Produkt- oder Materialkataloge, Kundenlisten oder Sensormesswerte. Das System verwaltet Versionen der Daten, sodass Sie nachvollziehen können, welche Datenbasis zu welchem Zeitpunkt galt.

Dieses Dokument zeigt, wie Sie Referenzdatensätze im Projekt einsehen und verwenden. Das Hochladen erfolgt ausschließlich über die externe API.

---

1. Referenzdaten öffnen

1. Öffnen Sie Ihr Projekt.

2. Klicken Sie in der Toolbar auf das Drei-Punkte-Menü (⋮) und wählen Sie Referenzdaten. Die Übersicht aller Datensätze des Projekts wird angezeigt.

Wenn Ihr Projekt noch keine Referenzdaten enthält, sehen Sie einen Hinweis. Referenzdaten werden erst sichtbar, sobald sie über die API hochgeladen wurden (siehe Referenzdaten hochladen).

---

2. Datensätze durchsuchen

Jeder Datensatz erscheint als eigene Karte mit den wichtigsten Informationen auf einen Blick:

• Name und optionale Beschreibung
• Spaltennamen der aktuellen Version
• Anzahl Versionen — wie oft der Datensatz aktualisiert wurde
• Zeilenanzahl der aktuellen Version
• Letzte Aktualisierung
• Versions-Badge — die aktuell aktive Versionsnummer (z. B. v3)

1. Klicken Sie auf eine Karte, um den Datensatz auszuklappen. Die Versionshistorie wird angezeigt.

2. Klicken Sie erneut auf die Karte, um den Datensatz wieder einzuklappen.

---

3. Versionshistorie und Daten einsehen

Im ausgeklappten Datensatz sehen Sie:

• Aktuelle Spalten — die Spaltennamen der aktiven Version als Chips
• Versionshistorie — alle Versionen als Zeitleiste, absteigend sortiert (neueste zuerst). Die aktuelle Version ist markiert.

Für jede Version werden angezeigt:

• Versionsnummer (z. B. v2) und Badge „Aktuell" bei der aktiven Version
• Erstellungsdatum und Uhrzeit
• Notiz — optionale Beschreibung, die beim Hochladen mitgegeben wurde
• Zeilenanzahl dieser Version

Daten einer Version anzeigen

1. Klicken Sie in der Zeitleiste auf einen Versions-Eintrag.

2. Bei kleinen Datensätzen (unter 1 MB) werden die Daten automatisch geladen.

3. Bei größeren Datensätzen erscheint die Schaltfläche Daten laden. Klicken Sie darauf, um die Daten aus dem Speicher zu laden.

Die Datentabelle wird unter der Version eingeblendet.

Tipp: Zwischen Versionen wird der zuletzt geladene Inhalt zwischengespeichert. Ein erneutes Öffnen derselben Version lädt die Daten nicht neu.

Grenzen bei der Anzeige

Um die Darstellung im Browser schnell zu halten, gelten feste Grenzen:

Grenze	Verhalten
10 000 Zeilen pro Anzeige	Es werden die letzten 10 000 Zeilen angezeigt. Ein Hinweis nennt die Gesamtzahl.
10 MB pro Datensegment	Einzelne Segmente über 10 MB werden übersprungen.
Alle Segmente > 10 MB	Es erscheint die Warnung „Alle Datensegmente überschreiten 10 MB und können nicht im Browser angezeigt werden".

Hinweis: Die Begrenzungen betreffen nur die Anzeige im Browser. Für die Dokumentverarbeitung stehen dem System stets die kompletten Daten zur Verfügung.

---

4. Referenzdaten hochladen (API)

Das Hochladen, Aktualisieren und Löschen von Referenzdaten erfolgt über die feld.ai External API. Eine Benutzeroberfläche zum direkten Upload ist derzeit nicht vorhanden.

Voraussetzungen

• Gültiger API-Schlüssel für das Zielprojekt (siehe Einstellungen > API Keys)
• Daten als Parquet-Datei (max. 1 GB pro Upload)

Vorgehen

Die External API (https://api.feld.ai/api/v1) unterstützt folgende Operationen. Der API-Schlüssel ist dem Projekt zugeordnet — es muss keine Projekt-ID im Pfad angegeben werden.

Operation	Endpoint	Zweck
Datensatz erstellen	POST /reference-datasets	Legt einen neuen Datensatz mit erster Version an
Liste abrufen	GET /reference-datasets	Alle Datensätze des Projekts auflisten
Metadaten ändern	PATCH /reference-datasets/{id}	Name oder Beschreibung aktualisieren
Neue Version hochladen	POST /reference-datasets/{id}/versions	Ersetzt die aktuelle Version durch eine neue
Zeilen anhängen	POST /reference-datasets/{id}/append	Fügt zusätzliche Zeilen zur aktuellen Version hinzu
Datensatz löschen	DELETE /reference-datasets/{id}	Entfernt den Datensatz mit allen Versionen

Die genaue Request-Struktur und alle Parameter finden Sie in der API-Referenz.

Schema-Entwicklung

Beim Hochladen einer neuen Version gilt:

• Neue Spalten hinzufügen ist erlaubt.
• Spalten entfernen, die in der Vorversion existiert haben, wird mit einem Fehler (HTTP 422) abgelehnt.
• Beim Anhängen von Zeilen muss das Schema exakt der aktuellen Version entsprechen (gleiche Spalten in gleicher Reihenfolge).

Achtung: Beim Löschen eines Datensatzes werden alle Versionen und die zugehörigen Dateien entfernt. Dokumentergebnisse, die diesen Datensatz bereits referenzieren, bleiben erhalten — die zugrundeliegenden Referenzdaten lassen sich danach aber nicht mehr einsehen.

---

Gut zu wissen

Frage	Antwort
In welchem Format müssen Referenzdaten vorliegen?	Parquet. CSV oder Excel werden nicht unterstützt.
Wie groß darf eine Datei sein?	Maximal 1 GB pro Upload.
Kann ich einen Datensatz über die Oberfläche bearbeiten?	Nein — alle Änderungen (erstellen, aktualisieren, löschen) laufen über die API.
Gibt es eine Grenze für die Anzahl Datensätze pro Projekt?	Keine feste Obergrenze.
Werden alte Versionen gelöscht, wenn eine neue hochgeladen wird?	Nein. Alle Versionen bleiben erhalten und sind über die Zeitleiste einsehbar.
Welche Version wird bei der Verarbeitung verwendet?	Immer die aktuelle Version (gekennzeichnet mit „Aktuell").
Warum zeigt der Browser nur einen Teil der Daten an?	Zur Wahrung der Performance gelten die oben genannten Anzeigegrenzen (10 000 Zeilen / 10 MB pro Segment).