Интеграция ClickHouse с Databricks

Поддерживается в ClickHouse

Коннектор ClickHouse Spark без проблем работает с Databricks. В этом руководстве описаны особенности настройки, установки и использования на платформе Databricks.

Выбор API для Databricks

По умолчанию Databricks использует Unity Catalog, который блокирует регистрацию каталога Spark. В этом случае необходимо использовать TableProvider API (доступ на основе формата).

Однако если отключить Unity Catalog, создав кластер с режимом доступа No isolation shared, вместо него можно использовать Catalog API. Catalog API предоставляет централизованную конфигурацию и нативную интеграцию со Spark SQL.

Статус Unity Catalog	Рекомендуемый API	Примечания
Включен (по умолчанию)	TableProvider API (доступ на основе формата)	Unity Catalog блокирует регистрацию каталога Spark
Отключен (No isolation shared)	Catalog API	Требуется кластер с режимом доступа "No isolation shared"

Установка в Databricks

Вариант 1: Загрузка JAR через интерфейс Databricks

Соберите или скачайте runtime JAR-файл:

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

Загрузите JAR-файл в рабочее пространство Databricks:
- Перейдите в Workspace → Откройте нужную папку
- Нажмите Upload → Выберите JAR-файл
- JAR-файл будет сохранён в рабочем пространстве
Установите библиотеку на кластер:
- Перейдите в Compute → Выберите кластер
- Откройте вкладку Libraries
- Нажмите Install New
- Выберите DBFS или Workspace → Перейдите к загруженному JAR-файлу
- Нажмите Install

Установка библиотеки из тома рабочего пространства

Перезапустите кластер, чтобы загрузить библиотеку

Вариант 2: Установите через Databricks CLI

# Загрузить JAR в DBFS
databricks fs cp clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}-{{ stable_version }}.jar \
  dbfs:/FileStore/jars/

# Установить на кластер
databricks libraries install \
  --cluster-id <your-cluster-id> \
  --jar dbfs:/FileStore/jars/clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}-{{ stable_version }}.jar

Вариант 3: координаты Maven (рекомендуется)

Перейдите в рабочее пространство Databricks:
- Перейдите в Compute → выберите кластер
- Откройте вкладку Libraries
- Нажмите Install New
- Выберите вкладку Maven
Добавьте координаты Maven:

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

Нажмите Install и перезапустите кластер, чтобы загрузить библиотеку

Использование TableProvider API

Когда Unity Catalog включен (по умолчанию), необходимо использовать TableProvider API (доступ на основе формата), поскольку Unity Catalog блокирует регистрацию каталога Spark. Если вы отключили Unity Catalog, используя кластер с режимом доступа "No isolation shared", вместо этого можно использовать Catalog API.

Чтение данных

# Чтение данных из ClickHouse с помощью 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()

# Схема определяется автоматически
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()

Запись данных

# Запись в ClickHouse — таблица будет создана автоматически, если её ещё не существует
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") \  # Обязательно: укажите ORDER BY при создании новой таблицы
    .option("settings.allow_nullable_key", "1") \  # Обязательно для ClickHouse Cloud, если ORDER BY содержит столбцы с типом 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")  // Обязательно: укажите ORDER BY при создании новой таблицы
  .option("settings.allow_nullable_key", "1")  // Обязательно для ClickHouse Cloud, если ORDER BY содержит столбцы с типом Nullable
  .mode("append")
  .save()

Особенности Databricks

Требования к режиму доступа

Коннектор ClickHouse Spark требует режима доступа Dedicated (ранее — Single User). Режим доступа Standard (ранее — Shared) не поддерживается при включенном Unity Catalog, поскольку в такой конфигурации Databricks блокирует внешние коннекторы DataSource V2.

Режим доступа	Unity Catalog	Поддерживается
Dedicated (Single User)	Включен	✅ Да
Dedicated (Single User)	Отключен	✅ Да
Standard (Shared)	Включен	❌ Нет
Standard (Shared)	Отключен	✅ Да

Управление секретами

Используйте secret scopes в Databricks для безопасного хранения учетных данных ClickHouse:

# Получение секретов
password = dbutils.secrets.get(scope="clickhouse", key="password")

Инструкции по настройке см. в документации Databricks по управлению секретами.

Подключение к ClickHouse Cloud

При подключении к ClickHouse Cloud из Databricks:

Используйте протокол HTTPS (protocol: https, http_port: 8443)
Включите SSL (ssl: true)

Примеры

Полный пример рабочего процесса

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

# Инициализируем Spark с коннектором ClickHouse
spark = SparkSession.builder \
    .config("spark.jars.packages", "com.clickhouse.spark:clickhouse-spark-runtime-3.4_2.12:0.9.0") \
    .getOrCreate()

# Читаем данные из 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()

# Преобразуем данные
transformed_df = df.filter(col("status") == "active")

# Записываем данные в 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

// Инициализируем Spark с коннектором ClickHouse
val spark = SparkSession.builder
  .config("spark.jars.packages", "com.clickhouse.spark:clickhouse-spark-runtime-3.4_2.12:0.9.0")
  .getOrCreate()

// Читаем данные из 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()

// Преобразуем данные
val transformedDF = df.filter(col("status") === "active")

// Записываем данные в 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()

Руководство по Spark Native Connector - Полная документация по коннектору
Документация по TableProvider API - Подробная информация о доступе на основе формата
Документация по Catalog API - Подробная информация о доступе на основе каталога