spark_catalog, а таблицы идентифицируются как {catalog name}.{database}.{table}. Благодаря этой
возможности теперь можно добавлять и использовать несколько каталогов в одном приложении Spark.
Коннектор ClickHouse Spark поддерживает два варианта доступа: Catalog API и TableProvider API (доступ на основе формата). Понимание различий между ними поможет выбрать подходящий вариант для вашего сценария использования.
- Java 8 или 17 (для Spark 4.0 требуется Java 17 и выше)
- Scala 2.12 или 2.13 (Spark 4.0 поддерживает только Scala 2.13)
- Apache Spark 3.3, 3.4, 3.5 или 4.0
Для интеграции ClickHouse со Spark доступно несколько вариантов установки, подходящих для разных конфигураций проекта.
Вы можете добавить коннектор ClickHouse Spark как зависимость напрямую в файл сборки проекта (например, в
pom.xml
для Maven или build.sbt для SBT).
Либо можно поместить необходимые JAR-файлы в каталог $SPARK_HOME/jars/ или передать их напрямую как параметр Spark
с помощью флага --jars в команде spark-submit.
Оба подхода позволяют сделать коннектор ClickHouse доступным в вашей среде Spark.
- Maven
- Gradle
- SBT
- Spark SQL/Shell CLI
Эти параметры можно задать одним из следующих способов:
- Отредактировать/создать
spark-defaults.conf. - Передать конфигурацию в команду
spark-submit(или в команды CLIspark-shell/spark-sql). - Добавить конфигурацию при инициализации контекста.
- Python
- Scala
- Java
- Python
- Scala
- Java
- Engine: Если параметр не указан, по умолчанию используется
MergeTree(). Вы можете задать другой движок с помощью параметраengine(например,ReplacingMergeTree(),SummingMergeTree()и т. д.) - ORDER BY: Обязательно — при создании новой таблицы необходимо явно указать параметр
order_by. Коннектор проверяет, что все указанные столбцы существуют в схеме. - Поддержка Nullable-ключей: Автоматически добавляет
settings.allow_nullable_key=1, если ORDER BY содержит столбец с типом Nullable
- Python
- Scala
- Java
Эти параметры используются, если таблица не существует и её нужно создать:
- Параметр
order_byобязателен при создании новой таблицы. Все указанные столбцы должны существовать в схеме. ** Автоматически устанавливается в1, если ORDER BY содержит столбец с типом Nullable и параметр не задан явно.
append: Добавляет данные в существующую таблицуoverwrite: Заменяет все данные в таблице (предварительно очищает таблицу)
- Python
- Scala
- Java
allow_nullable_key, index_granularity, а также другие параметры на уровне таблицы и запроса. Они отличаются от параметров коннектора (например, host, database, table), которые определяют, как коннектор подключается к ClickHouse.
При работе с TableProvider API используйте для параметров формат settings.<key>:
- Python
- Scala
- Java
spark.sql.catalog.<catalog_name>.option.<key>:
- Java
- Scala
- Python
- Spark SQL
- Java
- Scala
- Python
- Spark SQL
При использовании Spark SQL за один раз можно выполнить только один оператор.
Поддержка VariantType доступна в Spark 4.0+ и требует ClickHouse 25.3+ с включенными экспериментальными типами JSON/Variant.
VariantType в Spark для работы с полуструктурированными данными. VariantType сопоставляется с типами ClickHouse JSON и Variant, что позволяет эффективно хранить данные с гибкой схемой и выполнять по ним запросы.
Этот раздел посвящен исключительно сопоставлению и использованию VariantType. Полный обзор всех поддерживаемых типов данных см. в разделе Поддерживаемые типы данных.
При чтении из ClickHouse столбцы
JSON и Variant автоматически преобразуются в VariantType Spark:
- Scala
- Python
- Java
- Scala
- Python
- Java
variant_types не указано, для столбца по умолчанию используется тип JSON в ClickHouse, который принимает только объекты JSON:
variant_types:
Variant() можно использовать следующие типы ClickHouse:
- Примитивные типы:
String,Int8,Int16,Int32,Int64,UInt8,UInt16,UInt32,UInt64,Float32,Float64,Bool - Массивы:
Array(T), где T — любой поддерживаемый тип, включая вложенные массивы - JSON:
JSONдля хранения объектов JSON
VariantType. При необходимости это поведение можно изменить, чтобы считывать их как строки:
- Scala
- Python
- Java
Настройте формат записи:
- Используйте тип JSON для данных только в формате JSON: Если вы храните только объекты JSON, используйте тип JSON по умолчанию (без свойства
variant_types) - Явно указывайте типы: При использовании
Variant()явно перечислите все типы, которые планируете хранить - Включите экспериментальные возможности: Убедитесь, что в ClickHouse включен параметр
allow_experimental_json_type = 1 - Используйте формат JSON для записи: Для данных VariantType рекомендуется формат JSON, так как он обеспечивает лучшую совместимость
- Учитывайте шаблоны запросов: Типы JSON/Variant поддерживают в ClickHouse запросы по путям JSON для эффективной фильтрации
- Подсказки для столбцов для повышения производительности: При использовании полей JSON в ClickHouse добавление подсказок для столбцов повышает производительность запросов. В настоящее время добавление подсказок для столбцов через Spark не поддерживается. Отслеживать эту возможность можно в GitHub issue #497.
- Scala
- Python
- Java
Использование конфигураций: это параметры конфигурации на уровне Spark, которые применяются как к Catalog API, так и к TableProvider API. Их можно задать двумя способами:
-
Глобальная конфигурация Spark (применяется ко всем операциям):
-
Переопределение для отдельной операции (только для TableProvider API — может переопределять глобальные настройки):
spark-defaults.conf или при создании сеанса Spark.
В этом разделе описывается сопоставление типов данных между Spark и ClickHouse. В таблицах ниже приведена краткая справка
по преобразованию типов данных при чтении из ClickHouse в Spark и при вставке данных из Spark в ClickHouse.
Если вы хотите внести вклад в проект или сообщить о проблеме, мы будем рады вашей помощи!
Посетите наш репозиторий GitHub, чтобы создать issue, предложить
улучшения или отправить pull request.
Мы приветствуем ваш вклад! Перед началом работы ознакомьтесь с рекомендациями по участию в репозитории.
Спасибо, что помогаете улучшать наш коннектор ClickHouse Spark!