Integrar ClickHouse con Databricks

Compatible con ClickHouse

El ClickHouse Spark Connector funciona perfectamente con Databricks. Esta guía abarca la configuración, la instalación y los patrones de uso específicos de Databricks.

Selección de API para Databricks

De forma predeterminada, Databricks usa Unity Catalog, que bloquea el registro de catálogos de Spark. En este caso, debe usar la TableProvider API (acceso basado en formato).

Sin embargo, si desactiva Unity Catalog creando un clúster con el modo de acceso No isolation shared, puede usar la Catalog API en su lugar. La Catalog API proporciona una configuración centralizada e integración nativa con Spark SQL.

Estado de Unity Catalog	API recomendada	Notas
Habilitado (predeterminado)	TableProvider API (basada en formato)	Unity Catalog bloquea el registro de catálogos de Spark
Deshabilitado (No isolation shared)	Catalog API	Requiere un clúster con el modo de acceso "No isolation shared"

Instalación en Databricks

Opción 1: Subir el JAR mediante la UI de Databricks

Compila o descarga el JAR de runtime:

clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}-{{ stable_version }}.jar

Sube el JAR a tu espacio de trabajo de Databricks:
- Ve a Espacio de trabajo → navega hasta la carpeta deseada
- Haz clic en Upload → selecciona el archivo JAR
- El JAR se almacenará en tu espacio de trabajo
Instala la biblioteca en tu clúster:
- Ve a Compute → selecciona tu clúster
- Haz clic en la pestaña Libraries
- Haz clic en Install New
- Selecciona DBFS o Espacio de trabajo → navega hasta el archivo JAR que subiste
- Haz clic en Install

Instalación de la biblioteca desde el volumen del espacio de trabajo

Reinicia el clúster para cargar la biblioteca

Opción 2: Instalar con la CLI de Databricks

# Subir JAR a DBFS
databricks fs cp clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}-{{ stable_version }}.jar \
  dbfs:/FileStore/jars/

# Instalar en el clúster
databricks libraries install \
  --cluster-id <your-cluster-id> \
  --jar dbfs:/FileStore/jars/clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}-{{ stable_version }}.jar

Opción 3: Coordenadas de Maven (recomendada)

Ve a tu espacio de trabajo de Databricks:
- Ve a Compute → Selecciona tu clúster
- Haz clic en la pestaña Libraries
- Haz clic en Install New
- Selecciona la pestaña Maven
Agrega las coordenadas de Maven:

com.clickhouse.spark:clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}:{{ stable_version }}

Configuración de bibliotecas Maven en Databricks

Haz clic en Install y reinicia el clúster para cargar la biblioteca

Uso de la TableProvider API

Cuando Unity Catalog está habilitado (de forma predeterminada), debe usar la TableProvider API (acceso basado en formatos), ya que Unity Catalog bloquea el registro del catálogo de Spark. Si ha deshabilitado Unity Catalog usando un clúster con el modo de acceso "No isolation shared", puede usar la Catalog API en su lugar.

Lectura de datos

# Leer datos de ClickHouse mediante TableProvider API
df = spark.read \
    .format("clickhouse") \
    .option("host", "your-clickhouse-cloud-host.clickhouse.cloud") \
    .option("protocol", "https") \
    .option("http_port", "8443") \
    .option("database", "default") \
    .option("table", "events") \
    .option("user", "default") \
    .option("password", dbutils.secrets.get(scope="clickhouse", key="password")) \
    .option("ssl", "true") \
    .load()

# El esquema se infiere automáticamente
df.display()

val df = spark.read
  .format("clickhouse")
  .option("host", "your-clickhouse-cloud-host.clickhouse.cloud")
  .option("protocol", "https")
  .option("http_port", "8443")
  .option("database", "default")
  .option("table", "events")
  .option("user", "default")
  .option("password", dbutils.secrets.get(scope="clickhouse", key="password"))
  .option("ssl", "true")
  .load()

df.show()

Escritura de datos

# Escribir en ClickHouse: la tabla se creará automáticamente si no existe
df.write \
    .format("clickhouse") \
    .option("host", "your-clickhouse-cloud-host.clickhouse.cloud") \
    .option("protocol", "https") \
    .option("http_port", "8443") \
    .option("database", "default") \
    .option("table", "events_copy") \
    .option("user", "default") \
    .option("password", dbutils.secrets.get(scope="clickhouse", key="password")) \
    .option("ssl", "true") \
    .option("order_by", "id") \  # Obligatorio: especifica ORDER BY al crear una tabla nueva
    .option("settings.allow_nullable_key", "1") \  # Obligatorio en ClickHouse Cloud si ORDER BY incluye columnas que admiten NULL
    .mode("append") \
    .save()

df.write
  .format("clickhouse")
  .option("host", "your-clickhouse-cloud-host.clickhouse.cloud")
  .option("protocol", "https")
  .option("http_port", "8443")
  .option("database", "default")
  .option("table", "events_copy")
  .option("user", "default")
  .option("password", dbutils.secrets.get(scope="clickhouse", key="password"))
  .option("ssl", "true")
  .option("order_by", "id")  // Obligatorio: especifica ORDER BY al crear una tabla nueva
  .option("settings.allow_nullable_key", "1")  // Obligatorio en ClickHouse Cloud si ORDER BY incluye columnas que admiten NULL
  .mode("append")
  .save()

Consideraciones específicas de Databricks

Requisitos del modo de acceso

El ClickHouse Spark Connector requiere el modo de acceso Dedicated (antes Single User). El modo de acceso Standard (antes Shared) no es compatible cuando Unity Catalog está habilitado, ya que Databricks bloquea los conectores externos DataSource V2 en esa configuración.

Modo de acceso	Unity Catalog	Compatible
Dedicated (Single User)	Habilitado	✅ Sí
Dedicated (Single User)	Deshabilitado	✅ Sí
Standard (Shared)	Habilitado	❌ No
Standard (Shared)	Deshabilitado	✅ Sí

Gestión de secretos

Use los secret scopes de Databricks para guardar de forma segura las credenciales de ClickHouse:

# Acceder a los secretos
password = dbutils.secrets.get(scope="clickhouse", key="password")

Para obtener instrucciones de configuración, consulta la documentación sobre gestión de secretos de Databricks.

Conexión con ClickHouse Cloud

Al conectarse a ClickHouse Cloud desde Databricks:

Use el protocolo HTTPS (protocol: https, http_port: 8443)
Habilite SSL (ssl: true)

Ejemplos

Ejemplo completo de flujo de trabajo

from pyspark.sql import SparkSession
from pyspark.sql.functions import col

# Inicializar Spark con el conector de ClickHouse
spark = SparkSession.builder \
    .config("spark.jars.packages", "com.clickhouse.spark:clickhouse-spark-runtime-3.4_2.12:0.9.0") \
    .getOrCreate()

# Leer datos de ClickHouse
df = spark.read \
    .format("clickhouse") \
    .option("host", "your-host.clickhouse.cloud") \
    .option("protocol", "https") \
    .option("http_port", "8443") \
    .option("database", "default") \
    .option("table", "source_table") \
    .option("user", "default") \
    .option("password", dbutils.secrets.get(scope="clickhouse", key="password")) \
    .option("ssl", "true") \
    .load()

# Transformar los datos
transformed_df = df.filter(col("status") == "active")

# Escribir en ClickHouse
transformed_df.write \
    .format("clickhouse") \
    .option("host", "your-host.clickhouse.cloud") \
    .option("protocol", "https") \
    .option("http_port", "8443") \
    .option("database", "default") \
    .option("table", "target_table") \
    .option("user", "default") \
    .option("password", dbutils.secrets.get(scope="clickhouse", key="password")) \
    .option("ssl", "true") \
    .option("order_by", "id") \
    .mode("append") \
    .save()

import org.apache.spark.sql.SparkSession
import org.apache.spark.sql.functions.col

// Inicializar Spark con el conector de ClickHouse
val spark = SparkSession.builder
  .config("spark.jars.packages", "com.clickhouse.spark:clickhouse-spark-runtime-3.4_2.12:0.9.0")
  .getOrCreate()

// Leer datos de ClickHouse
val df = spark.read
  .format("clickhouse")
  .option("host", "your-host.clickhouse.cloud")
  .option("protocol", "https")
  .option("http_port", "8443")
  .option("database", "default")
  .option("table", "source_table")
  .option("user", "default")
  .option("password", dbutils.secrets.get(scope="clickhouse", key="password"))
  .option("ssl", "true")
  .load()

// Transformar los datos
val transformedDF = df.filter(col("status") === "active")

// Escribir en ClickHouse
transformedDF.write
  .format("clickhouse")
  .option("host", "your-host.clickhouse.cloud")
  .option("protocol", "https")
  .option("http_port", "8443")
  .option("database", "default")
  .option("table", "target_table")
  .option("user", "default")
  .option("password", dbutils.secrets.get(scope="clickhouse", key="password"))
  .option("ssl", "true")
  .option("order_by", "id")
  .mode("append")
  .save()

Guía del conector nativo de Spark - Documentación completa del conector
Documentación de TableProvider API - Detalles sobre el acceso basado en formato
Documentación de Catalog API - Detalles sobre el acceso basado en catálogo