Contexte

Pour les clients qui disposent d'outils de visualisation de données qui ne fonctionnent pas avec la méthode de partage de données de databricks, nous utiliserons cette implémentation Python pour soutenir une ingestion réussie.

Introduction

Delta Sharing est un protocole ouvert développé par Databricks pour le partage de données sécurisé et en temps réel entre organisations. Il permet à un fournisseur de données de partager des ensembles de données avec des destinataires sans les obliger à utiliser Databricks ou une plateforme spécifique.

Ce guide vous montre comment consommer des données partagées via Delta Sharing et les intégrer dans votre propre base de données. Nous fournissons un script de référence Python prêt à l'emploi qui lit un tableau Delta partagé et l'écrit dans une base de données PostgreSQL.

Pour qui est ce guide ?

Ce guide s'adresse aux clients qui reçoivent des données via Delta Sharing et souhaitent les charger dans un système qui ne supporte pas nativement le format Delta — comme PostgreSQL, MySQL, ou toute autre base de données SQL.

Aperçu de l'architecture

Le flux d'ingestion est direct :

Aucun compte Databricks requis côté destinataire.

Aucun pilote spécial — le script utilise la bibliothèque Python open-source delta-sharing.

Tes données restent sous ton contrôle — une fois ingérées, les données vivent dans ta base de données.

Prérequis

Avant de commencer, assurez-vous d'avoir ce qui suit :

Étape 1 — Obtenir votre profil Delta Sharing

Votre fournisseur de données (Uberall) vous fournira un fichier de profil Delta Sharing. Il s'agit d'un petit fichier JSON avec une extension .share qui contient les détails de connexion et le jeton d'authentification.

Le fichier ressemble à ceci :

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

Enregistrez ce fichier dans un emplacement sécurisé sur votre machine. Vous référencerez son chemin lors de la configuration du script.

Important :

Ce fichier contient un jeton bearer qui accorde l'accès aux données partagées. Traitez-le comme un mot de passe.

Ne le validez pas dans le contrôle de version.

Restreignez les permissions du fichier pour que seul votre utilisateur puisse le lire :

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

Si vous n'avez pas reçu votre fichier de profil, contactez l'équipe Uberall Data Engineering.

Étape 2 — Cloner le dépôt

Ouvrez un terminal et clonez le dépôt :

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

Accédez au répertoire du projet :

cd delta-sharing-code-examples

Le dépôt contient les fichiers suivants :

Étape 3 — Configurer un environnement Python

Nous vous recommandons d'utiliser un environnement virtuel pour éviter les conflits avec d'autres projets Python.

Créer et activer un environnement virtuel :

# Create the virtual environment
python -m venv venv

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

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

Installer les dépendances requises :

pip install -r requirements.txt

Cela installe les packages suivants :

Étape 4 — Configurer une base de données PostgreSQL

Vous avez deux options :

Option A : Utiliser la configuration Docker incluse (recommandée pour les tests)

Si Docker est installé, le dépôt inclut un compose.yaml qui lance une instance PostgreSQL 16 avec une seule commande.

Démarrer la base de données :

docker compose up -d

Vérifier qu'elle est en cours d'exécution :

docker compose logs db

Recherchez database system is ready to accept connections dans la sortie.

Test de connectivité rapide :

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

L'instance Docker PostgreSQL utilise les valeurs par défaut suivantes :

Celles-ci correspondent à la configuration par défaut dans le script, donc aucune modification supplémentaire n'est nécessaire.

Une fois vos tests terminés, arrêtez la base de données avec :

# Arrêter les conteneurs (les données sont conservées)
docker compose down

# Arrêter et supprimer toutes les données
docker compose down -v

Option B : Utiliser votre propre instance PostgreSQL

Si vous avez déjà une base de données PostgreSQL, notez simplement vos paramètres de connexion (hôte, port, base de données, utilisateur, mot de passe). Vous les entrerez à l'étape 5.

Étape 5 — Configurer le script

Ouvrez delta_sharing_to_postgres.py dans n'importe quel éditeur de texte. En haut du fichier, vous trouverez la section 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"

Modifiez les valeurs suivantes :

Comment découvrir les tables disponibles

Si vous ne connaissez pas le nom exact de la table, vous pouvez exécuter un script de découverte rapide. Créez un fichier Python temporaire ou utilisez un shell Python :

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}")

Ceci affiche toutes les tables qui vous sont accessibles. Utilisez la chaîne complète <share>.<schema>.<table> comme valeur pour DELTA_SHARING_TABLE.

Sinon, exécutez simplement le script principal — il enregistre toutes les tables disponibles au démarrage avant de tenter de lire les données.

Modes d'écriture

Le paramètre WRITE_MODE contrôle la manière dont le script traite les données existantes dans la table cible :

Étape 6 — Exécuter le script

Assurez-vous que votre environnement virtuel est activé (voir Étape 3), puis exécutez :

À quoi s'attendre

Une exécution réussie produit une sortie similaire à celle-ci :

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] ============================================================

Le script :

Se connecte à Delta Sharing et répertorie tous les tableaux disponibles.

Lit le tableau spécifié en mémoire.

Affiche un aperçu des 5 premières lignes.

Écrit les données dans votre instance PostgreSQL.

Valide l'ingestion en comptant les lignes du tableau cible.

Étape 7 — Vérifier les données

Après une exécution réussie, vous pouvez vérifier les données dans PostgreSQL.

Utiliser la ligne de commande (configuration Docker) :

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

Utiliser un client SQL (DataGrip, DBeaver, pgAdmin, etc.) :

Connectez-vous à votre instance PostgreSQL avec les mêmes identifiants de l'étape 5, puis exécutez :

-- Nombre de lignes
SELECT COUNT(*) FROM public.delta_sharing_data;

-- Aperçu des lignes
SELECT * FROM public.delta_sharing_data LIMIT 10;

-- Vérifier les types de colonnes
SELECT column_name, data_type
FROM information_schema.columns
WHERE table_schema = 'public' AND table_name = 'delta_sharing_data';

Cas d'usage

Actualisation complète des données

Définissez WRITE_MODE = "replace" et lancez le script selon un calendrier (par exemple quotidiennement via une tâche cron). À chaque exécution, la table entière est remplacée par les dernières données du partage.

# Exemple d'entrée cron : exécution tous les jours à 2:00 AM
0 2 * * * /path/to/venv/bin/python /path/to/delta_sharing_to_postgres.py

Ajout / accumulation des données au fil du temps

Définissez WRITE_MODE = "append" pour continuer à ajouter des lignes à chaque exécution. C'est utile lorsque la table partagée contient de nouveaux enregistrements (par exemple, des événements ou des journaux quotidiens) et que vous souhaitez constituer un historique dans votre base de données.

Remarque : Ce mode n'effectue pas de déduplications. Si vous lancez le script deux fois avec les mêmes données, vous aurez des lignes en double. Envisagez d'ajouter une logique de déduplication dans votre base de données ou dans le script si cela constitue un problème.

Charger dans une base de données différente

Le script utilise SQLAlchemy, qui prend en charge de nombreuses bases de données. Pour cibler une base de données différente, modifiez la chaîne de connexion dans build_pg_connection_string() et installez le pilote approprié :

Ingérer dans un entrepôt de données ou une base de données cloud

La même approche fonctionne avec les bases de données hébergées dans le cloud (Amazon RDS, Google Cloud SQL, Azure Database for PostgreSQL, etc.). Mettez simplement à jour les paramètres de connexion pour pointer vers votre instance cloud.

Guide de personnalisation

Le script est volontairement simple et conçu pour être adapté à vos besoins. Voici les modifications les plus courantes.

Filtrer ou transformer les données avant le chargement

Après la lecture des données, vous pouvez manipuler le DataFrame Pandas avant de l'écrire dans la base de données. Par exemple, pour ne conserver que des colonnes spécifiques :

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)

Ingestion incrémentielle (charger uniquement les nouvelles données)

Si la table partagée dispose d'une colonne timestamp ou date, vous pouvez filtrer pour charger uniquement les nouveaux enregistrements :

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")

Charger plusieurs tables

Dupliquez le bloc de configuration ou effectuez une boucle sur une liste de tables :

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)

Utiliser des variables d'environnement au lieu de valeurs codées en dur

Pour une utilisation en production, évitez de coder en dur les secrets dans le script. Utilisez plutôt des variables d'environnement :

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"]

Ensuite, définissez-les avant l'exécution :

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

Bonnes pratiques de sécurité

Dépannage

Assistance

Si vous rencontrez des problèmes liés à :

Aux données partagées, aux jetons d'accès ou aux autorisations — contactez l'équipe Uberall Data Engineering.

Au script d'ingestion — consultez ce guide et le fichier README.md du dépôt. Le script est fourni comme implémentation de référence ; vous êtes responsable de son adaptation et de sa maintenance pour votre environnement.