Contexto

Para los clientes que tienen herramientas de visualización de datos que no funcionan con el método de compartición de datos de databricks, utilizaremos esta implementación de Python para garantizar una ingesta exitosa.

Introducción

Delta Sharing es un protocolo abierto desarrollado por Databricks para compartir datos de forma segura y en tiempo real entre organizaciones. Permite que un proveedor de datos comparta conjuntos de datos con destinatarios sin requerir que utilicen Databricks ni ninguna plataforma específica.

Esta guía te muestra cómo consumir datos compartidos a través de Delta Sharing e ingerirlos en tu propia base de datos. Proporcionamos un script de referencia Python listo para usar que lee una tabla Delta compartida y la escribe en una base de datos PostgreSQL.

¿Para quién es esto?

Esta guía es para clientes que reciben datos a través de Delta Sharing y desean cargarlos en un sistema que no admita de forma nativa el formato Delta —como PostgreSQL, MySQL, o cualquier base de datos SQL.

Descripción general de la arquitectura

El flujo de ingesta es simple:

No se requiere cuenta de Databricks en el lado del destinatario.

Sin controladores especiales — el script utiliza la librería Python de código abierto delta-sharing.

Tus datos permanecen bajo tu control — una vez ingeridos, los datos residen en tu base de datos.

Requisitos previos

Antes de comenzar, asegúrate de que tienes lo siguiente:

Paso 1: Obtén tu Perfil de Delta Sharing

Tu proveedor de datos (Uberall) te proporcionará un archivo de perfil de Delta Sharing. Es un pequeño archivo JSON con una extensión .share que contiene los detalles de la conexión y el token de autenticación.

El archivo tiene este aspecto:

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

Guarda este archivo en una ubicación segura en tu máquina. Harás referencia a su ruta cuando configures el script.

Importante:

Este archivo contiene un token de portador que otorga acceso a los datos compartidos. Trátalo como una contraseña.

No lo hagas commit en el control de versiones.

Restringe los permisos del archivo para que solo tu usuario pueda leerlo:

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

Si no has recibido tu archivo de perfil, contacta al equipo de Data Engineering de Uberall.

Paso 2 — Clonar el repositorio

Abre una terminal y clona el repositorio:

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

Accede al directorio del proyecto:

cd delta-sharing-code-examples

El repositorio contiene los siguientes archivos:

Paso 3 — Configurar un entorno de Python

Te recomendamos usar un entorno virtual para evitar conflictos con otros proyectos de Python.

Crea y activa un entorno virtual:

# Create the virtual environment
python -m venv venv

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

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

Instala las dependencias requeridas:

pip install -r requirements.txt

Esto instala los siguientes paquetes:

Paso 4 — Configurar una base de datos PostgreSQL

Tienes dos opciones:

Opción A: Usar la configuración Docker incluida (recomendado para pruebas)

Si tienes Docker instalado, el repositorio incluye un compose.yaml que inicia una instancia de PostgreSQL 16 con un único comando.

Inicia la base de datos:

docker compose up -d

Verifica que esté funcionando:

docker compose logs db

Busca database system is ready to accept connections en la salida.

Prueba rápida de conectividad:

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

La instancia de Docker PostgreSQL utiliza los siguientes valores predeterminados:

Estos coinciden con la configuración predeterminada en el script, así que no hay cambios adicionales necesarios.

Cuando termines de hacer pruebas, detén la base de datos con:

# Detener los contenedores (los datos se conservan)
docker compose down

# Detener y eliminar todos los datos
docker compose down -v

Opción B: Usar tu propia instancia de PostgreSQL

Si ya tienes una base de datos PostgreSQL, simplemente anota tus detalles de conexión (host, puerto, base de datos, usuario, contraseña). Los ingresarás en el Paso 5.

Paso 5 — Configurar el Script

Abre delta_sharing_to_postgres.py en cualquier editor de texto. En la parte superior del archivo, encontrarás la sección 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"

Edita los siguientes valores:

Cómo Descubrir las Tablas Disponibles

Si no conoces el nombre exacto de la tabla, puedes ejecutar un script de descubrimiento rápido. Crea un archivo Python temporal o utiliza un shell de 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}")

Esto muestra todas las tablas disponibles para ti. Usa la cadena completa <share>.<schema>.<table> como valor para DELTA_SHARING_TABLE.

Alternativamente, simplemente ejecuta el script principal — registra todas las tablas disponibles al inicio antes de intentar leer datos.

Modos de Escritura

La configuración WRITE_MODE controla cómo el script maneja los datos existentes en la tabla de destino:

Paso 6 — Ejecutar el script

Asegúrate de que tu entorno virtual esté activado (consulta el Paso 3) y luego ejecuta:

Qué esperar

Una ejecución exitosa genera un resultado similar al siguiente:

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

El script:

Se conecta a Delta Sharing y lista todas las tablas disponibles.

Lee la tabla especificada en memoria.

Muestra una vista previa de las primeras 5 filas.

Escribe los datos en tu instancia de PostgreSQL.

Valida la ingesta contando las filas en la tabla de destino.

Paso 7 — Verificar los datos

Después de una ejecución exitosa, puedes verificar los datos en PostgreSQL.

Usando la línea de comandos (configuración Docker):

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

Usando un cliente SQL (DataGrip, DBeaver, pgAdmin, etc.):

Conéctate a tu instancia PostgreSQL con las mismas credenciales del Paso 5 y luego ejecuta:

-- Conteo de filas
SELECT COUNT(*) FROM public.delta_sharing_data;

-- Vista previa de filas
SELECT * FROM public.delta_sharing_data LIMIT 10;

-- Verificar tipos de columnas
SELECT column_name, data_type
FROM information_schema.columns
WHERE table_schema = 'public' AND table_name = 'delta_sharing_data';

Casos de uso

Actualización completa de instantánea

Establece WRITE_MODE = "replace" y ejecuta el script en una programación (p.ej., diariamente mediante un cron job). Cada ejecución reemplaza toda la tabla con los últimos datos del recurso compartido.

# Ejemplo de entrada en cron: ejecutar cada día a las 2:00 AM
0 2 * * * /path/to/venv/bin/python /path/to/delta_sharing_to_postgres.py

Añadir / acumular datos a lo largo del tiempo

Establece WRITE_MODE = "append" para seguir añadiendo filas en cada ejecución. Esto es útil cuando la tabla compartida contiene nuevos registros (p.ej., eventos diarios o registros de eventos) y deseas crear un historial en tu base de datos.

Nota: Este modo no realiza deduplicación. Si ejecutas el script dos veces con los mismos datos, tendrás filas duplicadas. Considera añadir lógica de deduplicación en tu base de datos o en el script si esto es una preocupación.

Cargar en una base de datos diferente

El script utiliza SQLAlchemy, que admite muchas bases de datos. Para dirigirse a una base de datos diferente, cambia la cadena de conexión en build_pg_connection_string() e instala el controlador apropiado:

Ingerir en un almacén de datos o base de datos en la nube

El mismo enfoque funciona con bases de datos alojadas en la nube (Amazon RDS, Google Cloud SQL, Azure Database for PostgreSQL, etc.). Simplemente actualiza los parámetros de conexión para que apunten a tu instancia en la nube.

Guía de personalización

El script es intencionalmente simple y está pensado para adaptarse a tus necesidades. A continuación se muestran modificaciones comunes.

Filtrar o transformar datos antes de cargar

Después de leer los datos, puedes manipular el DataFrame de Pandas antes de escribirlo en la base de datos. Por ejemplo, para mantener solo columnas específicas:

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)

Ingesta incremental (cargar solo datos nuevos)

Si la tabla compartida tiene una columna de marca de tiempo o fecha, puedes filtrar para cargar solo registros nuevos:

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

Cargar múltiples tablas

Duplica el bloque de configuración o itera sobre una lista de tablas:

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)

Usar variables de entorno en lugar de valores codificados

Para uso en producción, evita codificar secretos en el script. En su lugar, usa variables de entorno:

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

Luego, establécelas antes de ejecutar:

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

Mejores prácticas de seguridad

Solución de problemas

Soporte

Si encuentras problemas relacionados con:

Los datos compartidos, tokens de acceso o permisos — contacta con el equipo de Uberall Data Engineering.

El script de ingesta — consulta esta guía y el archivo README.md en el repositorio. El script se proporciona como una implementación de referencia; eres responsable de adaptarlo y mantenerlo en tu entorno.