duck_lineage

DuckLineage erfasst automatisch die Datenherkunft (Lineage) jeder DuckDB-Abfrage und sendet OpenLineage-Ereignisse.

Maintainer: ilum-cloud, thijs-s

Installation und Laden

INSTALL duck_lineage FROM community;
LOAD duck_lineage;

Beispiel

-- Point DuckLineage at a running OpenLineage backend (e.g. Marquez at localhost:5000)
SET duck_lineage_url          = 'http://localhost:5000/api/v1/lineage';
-- SET duck_lineage_namespace = 'my-data-warehouse';
-- SET duck_lineage_api_key   = 'your-api-key';
-- SET duck_lineage_debug     = true;

-- Run any query — lineage is captured automatically, no query changes required.
CREATE TABLE greetings (id INTEGER, message VARCHAR);
INSERT INTO greetings VALUES (1, 'Hello'), (2, 'World');

-- Derived table — column-level lineage links shouted.message -> greetings.message.
CREATE TABLE shouted AS
    SELECT id, upper(message) AS message FROM greetings;

SELECT * FROM shouted;

-- START/COMPLETE events with input/output datasets, schemas, column-level lineage,
-- SQL facet, and row-count statistics are streamed to the OpenLineage backend.

Über duck_lineage

DuckLineage ist eine Open-Source-DuckDB-Erweiterung von Ilum Labs, die die Datenherkunft (Lineage) jeder Abfrage ohne SQL-Änderungen erfasst und OpenLineage-Ereignisse an jedes OpenLineage-kompatible Backend sendet (Marquez, DataHub, Atlan, OpenMetadata und ähnliche). Sie ist darauf ausgelegt, Datenherkunft, Governance und Observability out-of-the-box für eingebettete Analytik, lokale ELT-Pipelines und DuckLake-Katalog-Workloads bereitzustellen.

Die Erweiterung hängt sich in die DuckDB-Optimizer-Pipeline ein, analysiert jeden logischen Query-Plan, extrahiert Ein- und Ausgabe-Datasets zusammen mit ihren Schemas und liefert asynchron strukturierte OpenLineage-Ereignisse über HTTP — sodass die Abfrageperformance nicht durch die Latenz des Lineage-Backends beeinträchtigt wird.

Funktionen:

• Automatische Lineage-Erfassung — läuft als DuckDB-Optimizer-Erweiterung, keine Umschreibung der Abfrage nötig
• Vollständiger OpenLineage-Ereignislebenszyklus START / COMPLETE / FAIL für jede ausgeführte Abfrage
• Extraktion von Ein- und Ausgabe-Datasets aus logischen Query-Plänen
• Schema-Facets (Spaltennamen und -typen) für alle verfolgten Datasets
• Spaltenweises Lineage-Facet auf Ausgabe-Datasets, mit Markierung direkter/indirekter Transformationen über CAST, Aliase, Joins, Aggregation, UNION/INTERSECT/EXCEPT, Fensterfunktionen, CTAS, INSERT INTO SELECT, Datei-Scans (CSV/Parquet), PIVOT und UNNEST
• SQL-Job-Facet an jedem Ereignis (wenn der rohe SQL-String verfügbar ist)
• Output-Statistics-Facet (Zeilenzahl) bei COMPLETE-Ereignissen
• Lifecycle-State-Change-Facet (CREATE, DROP, ALTER, OVERWRITE, RENAME, TRUNCATE)
• Symlinks-Facet zur Identitätsauflösung von Datasets über Katalog-/Storage-Namen
• Dateibasierte Quellenverfolgung für read_csv, read_parquet und COPY TO
• DuckLake-Katalogunterstützung mit automatisch aus dem Katalog-DATA_PATH aufgelöstem Namespace
• processing_engine-, dataSource- und catalog-Facets für reichere Backend-Visualisierung
• Asynchrone Ereigniszustellung über einen Hintergrund-Worker-Thread
• Exponential-Backoff-Retry mit konfigurierbarer Maximalzahl an Wiederholungen
• Begrenzte In-Memory-Ereigniswarteschlange mit Overflow-Schutz
• API-Key-(Bearer-)Authentifizierung für OpenLineage-Backends
• Parent-Run-Facet aus OPENLINEAGE_PARENT_*-Umgebungsvariablen, sodass DuckDB-Abfragen sauber als Child-Runs von Airflow, Dagster, Prefect oder jedem OpenLineage-fähigen Orchestrator verknüpft werden
• Konfigurierbare Dataset-Präfix-Filterung, um Lineage für interne/System-Datasets zu unterdrücken
• Debug-Logging-Modus, der emittierte JSON-Ereignisse auf die Konsole schreibt

Verfolgte Operationen:

• INSERT, UPDATE, DELETE, MERGE
• CREATE TABLE, CREATE TABLE AS, CREATE VIEW, CREATE INDEX
• DROP, ALTER
• COPY TO
• SELECT (schreibgeschützte Lineage)

Konfiguration (über DuckDB-SET-Anweisungen):

• duck_lineage_url: OpenLineage-Backend-Endpunkt (erforderlich)
• duck_lineage_namespace: Standard-Dataset-Namespace (Standard: duckdb)
• duck_lineage_api_key: Bearer-Token für das Backend (optional)
• duck_lineage_debug: Debug-Logging aktivieren (Standard: false)
• duck_lineage_max_retries: Wiederholungsversuche bei fehlgeschlagenen HTTP-Anfragen (Standard: 3)
• duck_lineage_max_queue_size: maximale Anzahl wartender Ereignisse vor dem Verwerfen (Standard: 10000)
• duck_lineage_timeout: HTTP-Anfrage-Timeout in Sekunden (Standard: 10)
• duck_lineage_exclude_dataset_prefixes: kommagetrennte Dataset-Präfixe, die von der Lineage ausgeschlossen werden

Hinzugefügte Funktionen

Diese Erweiterung fügt keine Funktionen hinzu.

Überladene Funktionen

Diese Erweiterung fügt keine Funktionsüberladungen hinzu.

Hinzugefügte Typen

Diese Erweiterung fügt keine Typen hinzu.

Hinzugefügte Einstellungen