Datasets | everyn

Datasets sind die Eingabeschicht für Everyn-Arbeit. Ein Dataset ist nicht nur ein Dateiname; es ist ein dauerhafter Source Snapshot mit stabiler Row Identity, Column Metadata, Sample-/Profile-Kontext und Verbindung zu den Runs, die es verwenden.

CSV Intake verwendet direkte Uploads. Everyn nimmt den Upload an, verarbeitet ihn asynchron, validiert und normalisiert die Quelle und stellt ein completed Dataset erst bereit, wenn die Eingabe für Runs nutzbar ist.

Intake und Identity

Intake-Lifecycle

Schritt	Was passiert	Was bewahrt werden muss
Upload erstellen	Client sendet CSV mit `sourceName`, `sourceType`, Metadata und Idempotency Key.	`uploadId`, `sourceName`, Request ID.
Processing	Everyn validiert gespeicherte Upload-Metadaten und parst die CSV.	Upload-Status und Failure Details.
Completed	Ein dauerhaftes Dataset wird aus dem normalisierten Snapshot registriert.	`datasetId`, Row Count, Columns, Sample/Profile.
Failed	Der Upload bleibt mit öffentlich sicheren Failure Metadata prüfbar.	`failure.code`, `failure.docsUrl`, Field Errors.
Retry	Retryable Failed Uploads können erneut verarbeitet werden, solange die Quelle existiert.	Ursprüngliche `uploadId` und Retry Outcome.

Dataset Identity

Wichtige Kennungen und Felder:

Feld	Warum es wichtig ist
`datasetId`	Identifiziert das dauerhafte Dataset für zukünftige Runs.
`datasetRowId`	Stabile Row Identity über Scopes, Retries, Outputs, Failures und Exports.
`uploadId`	Identifiziert den Intake-Versuch und seinen Failure- oder Retry-Status.
`sourceName`	Verbindet einen Fehler mit Datei oder Ursprungssystem.
`columnMap`	Verbindet Source Columns mit normalisierten Snapshot Columns.
`failure.code`	Zeigt dem Client, ob Eingabe korrigiert, wiederholt oder neu hochgeladen werden muss.
`failure.docsUrl`	Verlinkt direkt auf Recovery-Hinweise.

CSV-Erwartungen

CSV Uploads verwenden direkten Multipart Intake:

Das direkte Multipart File Limit ist 25 MiB.
Dataset-Erstellung ist nach Upload-Annahme asynchron.
Upload Progress wird über Resource State und Byte-Felder ausgedrückt, nicht über progressPercent.
Failed Uploads bleiben lesbare Ressourcen.

Für Endpoint-Mechanik nutze Dataset Uploads und Dataset Uploads API.

Vor dem Erstellen eines Job Specs

Prüfe genug vom Dataset, um keinen generischen Prompt zu schreiben:

Source Name und Source Type
Row Count
Column Names und Beispielwerte
fehlende oder fehlerhafte Werte
ob der beabsichtigte Output Columns ergänzt oder Child Rows erzeugt
Felder, die nie an externe Systeme gesendet oder exportiert werden sollten

Recovery-Pfade

Error	Bedeutung	Nächster Schritt
`csv_parse_failed`	Die CSV konnte nicht in ein gültiges Dataset geparst werden.	Datei korrigieren und Upload wie angewiesen neu erstellen oder wiederholen.
`transient_intake_failure`	Intake ist aus einem retryable Systemgrund fehlgeschlagen.	Wiederholen, wenn die Upload-Quelle noch existiert.
`upload_source_expired`	Die gespeicherte Quelle für Retry ist abgelaufen.	Neuen Upload erstellen.

Häufige Fehler

Upload-Annahme als completed Dataset Creation behandeln.
Einen Run starten, bevor datasetId vorhanden ist.
Parse Errors durch die generische Meldung "der Upload ist fehlgeschlagen" ersetzen.
Annehmen, dass Row Indexes genug Identität über Retry-Lineage hinweg sind.
Die ursprüngliche lokale CSV ändern und erwarten, dass sich ein bestehender Dataset Snapshot ändert.