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

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

Коннектор 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

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

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

2. Загрузите JAR-файл в рабочее пространство Databricks:

   • Перейдите в Workspace → Откройте нужную папку
   • Нажмите Upload → Выберите JAR-файл
   • JAR-файл будет сохранён в рабочем пространстве

3. Установите библиотеку на кластер:

   • Перейдите в Compute → Выберите кластер
   • Откройте вкладку Libraries
   • Нажмите Install New
   • Выберите DBFS или Workspace → Перейдите к загруженному JAR-файлу
   • Нажмите Install

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

​

Вариант 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 (рекомендуется)

1. Перейдите в рабочее пространство Databricks:

   • Перейдите в Compute → выберите кластер
   • Откройте вкладку Libraries
   • Нажмите Install New
   • Выберите вкладку Maven

2. Добавьте координаты Maven:

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

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

​

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

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

​

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

Python

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

Scala

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()

​

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

Python

# Запись в 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()

Scala

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 уже настроены secret scopes. Инструкции по настройке см. в документации Databricks по управлению секретами.

​

Особенности 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:

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

​

Примеры

​

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

Python

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()

Scala

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 - Подробная информация о доступе через каталог