> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Integre o ClickHouse ao Databricks
# Integrando o ClickHouse ao Databricks
export const ClickHouseSupportedBadge = () => {
return ;
};
export const Image = ({img, alt, size}) => {
return
;
};
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
1. Compile ou [baixe](https://repo1.maven.org/maven2/com/clickhouse/spark/) o JAR de runtime:
```bash theme={null}
clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}-{{ stable_version }}.jar
```
2. 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
3. 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**
4. Reinicie o cluster para carregar a biblioteca
### Opção 2: Instalar via Databricks CLI
```bash theme={null}
# 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 \
--jar dbfs:/FileStore/jars/clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}-{{ stable_version }}.jar
```
### Opção 3: Coordenadas do Maven (recomendado)
1. Acesse seu workspace do Databricks:
* Vá para **Compute** → selecione seu cluster
* Clique na guia **Libraries**
* Clique em **Install New**
* Selecione a guia **Maven**
2. Adicione as coordenadas do Maven:
```text theme={null}
com.clickhouse.spark:clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}:{{ stable_version }}
```
3. 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](/pt-BR/integrations/connectors/data-ingestion/apache-spark/spark-native-connector#register-the-catalog-required) no lugar.
### Leitura de dados
```python theme={null}
# 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()
```
```scala theme={null}
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
```python theme={null}
# 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()
```
```scala theme={null}
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()
```
Este exemplo pressupõe secret scopes já configurados no Databricks. Para instruções de configuração, consulte a [documentação de gerenciamento de segredos](https://docs.databricks.com/aws/en/security/secrets/) do Databricks.
## 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:
```python theme={null}
# 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](https://docs.databricks.com/aws/en/security/secrets/) da Databricks.
### Conexão com o ClickHouse Cloud
Ao se conectar ao ClickHouse Cloud pelo Databricks:
1. Use o **protocolo HTTPS** (`protocol: https`, `http_port: 8443`)
2. Ative o **SSL** (`ssl: true`)
## Exemplos
### Exemplo completo de fluxo de trabalho
```python theme={null}
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()
```
```scala theme={null}
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()
```
## Documentação relacionada
* [Guia do conector nativo do Spark](/pt-BR/integrations/connectors/data-ingestion/apache-spark/spark-native-connector) - Documentação completa do conector
* [Documentação da TableProvider API](/pt-BR/integrations/connectors/data-ingestion/apache-spark/spark-native-connector#using-the-tableprovider-api) - Detalhes do acesso baseado em formato
* [Documentação da Catalog API](/pt-BR/integrations/connectors/data-ingestion/apache-spark/spark-native-connector#register-the-catalog-required) - Detalhes do acesso baseado em catálogo