Teil 4. Umgebung: Qwen Code, dbt, DuckDB

Die Umgebung muss lokal, reproduzierbar und klein genug sein, damit der Student den SDD-Zyklus sieht und nicht mit der Infrastruktur kämpft. Daher werden im Lernpfad Python, DuckDB, dbt-core und dbt-duckdb verwendet.

Mindestanforderungen

• Python 3.11+;
• venv;
• Shell mit bash;
• Qwen Code CLI oder ein kompatibles Agentenwerkzeug;
• Zugriff auf das lokale Repository.

Überprüfung:

python3 --version
python3 -m venv /tmp/sdd-data-check
. /tmp/sdd-data-check/bin/activate
pip --version

Beispielinstallation

cd book3/examples/bank-lakehouse
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
bash smoke_all.sh

Ein vollständiger Smoke-Lauf sollte raw/seeds erzeugen, dbt parse und dbt build ausführen. Wenn dbt nicht installiert ist, prüft der Fallback-Modus nur die Struktur. Dies ist eine teilweise Überprüfung und kein Beweis für die Einsatzbereitschaft des Lehrbuchs.

Warum DuckDB

DuckDB ermöglicht es, SQL, Typen, Aggregate, dbt-Tests und lokalen Speicher ohne externen Dienst zu zeigen. Das macht Fehler billiger. Wenn revoked_at leer ist und die Typumwandlung fehlschlägt, sieht der Student das Problem im Source/Staging-Vertrag und nicht in den Clustereinstellungen.

DuckDB ersetzt nicht die Produktionsumgebung. Es ersetzt die erste Lernumgebung. Sobald Grain, PII-Richtlinien und Verträge lokal verstanden sind, kann dasselbe Schema auf Trino, Spark, Databricks oder Snowflake übertragen werden.

Agentenkonfiguration

Im Beispiel gibt es AGENTS.md und .qwen/commands/sdd/. Vor jeder Modelländerung muss der Agent Folgendes lesen:

• AGENTS.md;
• specs/mission.md;
• specs/tech-stack.md;
• erforderliche ODCS/ODPS;
• erforderliche Modellspezifikation;
• Überprüfungsfakten.

Beginnen Sie nicht mit „repariere dbt". Beginnen Sie mit „vergleiche den Fehler mit dem Vertrag und zeige, welche Tatsache verletzt wurde".

Erläuterung für den Leser

Die lokale Umgebung in diesem Buch ist absichtlich bescheiden. Dies ist kein Versuch, so zu tun, als wäre die Produktionsumgebung einfach aufgebaut. Im Gegenteil: Ein kleiner Stack ist nötig, um Lernfehler vom Infrastrukturrauschen zu trennen. Wenn dbt build an einem leeren Datum fehlschlägt, sollte der Leser das Problem in Staging und im Vertrag sehen und sich nicht mit Cluster, Geheimnissen, Rechten, Katalog und Netzwerkrichtlinien befassen müssen.

DuckDB ist genau als Labor nützlich. Es ist einer analytischen Engine ähnlich genug, um Typen, Aggregate, Materialisierungen und Tests zu zeigen. Gleichzeitig ist es nah genug, dass der Student die Datenbank löschen, die Daten neu aufbauen und wieder dasselbe Ergebnis erhalten kann. Solche Reproduzierbarkeit ist wichtiger als das Gefühl einer „echten" Plattform. Wenn die erste Lernumgebung lokal nicht reproduzierbar ist, fügt eine Übertragung auf Iceberg oder Spark nur neue Gründe für zufällige Abweichungen hinzu.

Ein separates venv ist ebenfalls Teil der Disziplin. Es legt die Grenzen des Beispiels fest: hier sind die Werkzeugversionen, hier ist der Installationsbefehl, hier ist der Überprüfungsbefehl. Wenn Pins aktualisiert werden, sollte dies durch einen Smoke-Lauf bestätigt werden und nicht durch Vertrauen auf den Namen „latest". Für ein Lehrbuch ist dies besonders wichtig: Der Leser kopiert Befehle, und wenn diese fehlschlagen, hört er auf, nicht nur der Umgebung, sondern auch dem Prozess zu vertrauen.

Schließlich setzt die Umgebung die richtige Haltung zum Agenten. Der Agent sollte nicht den Befehl „repariere alles" erhalten, wenn dbt nicht läuft. Zuerst muss verstanden werden, welche Grenze verletzt wurde: Abhängigkeit nicht installiert, Rohdaten fehlen, Staging interpretiert einen leeren Wert falsch, Vertrag stimmt nicht mit dem Modell überein. Je kleiner die Umgebung, desto einfacher ist es, diese Diagnose zu lernen.

Übung

Führen Sie smoke_all.sh in zwei Modi aus: ohne aktiviertes venv und nach der Installation der Abhängigkeiten. Notieren Sie, welcher Modus teilweise und welcher vollständig ist und welche Ausgabezeilen einen erfolgreichen dbt build belegen.

Minimale Ausgabe

Nach dem Kapitel sollten Sie Folgendes haben:

• lokal installierte Umgebung;
• erfolgreicher oder ehrlich festgehaltener smoke_all.sh;
• Verständnis, welcher Überprüfungsmodus vollständig und welcher teilweise war;
• Notiz darüber, wo specs, models, tests und die Artefakte des Reviewers liegen.

Typischer Fehler

Den Fallback-Smoke-Lauf ignorieren. Die Meldung „Struktur- und Datengenerierungsprüfung bestanden" bedeutet nicht, dass die dbt-Modelle korrekt sind. Es prüft nur, dass das Beispiel geöffnet und Rohdateien erzeugt werden können.

Kontrollfragen

1. Warum ist lokales DuckDB beim ersten Durchlauf nützlicher als ein Produktionscluster?
2. Worin unterscheidet sich ein teilweiser Smoke von einem vollständigen?
3. Welche Dateien muss der Agent vor der Änderung des Mart lesen?