Hintergrund

Für Kunden, die Data-Visualization-Tools haben, die nicht mit der Datasharing-Methode von Databricks funktionieren, werden wir diese Python-Implementierung verwenden, um eine erfolgreiche Aufnahme zu unterstützen.

Einführung

Delta Sharing ist ein offenes Protokoll von Databricks für sichere Datenschreiberung in Echtzeit zwischen Organisationen. Es ermöglicht es einem Datenanbieter, Datensätze mit Empfängern zu teilen, ohne dass diese Databricks oder eine bestimmte Plattform nutzen müssen.

Diese Anleitung zeigt dir, wie du über Delta Sharing freigegebene Daten verbrauchst und in deine eigene Datenbank aufnimmst. Wir stellen ein gebrauchsfertiges Python-Referenzskript zur Verfügung, das eine gemeinsam genutzte Delta-Tabelle liest und in eine PostgreSQL-Datenbank schreibt.

Für wen ist das gedacht?

Diese Anleitung ist für Kunden gedacht, die Daten über Delta Sharing erhalten und diese in ein System laden möchten, das das Delta-Format nicht nativ unterstützt – wie PostgreSQL, MySQL oder eine beliebige SQL-Datenbank.

Architekturübersicht

Der Ingestion-Ablauf ist unkompliziert:

Kein Databricks-Konto erforderlich auf der Empfängerseite.

Keine speziellen Treiber — das Skript verwendet die Open-Source-Bibliothek delta-sharing.

Deine Daten bleiben unter deiner Kontrolle — die Daten werden nach dem Einlesen in deiner Datenbank gespeichert.

Voraussetzungen

Stelle sicher, dass du folgendes hast, bevor du anfängst:

Schritt 1 – Dein Delta Sharing Profile abrufen

Dein Datenanbieter (Uberall) stellt dir eine Delta Sharing Profile-Datei zur Verfügung. Es handelt sich um eine kleine JSON-Datei mit einer .share Erweiterung, die die Verbindungsdetails und das Authentifizierungstoken enthält.

Die Datei sieht so aus:

{
  "shareCredentialsVersion": 1,
  "endpoint": "https://<databricks-host>/api/2.0/delta-sharing/",
  "bearerToken": "<your-token>"
}

Speichere diese Datei an einem sicheren Ort auf deinem Computer. Du wirst ihren Pfad bei der Konfiguration des Skripts benötigen.

Wichtig:

Diese Datei enthält ein Bearer Token, das Zugriff auf die freigegebenen Daten gewährt. Behandle es wie ein Passwort.

Gib sie nicht in die Versionskontrolle ein.

Schränke die Dateiberechtigungen ein, damit nur dein Benutzer sie lesen kann:

chmod 600 /path/to/your/profile.share

Falls du deine Profile-Datei noch nicht erhalten hast, kontaktiere das Uberall Data Engineering Team.

Schritt 2 — Repository klonen

Öffne ein Terminal und klone das Repository:

git clone https://gitlab.com/momentfeed/uberall/development/ar/data-lake/lakehouse/databricks/delta-sharing-code-examples.git

Navigiere in das Projektverzeichnis:

cd delta-sharing-code-examples

Das Repository enthält die folgenden Dateien:

Schritt 3 – Richte eine Python-Umgebung ein

Wir empfehlen dir, eine virtuelle Umgebung zu verwenden, um Konflikte mit anderen Python-Projekten zu vermeiden.

Erstelle und aktiviere eine virtuelle Umgebung:

# Create the virtual environment
python -m venv venv

# Activate it (Linux / macOS)
source venv/bin/activate

# Activate it (Windows PowerShell)
.\venv\Scripts\Activate.ps1

Installiere die erforderlichen Abhängigkeiten:

pip install -r requirements.txt

Dies installiert die folgenden Pakete:

Schritt 4 – PostgreSQL-Datenbank einrichten

Du hast zwei Möglichkeiten:

Option A: Docker-Setup verwenden (empfohlen zum Testen)

Wenn du Docker installiert hast, enthält das Repository eine compose.yaml, mit der du eine PostgreSQL-16-Instanz mit einem einzelnen Befehl starten kannst.

Starte die Datenbank:

docker compose up -d

Überprüfe, ob sie läuft:

docker compose logs db

Suche in der Ausgabe nach database system is ready to accept connections.

Schneller Verbindungstest:

docker compose exec db psql -U postgres -d testdb -c "SELECT 1;"

Die Docker-PostgreSQL-Instanz verwendet die folgenden Standardwerte:

Diese stimmen mit der Standardkonfiguration im Skript überein, sodass keine zusätzlichen Änderungen erforderlich sind.

Wenn du mit dem Testen fertig bist, fahre die Datenbank herunter:

# Stop containers (data is preserved)
docker compose down

# Stop and delete all data
docker compose down -v

Option B: Deine eigene PostgreSQL-Instanz verwenden

Wenn du bereits eine PostgreSQL-Datenbank hast, notiere dir einfach deine Verbindungsdetails (Host, Port, Datenbank, Benutzer, Passwort). Diese gibst du in Schritt 5 ein.

Schritt 5 – Skript konfigurieren

Öffne delta_sharing_to_postgres.py in einem beliebigen Texteditor. Am Anfang der Datei findest du den Abschnitt USER CONFIGURATION:

# =============================================================================
# USER CONFIGURATION — Edit the values below to match your environment.
# =============================================================================

DELTA_SHARING_PROFILE_PATH = "/path/to/your/profile.share"
DELTA_SHARING_TABLE = "<share_name>.<schema_name>.<table_name>"

PG_HOST = "localhost"
PG_PORT = 5432
PG_DATABASE = "testdb"
PG_USER = "postgres"
PG_PASSWORD = "example"

PG_TARGET_SCHEMA = "public"
PG_TARGET_TABLE = "delta_sharing_data"

WRITE_MODE = "replace"

Bearbeite die folgenden Werte:

Verfügbare Tabellen entdecken

Falls du den genauen Tabellennamen nicht kennst, kannst du ein kurzes Discovery-Skript ausführen. Erstelle eine temporäre Python-Datei oder benutze eine Python-Shell:

import delta_sharing

client = delta_sharing.SharingClient("/path/to/your/profile.share")

for table in client.list_all_tables():
    print(f"{table.share}.{table.schema}.{table.name}")

Dies zeigt alle Tabellen, auf die du Zugriff hast. Verwende die vollständige <share>.<schema>.<table>-Zeichenkette als Wert für DELTA_SHARING_TABLE.

Du kannst auch einfach das Hauptskript ausführen – es protokolliert beim Start alle verfügbaren Tabellen, bevor es versucht, Daten zu lesen.

Schreibmodi

Die WRITE_MODE-Einstellung kontrolliert, wie das Skript mit vorhandenen Daten in der Zieltabelle umgeht:

Schritt 6 – Skript ausführen

Stelle sicher, dass deine virtuelle Umgebung aktiviert ist (siehe Schritt 3), und führe dann folgendes aus:

Was du erwarten kannst

Eine erfolgreiche Ausführung erzeugt eine Ausgabe ähnlich wie die folgende:

2026-02-20 17:20:00,000 [INFO] ============================================================
2026-02-20 17:20:00,000 [INFO] Delta Sharing to PostgreSQL — Ingestion Script
2026-02-20 17:20:00,000 [INFO] ============================================================
2026-02-20 17:20:00,001 [INFO] Loading Delta Sharing profile from: ./config.share
2026-02-20 17:20:00,002 [INFO] Available shares and tables:
2026-02-20 17:20:01,500 [INFO]   my_share.analytics.sales_data
2026-02-20 17:20:01,500 [INFO] Reading table: my_share.analytics.sales_data
2026-02-20 17:20:05,000 [INFO] Read 15000 rows and 12 columns.
2026-02-20 17:20:05,001 [INFO] Preview of the data (first 5 rows):
2026-02-20 17:20:05,002 [INFO]
   col_a  col_b  col_c ...
0  ...    ...    ...
1  ...    ...    ...
2026-02-20 17:20:05,100 [INFO] Connecting to PostgreSQL...
2026-02-20 17:20:05,200 [INFO] PostgreSQL connection successful.
2026-02-20 17:20:05,201 [INFO] Writing 15000 rows to public.delta_sharing_data (mode=replace)...
2026-02-20 17:20:08,000 [INFO] Write complete.
2026-02-20 17:20:08,100 [INFO] Validation: public.delta_sharing_data now contains 15000 rows.
2026-02-20 17:20:08,101 [INFO] ============================================================
2026-02-20 17:20:08,101 [INFO] Ingestion completed successfully.
2026-02-20 17:20:08,101 [INFO] ============================================================

Das Skript:

Verbindet sich mit Delta Sharing und listet alle verfügbaren Tabellen auf.

Liest die angegebene Tabelle in den Arbeitsspeicher.

Zeigt eine Vorschau der ersten 5 Zeilen.

Schreibt die Daten in deine PostgreSQL-Instanz.

Validiert die Aufnahme durch Zählen der Zeilen in der Zieltabelle.

Schritt 7 – Daten überprüfen

Nach einem erfolgreichen Durchlauf kannst du die Daten in PostgreSQL überprüfen.

Über die Befehlszeile (Docker-Setup):

docker compose exec db psql -U postgres -d testdb -c "SELECT COUNT(*) FROM public.delta_sharing_data;"

Mit einem SQL-Client (DataGrip, DBeaver, pgAdmin, etc.):

Verbinde dich mit deiner PostgreSQL-Instanz mit den gleichen Anmeldedaten aus Schritt 5 und führe dann aus:

-- Zeilenzahl
SELECT COUNT(*) FROM public.delta_sharing_data;

-- Zeilen anzeigen
SELECT * FROM public.delta_sharing_data LIMIT 10;

-- Spaltendatentypen überprüfen
SELECT column_name, data_type
FROM information_schema.columns
WHERE table_schema = 'public' AND table_name = 'delta_sharing_data';

Anwendungsfälle

Vollständige Snapshot-Aktualisierung

Stelle WRITE_MODE = "replace" ein und führe das Skript nach einem Zeitplan aus (z. B. täglich über einen Cron-Job). Bei jedem Durchlauf werden alle Tabellendaten durch die neuesten Daten aus dem Share ersetzt.

# Beispiel-Cron-Eintrag: täglich um 2:00 Uhr ausführen
0 2 * * * /path/to/venv/bin/python /path/to/delta_sharing_to_postgres.py

Anhängen / Daten im Laufe der Zeit sammeln

Stelle WRITE_MODE = "append" ein, um bei jedem Durchlauf neue Zeilen hinzuzufügen. Das ist praktisch, wenn die gemeinsam genutzte Tabelle neue Datensätze enthält (z. B. täglich neue Ereignisse oder Logs) und du eine Historie in deiner Datenbank aufbauen möchtest.

Hinweis: Dieser Modus führt keine Deduplizierung durch. Wenn du das Skript zweimal mit den gleichen Daten ausführst, wirst du doppelte Zeilen haben. Erwäge, eine Deduplizierungslogik in deiner Datenbank oder im Skript hinzuzufügen, wenn das ein Problem darstellt.

In eine andere Datenbank laden

Das Skript verwendet SQLAlchemy, das viele Datenbanken unterstützt. Um eine andere Datenbank anzusteuern, ändere die Verbindungszeichenfolge in build_pg_connection_string() und installiere den passenden Treiber:

Aufnahme in ein Data Warehouse oder Cloud-Datenbank

Der gleiche Ansatz funktioniert mit in der Cloud gehosteten Datenbanken (Amazon RDS, Google Cloud SQL, Azure Database for PostgreSQL usw.). Aktualisiere einfach die Verbindungsparameter, um auf deine Cloud-Instanz zu verweisen.

Anpassungsleitfaden

Das Skript ist bewusst einfach gestaltet und soll an deine Anforderungen angepasst werden. Hier sind häufige Änderungen.

Daten vor dem Laden filtern oder transformieren

Nach dem Auslesen der Daten kannst du den Pandas DataFrame manipulieren, bevor du ihn in die Datenbank schreibst. Um zum Beispiel nur bestimmte Spalten zu behalten:

df = read_delta_sharing_table(DELTA_SHARING_PROFILE_PATH, DELTA_SHARING_TABLE)

# Keep only the columns you need
df = df[["column_a", "column_b", "column_c"]]

# Rename columns to match your schema
df = df.rename(columns={"column_a": "id", "column_b": "name"})

# Filter rows
df = df[df["status"] == "active"]

ingest_to_postgres(df, connection_string, PG_TARGET_SCHEMA, PG_TARGET_TABLE, WRITE_MODE)

Inkrementelles Laden (nur neue Daten)

Wenn die gemeinsame Tabelle eine Spalte für Zeitstempel oder Datum hat, kannst du filtern, um nur neue Datensätze zu laden:

df = read_delta_sharing_table(DELTA_SHARING_PROFILE_PATH, DELTA_SHARING_TABLE)

# Only load data from the last 7 days
from datetime import datetime, timedelta
cutoff = datetime.now() - timedelta(days=7)
df = df[df["updated_at"] >= cutoff]

ingest_to_postgres(df, connection_string, PG_TARGET_SCHEMA, PG_TARGET_TABLE, "append")

Mehrere Tabellen laden

Dupliziere den Konfigurationsblock oder durchlaufe eine Liste von Tabellen:

TABLES_TO_INGEST = [
    {"delta_table": "my_share.schema.table_a", "pg_table": "table_a"},
    {"delta_table": "my_share.schema.table_b", "pg_table": "table_b"},
]

for entry in TABLES_TO_INGEST:
    df = read_delta_sharing_table(DELTA_SHARING_PROFILE_PATH, entry["delta_table"])
    ingest_to_postgres(df, connection_string, PG_TARGET_SCHEMA, entry["pg_table"], WRITE_MODE)

Umgebungsvariablen statt hartcodierter Werte verwenden

Für den Produktivbetrieb solltest du keine Geheimnisse im Skript hartcodieren. Verwende stattdessen Umgebungsvariablen:

import os

DELTA_SHARING_PROFILE_PATH = os.environ["DELTA_SHARING_PROFILE_PATH"]
PG_HOST = os.environ.get("PG_HOST", "localhost")
PG_PASSWORD = os.environ["PG_PASSWORD"]

Lege sie dann vor dem Ausführen fest:

export DELTA_SHARING_PROFILE_PATH="./config.share"
export PG_PASSWORD="your_password"
python delta_sharing_to_postgres.py

Sicherheits-Best-Practices

Fehlerbehebung

Support

Falls du auf Probleme stößt, die sich beziehen auf:

Die gemeinsamen Daten, Zugriffstoken oder Berechtigungen – kontaktiere das Uberall Data Engineering Team.

Das Ingestion-Skript – lies diesen Guide und die README.md im Repository. Das Skript wird als Referenz-Implementierung bereitgestellt; du bist dafür verantwortlich, es für deine Umgebung anzupassen und zu warten.