Intégration de ClickHouse avec Databricks

Compatible avec ClickHouse

Le ClickHouse Spark Connector s’intègre parfaitement à Databricks. Ce guide présente la configuration, l’installation et les modes d’utilisation propres à la plateforme Databricks.

Sélection de l’API pour Databricks

Par défaut, Databricks utilise Unity Catalog, ce qui empêche l’enregistrement du catalogue Spark. Dans ce cas, vous devez utiliser la TableProvider API (accès basé sur le format).

Toutefois, si vous désactivez Unity Catalog en créant un cluster avec le mode d’accès No isolation shared, vous pouvez utiliser la Catalog API à la place. La Catalog API fournit une configuration centralisée et une intégration native à Spark SQL.

Statut d’Unity Catalog	API recommandée	Remarques
Activé (par défaut)	TableProvider API (accès basé sur le format)	Unity Catalog empêche l’enregistrement du catalogue Spark
Désactivé (No isolation shared)	Catalog API	Nécessite un cluster avec le mode d’accès "No isolation shared"

Installation sur Databricks

Option 1 : téléverser le JAR via l’UI Databricks

Compilez ou téléchargez le JAR d’exécution :

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

Téléversez le JAR dans votre workspace Databricks :
- Accédez à Workspace → Ouvrez le dossier souhaité
- Cliquez sur Upload → Sélectionnez le fichier JAR
- Le JAR sera stocké dans votre workspace
Installez la bibliothèque sur votre cluster :
- Accédez à Compute → Sélectionnez votre cluster
- Cliquez sur l’onglet Libraries
- Cliquez sur Install New
- Sélectionnez DBFS ou Workspace → Accédez au fichier JAR téléversé
- Cliquez sur Install

Installation de la bibliothèque depuis le volume du workspace

Redémarrez le cluster pour charger la bibliothèque

Option 2 : Installer avec la CLI Databricks

# Upload JAR to DBFS
databricks fs cp clickhouse-spark-runtime-{{ spark_binary_version }}_{{ scala_binary_version }}-{{ stable_version }}.jar \
  dbfs:/FileStore/jars/

# Install on 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

Option 3 : Coordonnées Maven (recommandée)

Accédez à votre workspace Databricks :
- Allez dans Compute → Sélectionnez votre cluster
- Cliquez sur l’onglet Libraries
- Cliquez sur Install New
- Sélectionnez l’onglet Maven
Ajoutez les coordonnées Maven :

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

Configuration des bibliothèques Maven dans Databricks

Cliquez sur Install puis redémarrez le cluster pour charger la bibliothèque

Utilisation de l’API TableProvider

Lorsque Unity Catalog est activé (par défaut), vous devez utiliser la TableProvider API (accès basé sur le format), car Unity Catalog bloque l’enregistrement du catalogue dans Spark. Si vous avez désactivé Unity Catalog en utilisant un cluster avec le mode d’accès « No isolation shared », vous pouvez utiliser la Catalog API à la place.

Lecture des données

# Lire des données depuis ClickHouse avec 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()

# Le schéma est inféré automatiquement
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()

Écriture de données

# Écrire dans ClickHouse - la table sera créée automatiquement si elle n'existe pas
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") \  # Obligatoire : spécifiez ORDER BY lors de la création d'une nouvelle table
    .option("settings.allow_nullable_key", "1") \  # Obligatoire pour ClickHouse Cloud si ORDER BY contient des colonnes 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")  // Obligatoire : spécifiez ORDER BY lors de la création d'une nouvelle table
  .option("settings.allow_nullable_key", "1")  // Obligatoire pour ClickHouse Cloud si ORDER BY contient des colonnes Nullable
  .mode("append")
  .save()

Considérations propres à Databricks

Exigences du mode d’accès

Le ClickHouse Spark Connector requiert le mode d’accès Dedicated (anciennement Single User). Le mode d’accès Standard (anciennement Shared) n’est pas pris en charge lorsque Unity Catalog est activé, car Databricks bloque les connecteurs DataSource V2 externes dans cette configuration.

Mode d’accès	Unity Catalog	Pris en charge
Dedicated (Single User)	Activé	✅ Oui
Dedicated (Single User)	Désactivé	✅ Oui
Standard (Shared)	Activé	❌ Non
Standard (Shared)	Désactivé	✅ Oui

Gestion des secrets

Utilisez les secret scopes Databricks pour stocker en toute sécurité les identifiants ClickHouse :

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

Pour les instructions de configuration, consultez la documentation Databricks sur la gestion des secrets.

Connexion à ClickHouse Cloud

Pour vous connecter à ClickHouse Cloud depuis Databricks :

Utilisez le protocole HTTPS (protocol: https, http_port: 8443)
Activez SSL (ssl: true)

Exemples

Exemple complet de workflow

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

# Initialiser Spark avec le connecteur ClickHouse
spark = SparkSession.builder \
    .config("spark.jars.packages", "com.clickhouse.spark:clickhouse-spark-runtime-3.4_2.12:0.9.0") \
    .getOrCreate()

# Lire les données depuis 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()

# Transformer les données
transformed_df = df.filter(col("status") == "active")

# Écrire les données dans 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

// Initialiser Spark avec le connecteur ClickHouse
val spark = SparkSession.builder
  .config("spark.jars.packages", "com.clickhouse.spark:clickhouse-spark-runtime-3.4_2.12:0.9.0")
  .getOrCreate()

// Lire les données depuis 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()

// Transformer les données
val transformedDF = df.filter(col("status") === "active")

// Écrire les données dans 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()

Guide du connecteur natif Spark - Documentation complète du connecteur
Documentation de TableProvider API - Détails de l’accès basé sur le format
Documentation de Catalog API - Détails de l’accès basé sur le catalogue