Superset sur ClickHouse

Ce guide décrit la configuration manuelle complète de tous les jeux de données, graphiques et tableaux de bord ClickHouse dans Superset. Suivez-le pour comprendre le rôle et la construction de chaque visualisation.

Vous souhaitez aller directement au résultat ? Exécutez le script d’importation pour tout créer automatiquement :

source .env && source .clickhouse_state
bash superset/add_clickhouse_connection.sh

Le script crée en une seule fois la connexion, les 7 jeux de données, les 18 graphiques et les 4 tableaux de bord. Utilisez ce guide comme référence ou pour reconstruire des éléments séparément.

Important — identifiants fictifs dans superset/dashboards/dashboard_export_*.zip.

Dans le fichier ZIP de tableau de bord enregistré, les valeurs de databases/*.yaml sont remplacées par des valeurs fictives :

sqlalchemy_uri: clickhousedb://default:XXXXXXXXXX@your-instance.clickhouse.cloud:8443/analytics?secure=true

• Importation automatique (add_clickhouse_connection.sh) — fonctionne sans modification. Avant l’envoi au point d’entrée d’importation, le script réécrit la valeur sqlalchemy_uri dans le ZIP avec ${CLICKHOUSE_HOST} / ${CLICKHOUSE_USER} / ${CLICKHOUSE_PASSWORD} issus de votre .env. L’hôte fictif n’atteint donc jamais Superset.
• Importation manuelle dans l’interface Superset — la base importée est créée avec your-instance.clickhouse.cloud et ne peut pas se connecter. Après l’importation, ouvrez Settings → Database Connections → Edit, puis remplacez sqlalchemy_uri par votre véritable URI ClickHouse Cloud, par exemple clickhousedb://default:<PASSWORD>@<your-host>.clickhouse.cloud:8443/analytics?secure=true.
• Nouvelle exportation de vos propres tableaux de bord — Superset inscrit votre véritable hôte ClickHouse dans l’exportation. Avant d’ajouter le fichier au dépôt, remplacez à nouveau l’hôte par your-instance.clickhouse.cloud afin de ne pas divulguer l’identifiant de votre service dans l’historique git.

Prérequis : la couche analytique est alimentée, après dbt run à l’étape 7.3, et le dictionnaire existe, après scripts/04_create_dictionary.sql à l’étape 7.4.

Étape 0 — Enregistrer la connexion ClickHouse

1. Connectez-vous à Superset sur http://localhost:8088 (admin / admin).

2. Ouvrez Settings → Database Connections.

3. Cliquez sur + Database.

4. Sélectionnez ClickHouse Connect dans la liste.

5. Renseignez les champs :

   Champ	Valeur
   Display Name	NYC Taxi — ClickHouse Cloud
   Host	le nom d’hôte ClickHouse Cloud indiqué dans .clickhouse_state
   Port	8443
   Database	analytics
   Username	default
   Password	votre mot de passe ClickHouse Cloud
   SSL	activé

6. Cliquez sur Test Connection et vérifiez que la bannière verte de réussite apparaît.

7. Cliquez sur Connect.

Partie 1 — Créer les jeux de données

Jeu de données 1 — fact_trips (table)

Utilisé par : Operations Command Center, Executive Weekly Report, Driver Quality Analytics et Capabilities Showcase

1. Ouvrez Datasets → + Dataset.
2. Définissez Database sur NYC Taxi — ClickHouse Cloud, Schema sur analytics et Table sur fact_trips.
3. Cliquez sur Add Dataset and Create Chart, puis quittez la page : le jeu de données est enregistré.

Jeu de données 2 — agg_hourly_zone_trips (table)

Utilisé par : Operations Command Center et Executive Weekly Report

1. Ouvrez Datasets → + Dataset.
2. Définissez Database sur NYC Taxi — ClickHouse Cloud, Schema sur analytics et Table sur agg_hourly_zone_trips.
3. Cliquez sur Save.

Jeu de données 3 — CH Approx Unique Trips (uniqHLL12) (virtuel)

Utilisé par : Capabilities Showcase — illustre le décompte approximatif avec uniqHLL12() par rapport au décompte exact avec uniq().

1. Ouvrez Datasets → + Dataset.
2. Cliquez sur Switch to SQL Lab, ou sélectionnez l’onglet Virtual.
3. Définissez Database sur NYC Taxi — ClickHouse Cloud.
4. Collez le SQL :

SELECT
  toDate(pickup_at)                                                     AS day,
  uniq(trip_id)                                                         AS exact_unique_trips,
  uniqHLL12(trip_id)                                                    AS approx_unique_trips,
  round(
    abs(uniq(trip_id) - uniqHLL12(trip_id)) / uniq(trip_id) * 100, 2
  )                                                                     AS pct_error
FROM analytics.fact_trips FINAL
WHERE pickup_at >= today() - INTERVAL 30 DAY
GROUP BY day
ORDER BY day

5. Nommez-le CH Approx Unique Trips (uniqHLL12), puis cliquez sur Save.

Jeu de données 4 — CH Cohort Retention (virtuel)

Utilisé par : Capabilities Showcase — illustre les fonctions de fenêtrage (AVG(...) OVER (...)) pour calculer le chiffre d’affaires glissant par arrondissement.

1. Ouvrez Datasets → + Dataset → Virtual.
2. Définissez Database sur NYC Taxi — ClickHouse Cloud.
3. Collez le SQL :

SELECT
  week,
  pickup_borough,
  trips,
  revenue,
  round(avg(revenue) OVER (
    PARTITION BY pickup_borough
    ORDER BY week
    ROWS BETWEEN 3 PRECEDING AND CURRENT ROW
  ), 2) AS rolling_4wk_avg_revenue
FROM (
  SELECT
    toStartOfWeek(pickup_at)       AS week,
    pickup_borough,
    count()                        AS trips,
    round(sum(fare_amount_usd), 2) AS revenue
  FROM analytics.fact_trips FINAL
  GROUP BY week, pickup_borough
)
ORDER BY week DESC, revenue DESC
LIMIT 100

4. Nommez-le CH Cohort Retention, puis cliquez sur Save.

Jeu de données 5 — CH Fare Percentiles (quantileTDigest) (virtuel)

Utilisé par : Capabilities Showcase — illustre quantileTDigest() comme fonction de centile native de ClickHouse.

1. Ouvrez Datasets → + Dataset → Virtual.
2. Définissez Database sur NYC Taxi — ClickHouse Cloud.
3. Collez le SQL :

SELECT
  vendor_name,
  quantileTDigest(0.5)(fare_amount_usd)  AS p50_fare,
  quantileTDigest(0.95)(fare_amount_usd) AS p95_fare,
  quantileTDigest(0.99)(fare_amount_usd) AS p99_fare,
  count()                                AS trip_count
FROM analytics.fact_trips FINAL
GROUP BY vendor_name
ORDER BY vendor_name

4. Nommez-le CH Fare Percentiles (quantileTDigest), puis cliquez sur Save.

Jeu de données 6 — CH Sampling Demo (virtuel)

Utilisé par : Capabilities Showcase — illustre l’échantillonnage rand() % N par rapport à un parcours complet, en comparant leur précision.

1. Ouvrez Datasets → + Dataset → Virtual.
2. Définissez Database sur NYC Taxi — ClickHouse Cloud.
3. Collez le SQL :

SELECT
  'Full Scan'              AS method,
  count()                  AS trip_count,
  round(avg(fare_amount_usd), 4) AS avg_fare
FROM analytics.fact_trips FINAL
UNION ALL
SELECT
  '~10% (rand() % 10 = 0)' AS method,
  count() * 10              AS trip_count_est,
  round(avg(fare_amount_usd), 4) AS avg_fare
FROM analytics.fact_trips FINAL
WHERE rand() % 10 = 0

4. Nommez-le CH Sampling Demo, puis cliquez sur Save.

Jeu de données 7 — CH Zone Dict Lookup (virtuel)

Utilisé par : Capabilities Showcase — illustre dictGet() pour enrichir une dimension sans aucun JOIN.

Nécessite : le dictionnaire analytics.taxi_zones_dict de l’étape 7.4, créé avec scripts/04_create_dictionary.sql.

1. Ouvrez Datasets → + Dataset → Virtual.
2. Définissez Database sur NYC Taxi — ClickHouse Cloud.
3. Collez le SQL :

SELECT
  dictGet('analytics.taxi_zones_dict', 'borough', toUInt16(pickup_location_id)) AS borough,
  dictGet('analytics.taxi_zones_dict', 'zone',    toUInt16(pickup_location_id)) AS zone,
  count()                                                                        AS trips,
  round(avg(fare_amount_usd), 2)                                                 AS avg_fare
FROM default.trips_raw
WHERE pickup_at >= today() - INTERVAL 7 DAY
GROUP BY borough, zone
ORDER BY trips DESC

4. Nommez-le CH Zone Dict Lookup, puis cliquez sur Save.

Ce jeu de données lit default.trips_raw, la table brute, plutôt que analytics.fact_trips, afin de montrer le fonctionnement du dictionnaire directement dans la couche source, sans prétraitement.

Partie 2 — Créer les graphiques

Créez les graphiques depuis Charts → + Chart : sélectionnez le jeu de données, choisissez le type de graphique, configurez les champs, puis cliquez sur Save en utilisant exactement le nom indiqué.

Tableau de bord 1 — CH Operations Command Center

Graphique : CH Total Trips Today

Enregistrez-le sous CH Total Trips Today.

Graphique : CH Revenue Today

Enregistrez-le sous CH Revenue Today.

Graphique : CH Trip Volume by Hour (24h)

Enregistrez-le sous CH Trip Volume by Hour (24h).

Graphique : CH Revenue by Zone (Top 10)

Enregistrez-le sous CH Revenue by Zone (Top 10).

Tableau de bord 2 — CH Executive Weekly Report

Graphique : CH Daily Revenue (7 days)

Enregistrez-le sous CH Daily Revenue (7 days).

Graphique : CH Top Zones by Revenue

Enregistrez-le sous CH Top Zones by Revenue.

Graphique : CH Payment Distribution

Enregistrez-le sous CH Payment Distribution.

Graphique : CH Avg Fare by Vendor

Enregistrez-le sous CH Avg Fare by Vendor.

Tableau de bord 3 — CH Driver Quality Analytics

Graphique : CH Rating Distribution

Enregistrez-le sous CH Rating Distribution.

Graphique : CH High-Rated Driver Revenue

Enregistrez-le sous CH High-Rated Driver Revenue.

Graphique : CH Avg Fare by Driver Rating

Enregistrez-le sous CH Avg Fare by Driver Rating.

Graphique : CH Top Drivers Leaderboard

Enregistrez-le sous CH Top Drivers Leaderboard.

Tableau de bord 4 — CH Capabilities Showcase

Graphique : CH Recent Trips (fact_trips)

Enregistrez-le sous CH Recent Trips (fact_trips).

Graphique : CH Fare Percentiles (quantileTDigest)

Enregistrez-le sous CH Fare Percentiles (quantileTDigest).

Graphique : CH Approx vs Exact Unique Trips (uniqHLL12)

Enregistrez-le sous CH Approx vs Exact Unique Trips (uniqHLL12).

Graphique : CH Sampling Accuracy Demo (SAMPLE 0.1)

Enregistrez-le sous CH Sampling Accuracy Demo (SAMPLE 0.1).

Graphique : CH Zone Lookup via Dictionary (dictGet)

Enregistrez-le sous CH Zone Lookup via Dictionary (dictGet).

Graphique : CH Weekly Revenue Trend (window functions)

Enregistrez-le sous CH Weekly Revenue Trend (window functions).

Partie 3 — Assembler les tableaux de bord

Pour chaque tableau de bord :

1. Ouvrez Dashboards → + Dashboard.
2. Saisissez le titre.
3. Cliquez sur Save, puis sur Edit Dashboard.
4. Depuis le volet droit, faites glisser chaque graphique sur le canevas.
5. Cliquez sur Save lorsque vous avez terminé.

CH — Operations Command Center

Titre : CH — Operations Command Center

CH — Executive Weekly Report

Titre : CH — Executive Weekly Report

CH — Driver Quality Analytics

Titre : CH — Driver Quality Analytics

CH — Capabilities Showcase

Titre : CH — Capabilities Showcase

Vérification

Après avoir terminé la troisième partie, ouvrez http://localhost:8088. Sous Dashboards, vous devez voir sept tableaux de bord : les trois tableaux de bord Snowflake créés pendant la première partie, et quatre dont le nom commence par CH —.

Résolution des problèmes

fact_trips ou agg_hourly_zone_trips introuvable Exécutez d’abord dbt run, à l’étape 7.3.

dictGet renvoie des chaînes vides Le dictionnaire analytics.taxi_zones_dict n’a pas été créé. Exécutez scripts/04_create_dictionary.sql, à l’étape 7.4.

Le jeu de données virtuel ne renvoie aucune ligne La fenêtre de 30 jours ou de 7 jours de certaines requêtes exige des données récentes. Si toutes vos données migrées sont historiques, remplacez le filtre temporel par une date fixe :

-- Replace: WHERE pickup_at >= today() - INTERVAL 30 DAY
-- With:    WHERE pickup_at >= '2023-01-01'

Erreur 403 du script d’importation Votre cookie de session Superset a expiré. Déconnectez-vous, reconnectez-vous, puis relancez le script.