Das n8n-Datenmodell sicher beherrschen

Das n8n-Datenmodell sicher beherrschen

0:00 Wenn ich eine einzige Stunde hätte, um jemanden in n8n einzuführen, würde ich diese hier nehmen. Denn die meisten Fehler, die Sie in Ihren ersten Wochen suchen werden, sind keine Logikfehler. Es sind Fehler darüber, welcher Datensatz gerade gemeint ist. Das Datenmodell von n8n ist erstaunlich einfach aufgebaut — es ist im Grunde eine einzige Regel.

0:20 Aber diese Regel hat Folgen, die man kennen muss, sonst rätselt man vor einem Bildschirm, auf dem alles richtig aussieht und trotzdem der falsche Wert ankommt.

Das n8n-Datenmodell sicher beherrschen

0:30 Wir bleiben am ersten Tag und gehen eine Ebene tiefer. Zuerst die Grundregel: Was fließt eigentlich zwischen zwei Bausteinen? Dann die Expressions — die kleinen Ausdrücke, mit denen Sie auf diese Daten zugreifen — und der häufigste Fehler dabei. Danach die fertigen Bausteine zum Umformen von Daten. Und zum Schluss die Sonderfälle: Dateien, verschachteltes JSON und die Frage, warum Datensätze manchmal spurlos verschwinden.

Items, Felder und Datenfluss

0:56 Fangen wir mit der Regel an, auf der alles aufbaut. Sie passt in einen Satz, und wenn Sie diesen Satz verinnerlicht haben, erklären sich erstaunlich viele Beobachtungen von selbst. Alle Daten, die zwischen Bausteinen fließen, sind ein Array von Objekten. Nutzdaten stehen unter dem Schlüssel json, binäre Daten unter binary.

1:15 Jeder Eintrag dieses Arrays ist ein Item — und jetzt kommt der entscheidende Teil: Ein Baustein verarbeitet jedes Item einzeln, mit derselben Konfiguration. Denken Sie an ein Fließband in einer Packstation. Es kommen hundert Pakete, und dieselbe Maschine klebt auf jedes ein Etikett. Sie stellen die Maschine einmal ein, aber sie arbeitet hundertmal. Genau deshalb heißt zwei Items im Eingang eben auch zwei Aufrufe im Baustein — nicht einer mit zwei Werten.

1:44 Sie sehen hier den Aufbau eines einzelnen Items, und mir geht es nur um die Struktur, nicht um die Werte. Oben die Nutzdaten unter json — das ist der Teil, mit dem Sie neunzig Prozent der Zeit arbeiten. Darunter die Binärdaten unter binary: Dort liegt eine Datei, und zwar mit ihren Begleitangaben — MIME-Typ, Dateiname, Endung. Das Wichtige daran ist die Trennung.

2:05 Wer eine Datei durch einen Baustein schickt, der nur json kennt, verliert sie unter Umständen, ohne dass irgendetwas rot wird. Diese Zweiteilung erklärt eine ganze Reihe merkwürdiger Beobachtungen im Alltag. Vier Folgerungen. Die erste kennen Sie schon, sie ist aber so wichtig, dass sie hier noch einmal steht: Zwei Items heißen zwei Aufrufe.

2:26 Die zweite ist tückisch — ein Baustein, der nichts zurückgibt, lässt den Zweig dahinter leer laufen; es gibt keinen Fehler, es passiert einfach nichts mehr. Die dritte ist ein Arbeitstipp: Die Schema-Ansicht zeigt Ihnen die Struktur, die Tabellenansicht die Werte — beim Suchen brauchen Sie meist die Struktur. Und die vierte klärt ein verbreitetes Missverständnis: Wenn Sie ein Feld per Drag-and-drop abbilden, erzeugen Sie einen Feldpfad, keinen festen Wert.

2:54 Jetzt zu einem Begriff, der Ihnen den ganzen Kurs über begegnen wird: Item Linking. Jedes Ausgabe-Item merkt sich, aus welchem Eingabe-Item es entstanden ist. So entsteht ein Faden, an dem Sie zurückgehen können. Stellen Sie sich eine Gepäckermittlung am Flughafen vor: An jedem Koffer hängt ein Abschnitt, mit dem sich auch nach drei Umladungen noch feststellen lässt, zu welchem Ticket er gehört.

3:16 Genau dafür ist die Verkettung da — Sie können aus einem späteren Baustein auf das zugehörige Item eines früheren zugreifen, selbst wenn sich die Reihenfolge zwischendurch geändert hat. Der erste Punkt betrifft vor allem eigene Bausteine: Wenn der json-Schlüssel fehlt, ergänzen ihn nur Code- und Function-Node von selbst.

3:35 Der zweite ist der häufigste Anfängerfehler überhaupt — der Baustein bekommt ein Item, das eine Liste enthält, obwohl er eine Liste von Items erwartet. Dafür gibt es einen eigenen Baustein, wir kommen gleich dazu. Der dritte ist ein Denkfehler beim Zugreifen: Sie zielen auf den ersten Datensatz, obwohl der Baustein ohnehin über alle läuft.

3:54 Und der vierte gehört zur Zweiteilung von eben: Binärdaten werden wie Nutzdaten gelesen und tauchen im json schlicht nicht auf.

Expressions und dynamische Parameter

4:02 Kommen wir zu dem Werkzeug, mit dem Sie auf all diese Daten zugreifen. Es ist klein, es steht mitten im Eingabefeld — und es hat eine Fehlermeldung, die anfangs jeden ratlos macht. Beide sehen wir uns an. Expressions sind kurze, JavaScript-ähnliche Ausdrücke, die in doppelten geschweiften Klammern direkt in einem Parameterfeld stehen.

4:23 Sie setzen Werte dynamisch — aus Daten vorheriger Bausteine, aus Workflow-Metadaten, aus Umgebungsvariablen. Der Vergleich, der hier trägt: Das ist die Formel in einer Tabellenkalkulation. Sie schreiben nicht den Wert ins Feld, sondern die Vorschrift, wie er entsteht. Und wie in der Tabellenkalkulation sehen Sie sofort das Ergebnis — n8n zeigt den berechneten Wert in einer Vorschau.

4:46 Die Dokumentation empfiehlt ausdrücklich, Expressions überall dort zu nehmen, wo sie reichen. Genau aus diesem Grund. Diese Zeilen sind kein Auswendiglernstoff, sondern ein Muster. Ganz oben der Zugriff auf das aktuelle Item — das ist der Normalfall und kurz. Darunter wird es interessant: Sie sprechen einen früheren Baustein mit Namen an und holen sich von dort einen Wert.

5:09 Und jetzt achten Sie auf den Unterschied in diesen drei Zeilen: einmal das zugehörige Item, einmal das erste, einmal eines an bestimmter Position. Das sieht nach Geschmacksfrage aus, ist aber die Weiche zwischen einem Ausdruck, der fachlich richtig ist, und einem, der zufällig das Richtige liefert. Unten noch die Metadaten — Workflow-Name, Ausführungskennung.

5:31 Jetzt zu der Fehlermeldung, die anfangs ratlos macht. n8n verfolgt für jedes Item einen Faden zurück zu seinen Vorgängern — das Item Linking von vorhin. Wenn Sie das zugehörige Item eines früheren Bausteins anfordern, läuft n8n diesen Faden entlang. Ist er unterbrochen, weiß n8n nicht, welches Item gemeint ist. Zeigt er auf mehrere Items, ist die Auswahl ebenfalls unklar. Und dann meldet der Editor einen Fehler, statt zu raten.

5:57 Das ist eine gute Entscheidung des Werkzeugs: Ein geratener Zusammenhang wäre schlimmer als ein sichtbarer Fehler — nur merkt man das erst, wenn man ihn einmal hatte. Vier Schritte, und die Reihenfolge ist wichtig. Prüfen Sie zuerst, welcher Baustein den Faden unterbricht — meistens ist es eine Zusammenführung. Entscheiden Sie dann, ob wirklich das zugehörige Item gemeint ist; erstaunlich oft lautet die Antwort nein, und dann ist die Frage schon beantwortet.

6:25 Ist die Position bekannt, weichen Sie auf das erste, das letzte oder eines an bestimmter Position aus. Und wenn nicht, beheben Sie die Ursache, statt den Zugriff zu umgehen. Denn Ausweichen verschiebt das Problem nur — es fällt Ihnen auf die Füße, sobald sich die Reihenfolge einmal ändert. Der erste Punkt ist der Standardfall: Der Zugriff auf das zugehörige Item wird nach einer Zusammenführung benutzt, wo der Faden nicht mehr eindeutig ist.

6:52 Der zweite ist die verführerische Abkürzung — das erste Item nehmen, weil es den Fehler wegmacht, nicht weil es fachlich stimmt. Das läuft, bis zum ersten Mal zwei Datensätze ankommen. Der dritte ist eine Wartungsfalle: Sie benennen einen Baustein um, und alle Expressions, die ihn mit Namen ansprechen, brechen. Und der vierte ist eine Stilfrage mit Folgen: Expressions werden für Logik missbraucht, die längst ins Code-Panel gehört.

Daten transformieren

7:17 Für die häufigen Umformungen brauchen Sie keinen Code. n8n bringt dafür fertige Bausteine mit, und es lohnt sich, sie zu kennen — schon damit Sie nicht nachbauen, was es längst gibt. Diese sechs Bausteine decken den größten Teil des Alltags ab, und sie sortieren sich nach einer einfachen Logik: Die ersten drei ändern die Zahl der Items, die letzten drei den Inhalt oder die Auswahl.

7:40 Aggregate fasst viele Items zu einem zusammen, Split Out macht aus einem Item mit einer Liste viele Items — das ist die Antwort auf den Stolperstein von vorhin. Summarize verdichtet, ähnlich einer Pivot-Tabelle. Sort ordnet, Remove Duplicates entfernt Doppelte über alle oder ausgewählte Felder, Limit kappt die Menge. Wenn eine dieser Beschreibungen zu Ihrer Aufgabe passt, nehmen Sie den Baustein — nicht den Code.

8:04 Diese vier Zeilen sind eine Entscheidungshilfe, die Sie sich merken können. Brauchen Sie einen einzelnen Parameterwert aus vorhandenen Daten? Dann eine Expression. Ist es eine der genannten Standardoperationen? Dann der passende Baustein. Geht es um den Umbau von Arrays und Objekten oder um eigene Algorithmen? Dann Code.

8:24 Und wollen Sie viele Items auf einmal umformen? Ebenfalls Code. Die Reihenfolge ist dabei eine Empfehlung: Je weiter oben Sie bleiben, desto leichter ist die Lösung später zu lesen — und desto eher sieht jemand anders auf einen Blick, was passiert. Diese fünf Schritte sind das Grundmuster jeder Datenintegration, und der letzte ist der, den man weglässt.

8:45 Bringen Sie beide Seiten zuerst auf dieselbe Feldbenennung — solange die Felder unterschiedlich heißen, arbeiten Sie gegen die Werkzeuge. Zerlegen Sie Listen mit Split Out in einzelne Items. Führen Sie über den gemeinsamen Schlüssel zusammen. Entfernen Sie Doppelte. Und dann prüfen Sie das Ergebnis gegen die erwartete Anzahl.

9:04 Dieser fünfte Schritt kostet zwei Minuten und ist der einzige Schutz gegen stillen Verlust — denn fehlende Datensätze erzeugen in n8n keinen Fehler, sie sind einfach nicht da. Der erste Punkt ist ein Dauerbrenner in Integrationsprojekten: Datumsformate werden erst im Zielsystem als unterschiedlich erkannt — dann ist die Datei schon weg.

9:24 Der zweite: Remove Duplicates prüft alle Felder, obwohl nur der Schlüssel zählen soll; dann bleiben Doppelte stehen, weil sich irgendwo ein Zeitstempel unterscheidet. Der dritte ist klassisch und schwer zu sehen: Sortiert wird auf Text, obwohl die Werte Zahlen sind — dann steht die Zehn vor der Zwei. Und der vierte ist der fehlende fünfte Schritt von eben: Nach dem Umbau prüft niemand, ob noch alle Datensätze da sind.

Binärdaten, JMESPath und typische Fehler

9:48 Zum Abschluss die Sonderfälle — Dateien und tief verschachteltes JSON — und dann die Frage, die Sie in der Praxis am häufigsten stellen werden: Wo sind meine Daten hin? JMESPath ist eine Abfragesprache für JSON, und n8n stellt dafür eine eigene Methode bereit. Der Vergleich, der hier hilft: Das ist für JSON, was XPath für XML ist — Sie beschreiben, welchen Teil eines verschachtelten Gebildes Sie haben wollen, statt sich durch drei Schleifen zu hangeln.

10:15 Eine Einschränkung müssen Sie kennen: Im Python-Code-Node gibt es diese Methode nicht; dort arbeiten Sie mit den Bordmitteln von Python. Und eine ehrliche Einordnung: JMESPath ist mächtig, aber wenn ein Transformations-Baustein dasselbe leistet, ist der die bessere Wahl — er ist lesbarer. Zwei Beispiele, und mir geht es um das Muster dahinter.

10:36 Die erste Zeile holt aus einer Liste von Anlagen alle Seriennummern heraus — aus einer verschachtelten Struktur wird eine flache Liste, in einem Ausdruck. Die zweite filtert zusätzlich: nur die Anlagen unterhalb eines bestimmten Baujahrs. Sie sehen, worauf es ankommt: Sie beschreiben das Ergebnis, nicht den Weg dorthin.

10:56 Die vollständige Syntax steht übrigens nicht in der n8n-Dokumentation, sondern bei JMESPath selbst — das ist eine eigenständige Sprache, die n8n nur einbindet. Merken Sie sich diese Trennung, wenn Sie später suchen. Diese vier Ursachen decken den größten Teil der Fälle ab, in denen Sie ratlos vor einem leeren Feld sitzen.

11:16 Erstens: Der Faden des Item Linking ist an einer Zusammenführung gerissen. Zweitens: Ein Feld heißt in der zweiten Quelle anders und wird still ignoriert — still, das ist das Tückische. Drittens: Ein Baustein hat null Items zurückgegeben, und der Zweig läuft leer weiter; auch das ohne Fehlermeldung. Und viertens: Die Binärdaten wurden weitergereicht, aber das Ziel erwartet sie unter einem anderen Schlüssel.

11:40 Wenn Sie diese vier durchgehen, haben Sie die Ursache meistens gefunden. Der erste Punkt ist die Gefahr beim Umgang mit Dateien: Binärdaten werden durch eine Transformation gereicht, die nur json kennt. Der zweite ist eine Leistungsfrage, die erst bei Last auffällt — große Dateien wandern durch mehrere Bausteine, statt früh abgelegt zu werden; jede Station hält sie im Speicher.

12:02 Der dritte ist die Versuchung nach einem neu gelernten Werkzeug: JMESPath wird für etwas benutzt, das ein Baustein sauberer erledigt. Und der vierte ist die Zusammenfassung dieses ganzen Moduls: Fehlende Felder erzeugen keinen Fehler, sondern leere Werte im Zielsystem.

Übung

12:18 Jetzt bringen Sie all das zusammen — an genau dem Problem, das in echten Integrationsprojekten den größten Teil der Zeit frisst: zwei Bestände, die dasselbe meinen und es unterschiedlich sagen. Kesselwerk führt seine Anlagen in zwei Beständen. Kundenkreis liefert eine flache Anlagenliste je Kunde. Das Portal Teilehandel liefert verschachtelte Wartungsprotokolle — mit abweichenden Feldnamen, abweichenden Datumsformaten und abweichenden Einheiten.

12:45 Das ist kein konstruiertes Übungsproblem, sondern der Normalfall: Zwei Systeme sind unabhängig voneinander gewachsen, und beide haben recht. Ihre Aufgabe ist es, daraus einen Stand zu machen, dem man trauen kann. Das Lernziel: unterschiedlich strukturierte Daten so normalisieren und verknüpfen, dass die Zuordnung nachweisbar stimmt.

13:05 Auf dem Wort nachweisbar liegt die Betonung — plausibel aussehen reicht nicht. Erfolgreich sind Sie, wenn jedes Wartungsprotokoll an der richtigen Anlage hängt, Datumsformate und Einheiten einheitlich sind und die Anzahl der Ergebnis-Items mit der erwarteten übereinstimmt. Wer früh fertig ist, baut einen Datensatz mit fehlendem Schlüsselfeld ein und lässt den Workflow ihn sichtbar melden.

13:26 Das ist die eigentliche Kunst: Es ist leicht, den guten Fall zu verarbeiten, und schwer, den schlechten nicht zu übersehen. Eine Stunde, fünf Schritte. Vergleichen Sie zuerst beide Strukturen in der Schema-Ansicht und notieren Sie die Unterschiede — schriftlich, nicht im Kopf. Zerlegen Sie dann die verschachtelten Protokolle mit Split Out. Gleichen Sie Feldnamen sowie Datums- und Zahlenformate an.

13:50 Führen Sie über die Seriennummer zusammen und prüfen Sie die Zuordnung stichprobenartig — nehmen Sie sich drei Anlagen und sehen Sie wirklich hin. Und zuletzt: Stellen Sie Eingangs- und Ausgangszahl gegenüber und erklären Sie die Differenz. Falls es keine gibt, umso besser — aber wissen sollten Sie es. Vier Fallen. Erstens: Die Zuordnung wird über den Namen versucht statt über die Seriennummer. Namen sind selten eindeutig, Seriennummern sind es meistens.

14:18 Zweitens, und das ist die gemeinste Falle dieser Übung: Die Zahl der Items stimmt zufällig, die Zuordnung aber nicht — deshalb die Stichprobe zusätzlich zur Zahl. Drittens: Der Zugriff auf das zugehörige Item wird nach der Zusammenführung benutzt und bricht; Sie wissen jetzt, warum. Und viertens: Einheiten werden angeglichen, aber nicht dokumentiert — der Nächste rechnet dann noch einmal um.