Superset no ClickHouse

Reconstrução dos dashboards no ClickHouse: sete conjuntos de dados que exercitam uniqHLL12, quantileTDigest, amostragem, funções de janela e dictGet, seguidos de 18 gráficos em quatro dashboards.

Este guia apresenta toda a configuração manual dos conjuntos de dados, gráficos e dashboards do ClickHouse no Superset. Siga-o para entender o que cada visualização faz e como ela é criada.

Quer pular essas etapas? Execute o script de importação para criar tudo automaticamente:
source .env && source .clickhouse_state
bash superset/add_clickhouse_connection.sh
O script cria a conexão e importa os 7 conjuntos de dados, 18 gráficos e 4 dashboards de uma só vez. Use este guia como referência ou para reconstruir elementos específicos.

Importante — credenciais de exemplo em superset/dashboards/dashboard_export_*.zip.

Os arquivos databases/*.yaml do ZIP de dashboards incluído no repositório usam valores de exemplo no lugar das informações reais:
sqlalchemy_uri: clickhousedb://default:XXXXXXXXXX@your-instance.clickhouse.cloud:8443/analytics?secure=true
Importação automática (add_clickhouse_connection.sh) — funciona sem alterações. Antes de enviar o arquivo ao endpoint de importação, o script reescreve sqlalchemy_uri dentro do ZIP usando ${CLICKHOUSE_HOST} / ${CLICKHOUSE_USER} / ${CLICKHOUSE_PASSWORD} de seu .env; assim, o host de exemplo nunca chega ao Superset.

Importação manual pela interface do Superset — o banco importado será criado com your-instance.clickhouse.cloud e não conseguirá se conectar. Após a importação, vá até Settings → Database Connections → Edit e substitua sqlalchemy_uri pela URI real do ClickHouse Cloud (por exemplo, clickhousedb://default:<PASSWORD>@<your-host>.clickhouse.cloud:8443/analytics?secure=true).

Nova exportação de seus próprios dashboards — o Superset incorpora seu host real do ClickHouse na exportação. Antes de fazer commit, substitua novamente o host por your-instance.clickhouse.cloud para que o identificador do serviço não vaze para o histórico do Git.

Pré-requisitos: a camada de analytics está preenchida (dbt run concluído na Etapa 7.3) e o dicionário existe (scripts/04_create_dictionary.sql concluído na Etapa 7.4).

Etapa 0 — Registrar a conexão com o ClickHouse

Entre no Superset em http://localhost:8088 (admin / admin).
Acesse Settings → Database Connections.
Clique em + Database.
Selecione ClickHouse Connect na lista.
Preencha:

Campo Valor
Display Name NYC Taxi — ClickHouse Cloud
Host o nome do host do ClickHouse Cloud (em .clickhouse_state)
Port 8443
Database analytics
Username default
Password sua senha do ClickHouse Cloud
SSL ativado
Clique em Test Connection — confirme que o banner verde de sucesso aparece.
Clique em Connect.

Campo	Valor
Display Name	`NYC Taxi — ClickHouse Cloud`
Host	o nome do host do ClickHouse Cloud (em `.clickhouse_state`)
Port	`8443`
Database	`analytics`
Username	`default`
Password	sua senha do ClickHouse Cloud
SSL	ativado

Parte 1 — Criar os conjuntos de dados

Conjunto de dados 1 — `fact_trips` (tabela)

Usado por: Operations Command Center, Executive Weekly Report, Driver Quality Analytics, Capabilities Showcase

Acesse Datasets → + Dataset.
Defina Database = NYC Taxi — ClickHouse Cloud, Schema = analytics, Table = fact_trips.
Clique em Add Dataset and Create Chart e depois saia da página — o conjunto de dados é salvo.

Conjunto de dados 2 — `agg_hourly_zone_trips` (tabela)

Usado por: Operations Command Center, Executive Weekly Report

Acesse Datasets → + Dataset.
Defina Database = NYC Taxi — ClickHouse Cloud, Schema = analytics, Table = agg_hourly_zone_trips.
Clique em Save.

Conjunto de dados 3 — `CH Approx Unique Trips (uniqHLL12)` (virtual)

Usado por: Capabilities Showcase — demonstra a contagem aproximada com uniqHLL12() em comparação com a contagem exata de uniq().

Acesse Datasets → + Dataset.
Clique em Switch to SQL Lab (ou selecione a guia Virtual).
Defina Database = NYC Taxi — ClickHouse Cloud.
Cole o 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

Dê o nome CH Approx Unique Trips (uniqHLL12) e clique em Save.

Conjunto de dados 4 — `CH Cohort Retention` (virtual)

Usado por: Capabilities Showcase — demonstra funções de janela (AVG(...) OVER (...)) para a receita móvel por borough.

Acesse Datasets → + Dataset → Virtual.
Defina Database = NYC Taxi — ClickHouse Cloud.
Cole o 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

Dê o nome CH Cohort Retention e clique em Save.

Conjunto de dados 5 — `CH Fare Percentiles (quantileTDigest)` (virtual)

Usado por: Capabilities Showcase — demonstra quantileTDigest() como uma função de percentil nativa do ClickHouse.

Acesse Datasets → + Dataset → Virtual.
Defina Database = NYC Taxi — ClickHouse Cloud.
Cole o 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

Dê o nome CH Fare Percentiles (quantileTDigest) e clique em Save.

Conjunto de dados 6 — `CH Sampling Demo` (virtual)

Usado por: Capabilities Showcase — demonstra a amostragem com rand() % N em comparação com uma varredura completa e compara sua precisão.

Acesse Datasets → + Dataset → Virtual.
Defina Database = NYC Taxi — ClickHouse Cloud.
Cole o 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

Dê o nome CH Sampling Demo e clique em Save.

Conjunto de dados 7 — `CH Zone Dict Lookup` (virtual)

Usado por: Capabilities Showcase — demonstra dictGet() para enriquecer dimensões sem nenhuma JOIN.

Exige: o dicionário analytics.taxi_zones_dict da Etapa 7.4 (scripts/04_create_dictionary.sql).

Acesse Datasets → + Dataset → Virtual.
Defina Database = NYC Taxi — ClickHouse Cloud.
Cole o 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

Dê o nome CH Zone Dict Lookup e clique em Save.

Esse conjunto de dados lê de default.trips_raw (tabela bruta), e não de analytics.fact_trips, para mostrar o dicionário funcionando na camada de origem sem nenhum pré-processamento.

Parte 2 — Criar os gráficos

Crie os gráficos por meio de Charts → + Chart: selecione o conjunto de dados, escolha o tipo de gráfico, configure os campos e clique em Save, usando exatamente o nome indicado.

Dashboard 1 — CH Operations Command Center

Gráfico: CH Trip Volume by Hour (24h)

Configuração	Valor
Dataset	`agg_hourly_zone_trips`
Chart type	Line Chart (ECharts)
X-axis	`hour_bucket`
Metric	SUM(`trips`)
Time grain	1 hour

Salve como CH Trip Volume by Hour (24h).

Gráfico: CH Revenue by Zone (Top 10)

Configuração	Valor
Dataset	`agg_hourly_zone_trips`
Chart type	Bar Chart
Dimensions	`zone_id`
Metric	SUM(`revenue`)
Row limit	10
Sort bars	enabled

Salve como CH Revenue by Zone (Top 10).

Dashboard 2 — CH Executive Weekly Report

Gráfico: CH Daily Revenue (7 days)

Configuração	Valor
Dataset	`fact_trips`
Chart type	Line Chart (ECharts)
X-axis	`pickup_at`
Metric	SUM(`fare_amount_usd`)
Time grain	1 hour

Salve como CH Daily Revenue (7 days).

Gráfico: CH Top Zones by Revenue

Configuração	Valor
Dataset	`agg_hourly_zone_trips`
Chart type	Bar Chart
Dimensions	`zone_id`
Metric	SUM(`revenue`)
Row limit	20
Sort bars	enabled

Salve como CH Top Zones by Revenue.

Gráfico: CH Payment Distribution

Configuração	Valor
Dataset	`fact_trips`
Chart type	Pie Chart
Dimensions	`payment_type`
Metric	COUNT(`trip_id`)

Salve como CH Payment Distribution.

Gráfico: CH Avg Fare by Vendor

Configuração	Valor
Dataset	`fact_trips`
Chart type	Bar Chart
Dimensions	`vendor_name`
Metric	AVG(`fare_amount_usd`)
Row limit	20
Sort bars	enabled

Salve como CH Avg Fare by Vendor.

Dashboard 3 — CH Driver Quality Analytics

Gráfico: CH Rating Distribution

Configuração	Valor
Dataset	`fact_trips`
Chart type	Bar Chart
Dimensions	`driver_rating`
Metric	COUNT(`trip_id`)
Row limit	20
Sort bars	enabled

Salve como CH Rating Distribution.

Gráfico: CH High-Rated Driver Revenue

Configuração	Valor
Dataset	`fact_trips`
Chart type	Big Number
Metric	SUM(`fare_amount_usd`)
Filter	`driver_rating >= 4.5`
Subheader	`revenue from 4.5+ rated drivers`

Salve como CH High-Rated Driver Revenue.

Gráfico: CH Avg Fare by Driver Rating

Configuração	Valor
Dataset	`fact_trips`
Chart type	Bar Chart
Dimensions	`driver_rating`
Metric	AVG(`fare_amount_usd`)
Row limit	20
Sort bars	enabled

Salve como CH Avg Fare by Driver Rating.

Gráfico: CH Top Drivers Leaderboard

Configuração	Valor
Dataset	`fact_trips`
Chart type	Table
Query mode	Raw records
Columns	`vendor_name`, `vehicle_type`, `driver_rating`, `fare_amount_usd`
Row limit	1000

Salve como CH Top Drivers Leaderboard.

Dashboard 4 — CH Capabilities Showcase

Gráfico: CH Recent Trips (fact_trips)

Configuração	Valor
Dataset	`fact_trips`
Chart type	Table
Query mode	Raw records
Columns	`trip_id`, `pickup_at`, `dropoff_at`, `fare_amount_usd`, `pickup_borough`, `vendor_name`
Row limit	1000

Salve como CH Recent Trips (fact_trips).

Gráfico: CH Fare Percentiles (quantileTDigest)

Configuração	Valor
Dataset	`CH Fare Percentiles (quantileTDigest)`
Chart type	Table
Query mode	Raw records
Columns	`vendor_name`, `p50_fare`, `p95_fare`, `p99_fare`, `trip_count`

Salve como CH Fare Percentiles (quantileTDigest).

Gráfico: CH Approx vs Exact Unique Trips (uniqHLL12)

Configuração	Valor
Dataset	`CH Approx Unique Trips (uniqHLL12)`
Chart type	Table
Query mode	Raw records
Columns	`day`, `exact_unique_trips`, `approx_unique_trips`, `pct_error`

Salve como CH Approx vs Exact Unique Trips (uniqHLL12).

Gráfico: CH Sampling Accuracy Demo (SAMPLE 0.1)

Configuração	Valor
Dataset	`CH Sampling Demo`
Chart type	Table
Query mode	Raw records
Columns	`method`, `trip_count`, `avg_fare`

Salve como CH Sampling Accuracy Demo (SAMPLE 0.1).

Gráfico: CH Zone Lookup via Dictionary (dictGet)

Configuração	Valor
Dataset	`CH Zone Dict Lookup`
Chart type	Table
Query mode	Raw records
Columns	`borough`, `zone`, `trips`, `avg_fare`

Salve como CH Zone Lookup via Dictionary (dictGet).

Gráfico: CH Weekly Revenue Trend (window functions)

Configuração	Valor
Dataset	`CH Cohort Retention`
Chart type	Table
Query mode	Raw records
Columns	`week`, `pickup_borough`, `trips`, `revenue`, `rolling_4wk_avg_revenue`

Salve como CH Weekly Revenue Trend (window functions).

Parte 3 — Montar os dashboards

Para cada dashboard:

Acesse Dashboards → + Dashboard.
Informe o título.
Clique em Save e depois em Edit Dashboard.
No painel à direita, arraste cada gráfico para a tela.
Ao terminar, clique em Save.

CH — Operations Command Center

Título: CH — Operations Command Center

Linha	Gráficos
Linha 1	CH Total Trips Today · CH Revenue Today
Linha 2	CH Trip Volume by Hour (24h) · CH Revenue by Zone (Top 10)

CH — Executive Weekly Report

Título: CH — Executive Weekly Report

Linha	Gráficos
Linha 1	CH Daily Revenue (7 days) · CH Top Zones by Revenue · CH Payment Distribution · CH Avg Fare by Vendor

CH — Driver Quality Analytics

Título: CH — Driver Quality Analytics

Linha	Gráficos
Linha 1	CH Rating Distribution · CH High-Rated Driver Revenue
Linha 2	CH Avg Fare by Driver Rating · CH Top Drivers Leaderboard

CH — Capabilities Showcase

Título: CH — Capabilities Showcase

Linha	Gráficos
Linha 1	CH Recent Trips (fact_trips) · CH Fare Percentiles (quantileTDigest)
Linha 2	CH Approx vs Exact Unique Trips (uniqHLL12) · CH Sampling Accuracy Demo (SAMPLE 0.1)
Linha 3	CH Zone Lookup via Dictionary (dictGet) · CH Weekly Revenue Trend (window functions)

Depois de concluir a Parte 3, abra http://localhost:8088. Em Dashboards, devem aparecer 7 itens no total — 3 dashboards do Snowflake (criados durante a preparação da Parte 1) e 4 com o prefixo CH —.

Solução de problemas

fact_trips ou agg_hourly_zone_trips não encontrado Primeiro, execute dbt run (Etapa 7.3).

dictGet retorna strings vazias O dicionário analytics.taxi_zones_dict não foi criado. Execute scripts/04_create_dictionary.sql (Etapa 7.4).

O conjunto de dados virtual não retorna linhas A janela de 30 ou 7 dias de algumas consultas exige dados recentes. Se todos os dados da migração forem históricos, substitua o filtro de tempo por uma data fixa:

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

Erro 403 do script de importação O cookie de sessão do Superset expirou. Saia, entre novamente e execute o script outra vez.

Nesta página