ClickHouse 上的 Superset

本指南带你完整手工搭建 Superset 中所有 ClickHouse 数据集、图表与看板。照它做一遍，你就能理解每个可视化的作用以及它是怎么搭出来的。

想直接跳过？ 运行导入脚本，让一切自动创建：

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

脚本会一次性创建连接，并导入全部 7 个数据集、18 个图表和 4 个看板。你可以把本指南当作参考手册，或用它来重建单个部分。

重要，superset/dashboards/dashboard_export_*.zip 中的占位凭据。

已提交的看板 ZIP 中，databases/*.yaml 已被脱敏为占位值：

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

• 自动导入（add_clickhouse_connection.sh），开箱可用。脚本会在把 ZIP 提交到导入端点之前，用你 .env 中的 ${CLICKHOUSE_HOST} / ${CLICKHOUSE_USER} / ${CLICKHOUSE_PASSWORD} 改写 ZIP 内的 sqlalchemy_uri，因此占位主机名永远不会到达 Superset。
• 通过 Superset 界面手动导入，导入出的数据库会带着 your-instance.clickhouse.cloud 创建，无法连接。导入后前往 Settings → Database Connections → Edit 编辑该条目，把 sqlalchemy_uri 替换为你真实的 ClickHouse Cloud URI（例如 clickhousedb://default:<PASSWORD>@<your-host>.clickhouse.cloud:8443/analytics?secure=true）。
• 重新导出你自己的看板，Superset 会把你真实的 ClickHouse 主机名写进导出文件。提交之前请把主机名改回 your-instance.clickhouse.cloud，以免你的服务标识泄漏进 git 历史。

前置条件： analytics 层已填充数据（第 7.3 步的 dbt run 已完成），并且字典已存在（第 7.4 步的 scripts/04_create_dictionary.sql 已完成）。

第 0 步：注册 ClickHouse 连接

1. 在 http://localhost:8088 登录 Superset（admin / admin）。

2. 前往 Settings → Database Connections。

3. 点击 + Database。

4. 从列表中选择 ClickHouse Connect。

5. 填写：

   字段	值
   Display Name	NYC Taxi — ClickHouse Cloud
   Host	你的 ClickHouse Cloud 主机名（来自 .clickhouse_state）
   Port	8443
   Database	analytics
   Username	default
   Password	你的 ClickHouse Cloud 密码
   SSL	启用

6. 点击 Test Connection，确认出现绿色的成功提示。

7. 点击 Connect。

第 1 部分：创建数据集

数据集 1：fact_trips（表数据集）

使用它的看板：Operations Command Center、Executive Weekly Report、Driver Quality Analytics、Capabilities Showcase

1. 前往 Datasets → + Dataset。
2. 设置 Database = NYC Taxi — ClickHouse Cloud、Schema = analytics、Table = fact_trips。
3. 点击 Add Dataset and Create Chart → 然后离开该页面，数据集已保存。

数据集 2：agg_hourly_zone_trips（表数据集）

使用它的看板：Operations Command Center、Executive Weekly Report

1. 前往 Datasets → + Dataset。
2. 设置 Database = NYC Taxi — ClickHouse Cloud、Schema = analytics、Table = agg_hourly_zone_trips。
3. 点击 Save。

数据集 3：CH Approx Unique Trips (uniqHLL12)（虚拟）

使用它的看板：Capabilities Showcase，演示 uniqHLL12() 近似计数与精确 uniq() 的对比。

1. 前往 Datasets → + Dataset。
2. 点击 Switch to SQL Lab（或选择 Virtual 标签页）。
3. 设置 Database = NYC Taxi — ClickHouse Cloud。
4. 粘贴 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. 命名为 CH Approx Unique Trips (uniqHLL12) 并点击 Save。

数据集 4：CH Cohort Retention（虚拟）

使用它的看板：Capabilities Showcase，演示用窗口函数（AVG(...) OVER (...)）计算按行政区的滚动营收。

1. 前往 Datasets → + Dataset → Virtual。
2. 设置 Database = NYC Taxi — ClickHouse Cloud。
3. 粘贴 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. 命名为 CH Cohort Retention 并点击 Save。

数据集 5：CH Fare Percentiles (quantileTDigest)（虚拟）

使用它的看板：Capabilities Showcase，演示 quantileTDigest() 作为 ClickHouse 原生的百分位函数。

1. 前往 Datasets → + Dataset → Virtual。
2. 设置 Database = NYC Taxi — ClickHouse Cloud。
3. 粘贴 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. 命名为 CH Fare Percentiles (quantileTDigest) 并点击 Save。

数据集 6：CH Sampling Demo（虚拟）

使用它的看板：Capabilities Showcase，演示 rand() % N 抽样与全表扫描的对比，比较准确度。

1. 前往 Datasets → + Dataset → Virtual。
2. 设置 Database = NYC Taxi — ClickHouse Cloud。
3. 粘贴 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. 命名为 CH Sampling Demo 并点击 Save。

数据集 7：CH Zone Dict Lookup（虚拟）

使用它的看板：Capabilities Showcase，演示用 dictGet() 实现零 JOIN 的维度富化。

依赖： 第 7.4 步（scripts/04_create_dictionary.sql）创建的字典 analytics.taxi_zones_dict。

1. 前往 Datasets → + Dataset → Virtual。
2. 设置 Database = NYC Taxi — ClickHouse Cloud。
3. 粘贴 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. 命名为 CH Zone Dict Lookup 并点击 Save。

这个数据集读取的是 default.trips_raw（原始表）而不是 analytics.fact_trips，目的是展示字典在源层无需任何预处理就能生效。

第 2 部分：创建图表

通过 Charts → + Chart 创建图表：选择数据集，选定图表类型，配置各字段，然后用列出的确切名称 Save。

看板 1：CH Operations Command Center

图表：CH Total Trips Today

保存为 CH Total Trips Today。

图表：CH Revenue Today

保存为 CH Revenue Today。

图表：CH Trip Volume by Hour (24h)

保存为 CH Trip Volume by Hour (24h)。

图表：CH Revenue by Zone (Top 10)

保存为 CH Revenue by Zone (Top 10)。

看板 2：CH Executive Weekly Report

图表：CH Daily Revenue (7 days)

保存为 CH Daily Revenue (7 days)。

图表：CH Top Zones by Revenue

保存为 CH Top Zones by Revenue。

图表：CH Payment Distribution

保存为 CH Payment Distribution。

图表：CH Avg Fare by Vendor

保存为 CH Avg Fare by Vendor。

看板 3：CH Driver Quality Analytics

图表：CH Rating Distribution

保存为 CH Rating Distribution。

图表：CH High-Rated Driver Revenue

保存为 CH High-Rated Driver Revenue。

图表：CH Avg Fare by Driver Rating

保存为 CH Avg Fare by Driver Rating。

图表：CH Top Drivers Leaderboard

保存为 CH Top Drivers Leaderboard。

看板 4：CH Capabilities Showcase

图表：CH Recent Trips (fact_trips)

保存为 CH Recent Trips (fact_trips)。

图表：CH Fare Percentiles (quantileTDigest)

保存为 CH Fare Percentiles (quantileTDigest)。

图表：CH Approx vs Exact Unique Trips (uniqHLL12)

保存为 CH Approx vs Exact Unique Trips (uniqHLL12)。

图表：CH Sampling Accuracy Demo (SAMPLE 0.1)

保存为 CH Sampling Accuracy Demo (SAMPLE 0.1)。

图表：CH Zone Lookup via Dictionary (dictGet)

保存为 CH Zone Lookup via Dictionary (dictGet)。

图表：CH Weekly Revenue Trend (window functions)

保存为 CH Weekly Revenue Trend (window functions)。

第 3 部分：组装看板

对每个看板：

1. 前往 Dashboards → + Dashboard。
2. 输入标题。
3. 点击 Save，然后点击 Edit Dashboard。
4. 从右侧面板把每个图表拖到画布上。
5. 完成后点击 Save。

CH — Operations Command Center

标题： CH — Operations Command Center

CH — Executive Weekly Report

标题： CH — Executive Weekly Report

CH — Driver Quality Analytics

标题： CH — Driver Quality Analytics

CH — Capabilities Showcase

标题： CH — Capabilities Showcase

验证

完成第 3 部分后，打开 http://localhost:8088。在 Dashboards 下你应该总共看到 7 个，3 个 Snowflake 看板（来自第 1 部分的搭建）和 4 个以 CH — 为前缀的看板。

故障排查

找不到 fact_trips 或 agg_hourly_zone_trips 请先运行 dbt run（第 7.3 步）。

dictGet 返回空字符串 analytics.taxi_zones_dict 字典尚未创建。请运行 scripts/04_create_dictionary.sql（第 7.4 步）。

虚拟数据集没有返回任何行 某些查询中的 30 天 / 7 天窗口需要近期数据。如果你的迁移数据全是历史数据，请把时间过滤条件换成固定日期：

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

导入脚本报 403 错误 你的 Superset 会话 cookie 已过期。退出登录再重新登录，然后重跑。