Controlador Databricks

Esta documentación explica la implementación del controlador Databricks y cómo los parámetros de conexión se corresponden con los campos de la interfaz de usuario en la aplicación Gigantic. El controlador se conecta a un SQL Warehouse de Databricks (o a un clúster de propósito general) y trabaja con las tablas de un catálogo y un esquema.

Databricks aparece en el grupo Bases de datos Cloud del selector de drivers y requiere el plan de licencia Cloud.

Parámetros de Conexión

Campo UI	Implementación Técnica	Descripción	Requerido	Valor por Defecto
Host	`host` en la conexión de `@databricks/sql`	Nombre de host del workspace, sin `https://` (por ejemplo `adb-1234567890.1.azuredatabricks.net`)	Sí	Ninguno (debe especificarse)
Ruta HTTP (HTTP Path)	`httpPath` (se envía como `db`)	Ruta HTTP del SQL Warehouse o del clúster (por ejemplo `/sql/1.0/warehouses/abc123`)	Sí	Ninguno (debe especificarse)
Catálogo	`catalog` (se envía como `schema`)	Catálogo de Unity Catalog que contiene las tablas	No	main
Esquema	`owner`	Esquema (base de datos) dentro del catálogo	No	default
Contraseña	`token` (se envía como `password`)	Token de acceso personal de Databricks	Sí	Ninguno (debe especificarse)

Notas:

El formulario no tiene campo Puerto. El controlador se conecta por HTTPS al host en el puerto 443, o al puerto local del túnel SSH cuando el túnel está habilitado.
El campo Usuario de la autenticación "Usuario / Contraseña" se ignora. Solo se usa el campo Contraseña, que debe contener el token de acceso.
Las tablas siempre se referencian como <catálogo>.<esquema>.<tabla>.

Si falta alguno de los valores obligatorios, la conexión falla con uno de estos errores:

Databricks host is required
Databricks HTTP path is required
Databricks access token is required

Detalles Técnicos

El controlador Databricks utiliza la biblioteca oficial de Node.js @databricks/sql (DBSQLClient).

Proceso de conexión:

Abre un cliente con el host, la ruta HTTP y el token
Abre una sesión con el catálogo y el esquema como catálogo y esquema iniciales
Ejecuta SELECT 1 para comprobar la conexión

Descubrimiento del esquema:

Lista las tablas del esquema desde <catálogo>.INFORMATION_SCHEMA.TABLES (tipos TABLE, MANAGED, EXTERNAL y VIEW)
Lee las columnas desde INFORMATION_SCHEMA.COLUMNS
Obtiene el número de filas con count(*) y el tamaño con DESCRIBE DETAIL (sizeInBytes)
Lee las claves primarias desde TABLE_CONSTRAINTS y CONSTRAINT_COLUMN_USAGE. Solo funciona con Unity Catalog; sin él las tablas no tienen clave primaria
Guarda el DDL de cada tabla con SHOW CREATE TABLE
Inspecciona hasta 4 tablas a la vez

Mapeo de tipos:

Tipo Databricks	Tipo Gigantic
`date`, `timestamp`, `timestamp_ntz`	date
`tinyint`, `smallint`, `short`, `int`, `integer`, `long`, `bigint`	number
`float`, `double`, `decimal`, `numeric`	float
`binary`, `varbinary`	buffer
`array`, `map`, `struct`, `json`	object
`boolean` y cualquier otro tipo	string

Proceso de lectura:

Construye un SELECT con el where, el límite y el offset de la regla
Obtiene las filas en lotes del tamaño de lectura del job o de la regla (si no hay ninguno, el batchSize del controlador, 10000) y las envía como stream

Proceso de escritura:

Las inserciones usan sentencias INSERT ... VALUES de varias filas en lotes del tamaño de escritura del job o de la regla (si no hay ninguno, el batchSize del controlador, 10000)
Solo se escriben las columnas que existen en la tabla destino
Los textos se convierten a número en las columnas numéricas; los valores que no se pueden convertir se escriben como NULL
Las actualizaciones y los merge usan MERGE INTO sobre las columnas de la clave primaria. Fallan si la tabla no tiene clave primaria
Si Reintentar al fallar está activado, los lotes que fallan se dividen por la mitad y se reintentan (ver Panorama de Controladores)

Modos de escritura:

Modo de escritura	Comportamiento
Drop	`DROP TABLE IF EXISTS` y vuelve a crear la tabla con el DDL de origen (sin `TBLPROPERTIES`)
Truncate	`TRUNCATE TABLE` antes de cargar
Append	Inserta filas en la tabla existente
Update / Merge	Mantiene la tabla y ejecuta `MERGE INTO` por clave primaria

Si la tabla destino no existe, se crea con el DDL de origen.

Opciones de Autenticación

Tipo de Autenticación	Mapeo UI	Descripción
Ninguno	Sin credenciales	Solo funciona si el token se indica en los Parámetros personalizados (`token`)
Usuario / Contraseña	Campo Contraseña	El campo Contraseña contiene el token de acceso personal. El campo Usuario se ignora
Gestor de Contraseñas	Campos del gestor de contraseñas	El token se obtiene del gestor de contraseñas como contraseña

Soporte de Túnel SSH

Activa ¿Habilitar SSH? para llegar al workspace a través de un servidor SSH. El controlador se conecta entonces por HTTPS al puerto local del túnel, que reenvía la conexión al host en el puerto 443.

Endpoints de API Utilizados

Las conexiones Databricks se utilizan en:

Creación de taps (descubrimiento de la fuente de datos)
Creación de sinks (destino de los datos anonimizados)
Ejecución de pipelines (extracción y carga de datos)

Dependencia del Controlador Node.js

Biblioteca: @databricks/sql
Propósito: conexión con SQL Warehouses y clústeres de Databricks

Parámetros Personalizados

Los Parámetros personalizados (YAML) se combinan con la configuración del controlador, así que pueden fijar o sobrescribir estas claves:

httpPath: /sql/1.0/warehouses/abc123   # Sustituye el campo Ruta HTTP
token: dapi0123456789abcdef            # Token de acceso, sustituye el campo Contraseña
catalog: main                          # Sustituye el campo Catálogo
batchSize: 5000                        # Tamaño de lote si el job o la regla no indican ninguno (10000)

Ejemplos de Configuración

Tabla de Unity Catalog en un esquema propio

catalog: sales

Con el campo Esquema a crm, las tablas se leen como sales.crm.<tabla>.

Tabla de Contenidos