Superset trên ClickHouse

Hướng dẫn này đi qua toàn bộ quá trình thiết lập thủ công mọi dataset, chart và dashboard ClickHouse trong Superset. Hãy theo nó để hiểu mỗi biểu đồ làm gì và được dựng ra sao.

Muốn bỏ qua để đi nhanh? Chạy script import để mọi thứ được tạo tự động:

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

Script tạo kết nối, import toàn bộ 7 dataset, 18 chart và 4 dashboard trong một lần. Hãy dùng hướng dẫn này như tài liệu tham khảo hoặc để dựng lại từng phần riêng lẻ.

Quan trọng — thông tin đăng nhập giả trong superset/dashboards/dashboard_export_*.zip.

ZIP dashboard đã commit có databases/*.yaml bị che thành giá trị giả:

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

• Auto-import (add_clickhouse_connection.sh) — hoạt động nguyên trạng. Script ghi lại sqlalchemy_uri bên trong ZIP bằng ${CLICKHOUSE_HOST} / ${CLICKHOUSE_USER} / ${CLICKHOUSE_PASSWORD} từ .env của bạn trước khi gửi tới endpoint import, nên host giả không bao giờ tới được Superset.
• Import thủ công qua Superset UI — database được import sẽ được tạo với your-instance.clickhouse.cloud và sẽ không kết nối được. Sau khi import, vào Settings → Database Connections → Edit mục đó và thay sqlalchemy_uri bằng URI ClickHouse Cloud thật của bạn (ví dụ clickhousedb://default:<PASSWORD>@<your-host>.clickhouse.cloud:8443/analytics?secure=true).
• Xuất lại dashboard của riêng bạn — Superset nhúng host ClickHouse thật của bạn vào bản export. Trước khi commit, hãy che host trở về your-instance.clickhouse.cloud để định danh service của bạn không lọt vào git history.

Điều kiện tiên quyết: Tầng analytics đã có dữ liệu (dbt run đã xong ở Bước 7.3) và dictionary đã tồn tại (scripts/04_create_dictionary.sql đã xong ở Bước 7.4).

Bước 0 — Đăng Ký Kết Nối ClickHouse

1. Đăng nhập Superset tại http://localhost:8088 (admin / admin).

2. Vào Settings → Database Connections.

3. Bấm + Database.

4. Chọn ClickHouse Connect từ danh sách.

5. Điền:

   Trường	Giá trị
   Display Name	NYC Taxi — ClickHouse Cloud
   Host	hostname ClickHouse Cloud của bạn (từ .clickhouse_state)
   Port	8443
   Database	analytics
   Username	default
   Password	mật khẩu ClickHouse Cloud của bạn
   SSL	bật

6. Bấm Test Connection — xác nhận banner thành công màu xanh.

7. Bấm Connect.

Phần 1 — Tạo Dataset

Dataset 1 — fact_trips (dataset dạng bảng)

Được dùng bởi: Operations Command Center, Executive Weekly Report, Driver Quality Analytics, Capabilities Showcase

1. Vào Datasets → + Dataset.
2. Đặt Database = NYC Taxi — ClickHouse Cloud, Schema = analytics, Table = fact_trips.
3. Bấm Add Dataset and Create Chart → rồi rời khỏi trang — dataset đã được lưu.

Dataset 2 — agg_hourly_zone_trips (dataset dạng bảng)

Được dùng bởi: Operations Command Center, Executive Weekly Report

1. Vào Datasets → + Dataset.
2. Đặt Database = NYC Taxi — ClickHouse Cloud, Schema = analytics, Table = agg_hourly_zone_trips.
3. Bấm Save.

Dataset 3 — CH Approx Unique Trips (uniqHLL12) (virtual)

Được dùng bởi: Capabilities Showcase — minh họa phép đếm gần đúng uniqHLL12() so với uniq() chính xác.

1. Vào Datasets → + Dataset.
2. Bấm Switch to SQL Lab (hoặc chọn tab Virtual).
3. Đặt Database = NYC Taxi — ClickHouse Cloud.
4. Dán 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. Đặt tên nó là CH Approx Unique Trips (uniqHLL12) và bấm Save.

Dataset 4 — CH Cohort Retention (virtual)

Được dùng bởi: Capabilities Showcase — minh họa window function (AVG(...) OVER (...)) cho doanh thu trượt theo borough.

1. Vào Datasets → + Dataset → Virtual.
2. Đặt Database = NYC Taxi — ClickHouse Cloud.
3. Dán 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. Đặt tên nó là CH Cohort Retention và bấm Save.

Dataset 5 — CH Fare Percentiles (quantileTDigest) (virtual)

Được dùng bởi: Capabilities Showcase — minh họa quantileTDigest() như một hàm phân vị native của ClickHouse.

1. Vào Datasets → + Dataset → Virtual.
2. Đặt Database = NYC Taxi — ClickHouse Cloud.
3. Dán 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. Đặt tên nó là CH Fare Percentiles (quantileTDigest) và bấm Save.

Dataset 6 — CH Sampling Demo (virtual)

Được dùng bởi: Capabilities Showcase — minh họa sampling rand() % N so với một lần scan toàn bộ, đối chiếu độ chính xác.

1. Vào Datasets → + Dataset → Virtual.
2. Đặt Database = NYC Taxi — ClickHouse Cloud.
3. Dán 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. Đặt tên nó là CH Sampling Demo và bấm Save.

Dataset 7 — CH Zone Dict Lookup (virtual)

Được dùng bởi: Capabilities Showcase — minh họa dictGet() để làm giàu dimension mà không cần JOIN.

Yêu cầu: dictionary analytics.taxi_zones_dict từ Bước 7.4 (scripts/04_create_dictionary.sql).

1. Vào Datasets → + Dataset → Virtual.
2. Đặt Database = NYC Taxi — ClickHouse Cloud.
3. Dán 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. Đặt tên nó là CH Zone Dict Lookup và bấm Save.

Dataset này đọc từ default.trips_raw (bảng thô) thay vì analytics.fact_trips để cho thấy dictionary hoạt động ngay ở tầng nguồn mà không cần bất kỳ tiền xử lý nào.

Phần 2 — Tạo Chart

Tạo chart qua Charts → + Chart, chọn dataset, chọn loại chart, cấu hình các trường, rồi Save với đúng tên được liệt kê.

Dashboard 1 — CH Operations Command Center

Chart: CH Total Trips Today

Lưu với tên CH Total Trips Today.

Chart: CH Revenue Today

Lưu với tên CH Revenue Today.

Chart: CH Trip Volume by Hour (24h)

Lưu với tên CH Trip Volume by Hour (24h).

Chart: CH Revenue by Zone (Top 10)

Lưu với tên CH Revenue by Zone (Top 10).

Dashboard 2 — CH Executive Weekly Report

Chart: CH Daily Revenue (7 days)

Lưu với tên CH Daily Revenue (7 days).

Chart: CH Top Zones by Revenue

Lưu với tên CH Top Zones by Revenue.

Chart: CH Payment Distribution

Lưu với tên CH Payment Distribution.

Chart: CH Avg Fare by Vendor

Lưu với tên CH Avg Fare by Vendor.

Dashboard 3 — CH Driver Quality Analytics

Chart: CH Rating Distribution

Lưu với tên CH Rating Distribution.

Chart: CH High-Rated Driver Revenue

Lưu với tên CH High-Rated Driver Revenue.

Chart: CH Avg Fare by Driver Rating

Lưu với tên CH Avg Fare by Driver Rating.

Chart: CH Top Drivers Leaderboard

Lưu với tên CH Top Drivers Leaderboard.

Dashboard 4 — CH Capabilities Showcase

Chart: CH Recent Trips (fact_trips)

Lưu với tên CH Recent Trips (fact_trips).

Chart: CH Fare Percentiles (quantileTDigest)

Lưu với tên CH Fare Percentiles (quantileTDigest).

Chart: CH Approx vs Exact Unique Trips (uniqHLL12)

Lưu với tên CH Approx vs Exact Unique Trips (uniqHLL12).

Chart: CH Sampling Accuracy Demo (SAMPLE 0.1)

Lưu với tên CH Sampling Accuracy Demo (SAMPLE 0.1).

Chart: CH Zone Lookup via Dictionary (dictGet)

Lưu với tên CH Zone Lookup via Dictionary (dictGet).

Chart: CH Weekly Revenue Trend (window functions)

Lưu với tên CH Weekly Revenue Trend (window functions).

Phần 3 — Lắp Ghép Dashboard

Với từng dashboard:

1. Vào Dashboards → + Dashboard.
2. Nhập tiêu đề.
3. Bấm Save rồi Edit Dashboard.
4. Từ panel bên phải, kéo từng chart vào canvas.
5. Bấm Save khi xong.

CH — Operations Command Center

Title: CH — Operations Command Center

CH — Executive Weekly Report

Title: CH — Executive Weekly Report

CH — Driver Quality Analytics

Title: CH — Driver Quality Analytics

CH — Capabilities Showcase

Title: CH — Capabilities Showcase

Kiểm Chứng

Sau khi hoàn thành Phần 3, hãy mở http://localhost:8088. Dưới Dashboards, bạn sẽ thấy tổng cộng 7 — 3 dashboard Snowflake (từ phần setup ở Phần 1) và 4 dashboard có tiền tố CH —.

Xử Lý Sự Cố

Không tìm thấy fact_trips hoặc agg_hourly_zone_trips Hãy chạy dbt run trước (Bước 7.3).

dictGet trả về chuỗi rỗng Dictionary analytics.taxi_zones_dict chưa được tạo. Hãy chạy scripts/04_create_dictionary.sql (Bước 7.4).

Virtual dataset không trả về dòng nào Cửa sổ 30 ngày / 7 ngày trong một số truy vấn đòi hỏi dữ liệu gần đây. Nếu dữ liệu di trú của bạn hoàn toàn là dữ liệu lịch sử, hãy thay bộ lọc thời gian bằng một mốc ngày cố định:

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

Lỗi 403 từ script import Cookie phiên Superset của bạn đã hết hạn. Hãy đăng xuất rồi đăng nhập lại, sau đó chạy lại.