Integrando o ClickHouse ao Databricks

Suportado pelo ClickHouse

O ClickHouse Spark connector funciona perfeitamente com o Databricks. Este guia aborda a configuração específica da plataforma, a instalação e os padrões de uso no Databricks.

Seleção de API para Databricks

Por padrão, o Databricks usa o Unity Catalog, que bloqueia o registro de catálogo no Spark. Nesse caso, você deve usar a TableProvider API (acesso baseado em formato).

No entanto, se você desativar o Unity Catalog criando um cluster com o modo de acesso No isolation shared, poderá usar a Catalog API. A Catalog API oferece configuração centralizada e integração nativa com o Spark SQL.

Status do Unity Catalog	API recomendada	Observações
Ativado (padrão)	TableProvider API (baseada em formato)	O Unity Catalog bloqueia o registro de catálogo no Spark
Desativado (No isolation shared)	Catalog API	Requer um cluster com o modo de acesso "No isolation shared"

Instalação no Databricks

Opção 1: Fazer upload do JAR pela interface do Databricks

Compile ou baixe o JAR de runtime:

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

Faça upload do JAR para o seu workspace no Databricks:
- Vá para Workspace → navegue até a pasta desejada
- Clique em Upload → selecione o arquivo JAR
- O JAR será armazenado no seu workspace
Instale a biblioteca no seu cluster:
- Vá para Compute → selecione o seu cluster
- Clique na guia Libraries
- Clique em Install New
- Selecione DBFS ou Workspace → navegue até o arquivo JAR enviado
- Clique em Install

Instalando a biblioteca a partir do volume do workspace

Reinicie o cluster para carregar a biblioteca

Opção 2: Instalar via Databricks CLI

# Fazer upload do JAR para o DBFS
databricks fs cp clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}-{{ stable_version }}.jar \
  dbfs:/FileStore/jars/

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

Opção 3: Coordenadas do Maven (recomendado)

Acesse seu workspace do Databricks:
- Vá para Compute → selecione seu cluster
- Clique na guia Libraries
- Clique em Install New
- Selecione a guia Maven
Adicione as coordenadas do Maven:

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

Configuração das bibliotecas Maven no Databricks

Clique em Install e reinicie o cluster para carregar a biblioteca

Usando a TableProvider API

Quando o Unity Catalog está habilitado (padrão), você deve usar a TableProvider API (acesso baseado em formato), pois o Unity Catalog bloqueia o registro de catálogo no Spark. Se você desativou o Unity Catalog usando um cluster com o modo de acesso "No isolation shared", pode usar a Catalog API no lugar.

Leitura de dados

# Ler dados do ClickHouse usando a 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()

# O schema é inferido automaticamente
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()

Gravação de dados

# Grava no ClickHouse — a tabela será criada automaticamente se não existir
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") \  # Obrigatório: especifique o ORDER BY ao criar uma nova tabela
    .option("settings.allow_nullable_key", "1") \  # Obrigatório no ClickHouse Cloud se o ORDER BY tiver colunas Nullable
    .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")  // Obrigatório: especifique o ORDER BY ao criar uma nova tabela
  .option("settings.allow_nullable_key", "1")  // Obrigatório no ClickHouse Cloud se o ORDER BY tiver colunas Nullable
  .mode("append")
  .save()

Considerações específicas do Databricks

Requisitos do modo de acesso

O ClickHouse Spark Connector requer o modo de acesso Dedicated (antes chamado de Single User). O modo de acesso Standard (antes chamado de Shared) não tem suporte quando o Unity Catalog está habilitado, pois o Databricks bloqueia conectores externos do DataSource V2 nessa configuração.

Modo de acesso	Unity Catalog	Suportado
Dedicated (Single User)	Habilitado	✅ Sim
Dedicated (Single User)	Desabilitado	✅ Sim
Standard (Shared)	Habilitado	❌ Não
Standard (Shared)	Desabilitado	✅ Sim

Gerenciamento de segredo

Use os secret scopes do Databricks para armazenar com segurança as credenciais do ClickHouse:

# Acessar secrets
password = dbutils.secrets.get(scope="clickhouse", key="password")

Para obter instruções de configuração, consulte a documentação de gerenciamento de segredo da Databricks.

Conexão com o ClickHouse Cloud

Ao se conectar ao ClickHouse Cloud pelo Databricks:

Use o protocolo HTTPS (protocol: https, http_port: 8443)
Ative o SSL (ssl: true)

Exemplos

Exemplo completo de fluxo de trabalho

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

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

# Ler do 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 os dados
transformed_df = df.filter(col("status") == "active")

# Gravar no 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 o Spark com o conector do ClickHouse
val spark = SparkSession.builder
  .config("spark.jars.packages", "com.clickhouse.spark:clickhouse-spark-runtime-3.4_2.12:0.9.0")
  .getOrCreate()

// Ler do 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 os dados
val transformedDF = df.filter(col("status") === "active")

// Gravar no 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()

Guia do Spark Native Connector - Documentação completa do conector
Documentação da TableProvider API - Detalhes sobre o acesso baseado em formato
Documentação da Catalog API - Detalhes sobre o acesso baseado em catálogo