Apache Superset: Docker ile Kurulumdan Dashboard’a

Konu nedir, neden önemli?

Apache Superset, açık kaynak bir BI (Business Intelligence) ve data keşif aracıdır.

• Veritabanlarına bağlanır (PostgreSQL, MySQL, Snowflake, BigQuery, vb.)
• SQL ile veri çeker / dataset tanımlar
• Grafikler (charts) ve panolar (dashboards) üretir
• Yetkilendirme (RBAC), paylaşım, embed, alert/report gibi kurumsal özellikleri vardır
• Docker ile hızlıca ayağa kaldırılabilir

Neden önemli?

• “Veriyi görselleştirebiliyorum” demekten öte, uçtan uca BI pipeline kurabildiğini kanıtlar.
• Mühendislik tarafında: Docker, config yönetimi, DB bağlantısı, metrik/dimension tasarımı, dashboard kurgusu.
• Ürün tarafında: KPI seçimi, filtreleme, drill-down, paylaşım.

Temel kavramlar ve tanımlar

Superset’te en çok duyacağın kavramlar:

1) Database (Veritabanı bağlantısı)

Superset’in bağlandığı kaynak. Örn: PostgreSQL.

Bağlantı formatı (SQLAlchemy URI):

postgresql+psycopg2://kullanici:sifre@host:5432/veritabani

2) Dataset (Veri seti / tablo veya view)

Chart’ların beslendiği yapı. Bir tablo (orders) veya view (orders_daily) olabilir.

3) Chart (Görselleştirme)

Dataset + metrik/dimension + filtre + görsel türü.

• Metric: ölçüm (SUM(revenue), COUNT(*), AVG(duration))
• Dimension: kırılım (country, category, date)

4) Dashboard (Pano)

Birden fazla chart’ı bir ekranda toplar, filtreler/sekme düzeni kurarsın.

5) Explore / SQL Lab

• SQL Lab: SQL yaz, çalıştır, sonuçları dataset’e dönüştür
• Explore: chart üretme ekranı (metrik, dimension, filtre, time grain)

6) RBAC (Role-Based Access Control)

Kim hangi veriyi/alanı görebilir? Prod ortamda kritik.

Nasıl çalışır? (Detaylı açıklama)

Database → Superset → Dashboard → User

• Superset, DB’ye bağlanır (driver + SQLAlchemy).
• Dataset tanımlarsın (tablo/view).
• Explore ekranında metrik/dimension seçersin.
• Superset, arka planda SQL üretir, DB’de çalıştırır, sonucu görselleştirir.
• Dashboard, farklı chart’ların birlikte çalıştığı “sunum” katmanı olur.

Önemli nokta: Superset genelde veriyi kendi içinde “saklamaz”. Asıl kaynak DB’dir. (Cache/metadata ayrı)

Faz 0: Docker ile çalışan Superset kurulumu

Aşağıdaki kurulum senaryosu:

• Superset (web)
• Postgres (örnek veri için)
• Admin user
• Çalışır demo dataset

Not: En pratik yöntem, Superset’in resmi docker-compose örneğini baz almak ve repo olarak düzenlemek.

1) Proje klasörü yapısı (GitHub için ideal)

superset-proof/
  docker/
    docker-compose.yml
    superset.env
  db/
    init/
      01_schema.sql
      02_seed.sql
  README.md

---

2) docker-compose.yml (Çalışır örnek)

docker/docker-compose.yml

version: "3.8"

services:
  db:
    image: postgres:16
    container_name: demo_postgres
    environment:
      POSTGRES_USER: demo
      POSTGRES_PASSWORD: demo
      POSTGRES_DB: demo
    ports:
      - "5432:5432"
    volumes:
      - ../db/init:/docker-entrypoint-initdb.d
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U demo -d demo"]
      interval: 5s
      timeout: 5s
      retries: 20

  superset:
    image: apache/superset:latest
    container_name: superset
    depends_on:
      db:
        condition: service_healthy
    env_file:
      - ./superset.env
    ports:
      - "8088:8088"
    command: >
      bash -c "
      superset db upgrade &&
      superset fab create-admin
        --username admin
        --firstname Admin
        --lastname User
        --email admin@local
        --password admin
      || true &&
      superset init &&
      superset run -h 0.0.0.0 -p 8088
      "

Satır satır kısa açıklama

• db: Demo verisini koyacağımız PostgreSQL
• volumes: db/init içindeki SQL dosyaları container ilk kalkışta otomatik çalışır
• superset: Superset container’ı
• superset db upgrade: metadata tablolarını hazırlar
• create-admin: admin hesabı oluşturur (ikinci çalıştırmada “zaten var” olabilir, || true ile tolere)
• superset init: örnek ayarlar, roller, izinler
• run: 8088’den ayağa kaldırır

3) Superset env dosyası

docker/superset.env

SUPERSET_SECRET_KEY=change_me_to_a_long_random_string
TZ=Europe/Istanbul

Prod’da SECRET_KEY mutlaka güçlü olmalı.

4) Ayağa kaldırma

Proje kökünde:

cd docker
docker compose up -d
docker compose logs -f superset

Tarayıcı:

• http://localhost:8088
• kullanıcı: admin
• şifre: admin

Faz 1: Demo veritabanı

1) Tablo ve seed (Postgres init SQL)

db/init/01_schema.sql

CREATE TABLE IF NOT EXISTS orders (
  id           BIGSERIAL PRIMARY KEY,
  order_date   TIMESTAMP NOT NULL,
  customer_id  BIGINT NOT NULL,
  country      TEXT NOT NULL,
  category     TEXT NOT NULL,
  revenue      NUMERIC(12,2) NOT NULL,
  quantity     INT NOT NULL
);

CREATE INDEX IF NOT EXISTS ix_orders_order_date ON orders(order_date);
CREATE INDEX IF NOT EXISTS ix_orders_country ON orders(country);
CREATE INDEX IF NOT EXISTS ix_orders_category ON orders(category);

db/init/02_seed.sql

INSERT INTO orders (order_date, customer_id, country, category, revenue, quantity)
SELECT
  NOW() - (random() * interval '180 days') AS order_date,
  (random() * 5000)::int + 1 AS customer_id,
  (ARRAY['TR','DE','NL','UK','US'])[floor(random()*5)+1] AS country,
  (ARRAY['Electronics','Fashion','Home','Grocery'])[floor(random()*4)+1] AS category,
  round((random() * 500 + 10)::numeric, 2) AS revenue,
  (random()*5)::int + 1 AS quantity
FROM generate_series(1, 20000);

Bu seed:

• Son 180 gün içine dağıtılmış 20.000 sipariş üretir
• KPI’lar için güzel bir demo sağlar (revenue trend, country breakdown, category share)

---

Faz 2: Superset’e Database bağlama (adım adım)

1) Superset UI’dan bağlantı

Superset → Settings → Database Connections → + Database

SQLAlchemy URI:

postgresql+psycopg2://demo:demo@db:5432/demo

Dikkat: Docker ağında superset container’ından DB’ye giderken host localhost değil, service adı olan dbkullanılmalı.

“Test Connection” → başarılı olmalı.

---

Faz 3: Dataset oluşturma + SQL örnekleri (çalışır)

1) Dataset ekleme

Superset → Datasets → + Dataset

• Database: demo_postgres
• Schema: public
• Table: orders

Kaydet.

2) SQL Lab: temel sorgular

Superset → SQL Lab → SQL Editor

(A) Günlük ciro (time series temel)

SELECT
  date_trunc('day', order_date) AS day,
  SUM(revenue) AS total_revenue
FROM orders
GROUP BY 1
ORDER BY 1;

(B) Ülkelere göre ciro

SELECT
  country,
  SUM(revenue) AS total_revenue
FROM orders
GROUP BY country
ORDER BY total_revenue DESC;

(C) Kategori payı

SELECT
  category,
  SUM(revenue) AS total_revenue
FROM orders
GROUP BY category
ORDER BY total_revenue DESC;

(D) Ortalama sepet (avg revenue per order) — metrik mantığı

SELECT
  AVG(revenue) AS avg_order_value
FROM orders;

Faz 4: Chart oluşturma

Aşağıdaki 4 chart ile “demo dashboard” çok net olur.

Chart 1 — “Revenue Trend (Daily)”

• Dataset: orders
• Visualization: Time-series Line Chart
• Time column: order_date
• Time grain: day
• Metric: SUM(revenue)
• Filters: Son 90 gün

Bu chart neyi gösterir?

• Günlük ciro trendi, artış/azalış, sezon etkisi

Chart 2 — “Revenue by Country”

• Visualization: Bar Chart
• Dimension: country
• Metric: SUM(revenue)
• Sort: Metric desc

Chart 3 — “Category Share”

• Visualization: Pie Chart / Donut
• Dimension: category
• Metric: SUM(revenue)

Chart 4 — “Orders & AOV KPI”

• Visualization: Big Number / KPI
• KPI1: COUNT(*) (sipariş sayısı)
• KPI2: AVG(revenue) (AOV)

Superset’te metrik tanımları genelde dataset içinde “metrics” olarak kaydedilebilir. Böylece tekrar kullanırsın.

Faz 5: Dashboard kurgusu

Dashboard oluştur:

• Üstte: KPI’lar (Orders, AOV, Total Revenue)
• Orta: Revenue Trend
• Altta: Country bar + Category donut

Native Filters ekle:

• Date range (order_date)
• Country (country)
• Category (category)

Bu filtreleri tüm grafiklere bağla.

Küçük projelere entegre edilebilir “kod” parçaları

1) View ile modelleme (DB tarafı)

Dashboard’ın temiz çalışması için DB’de view üretmek gerçek hayatta sık görülür.

Örn: Günlük özet view:

CREATE OR REPLACE VIEW orders_daily AS
SELECT
  date_trunc('day', order_date) AS day,
  country,
  category,
  COUNT(*) AS order_count,
  SUM(revenue) AS revenue,
  AVG(revenue) AS aov
FROM orders
GROUP BY 1,2,3;

Bunu dataset yaparsın:

• day time column
• metrikler hazır (revenue, order_count, aov)

2) “Okunur KPI tanımı” (metric olarak)

Superset’te metric ifadesi olarak:

• Total Revenue: SUM(revenue)
• Orders: COUNT(*)
• AOV: AVG(revenue)
• Revenue per Item: SUM(revenue) / NULLIF(SUM(quantity), 0)

Yaygın hatalar ve çözümleri

1) “Connection refused / host not found”

Sebep: Docker içinde localhost kullanmak
Çözüm: URI’da host db olmalı:

postgresql+psycopg2://demo:demo@db:5432/demo

2) “psycopg2 not installed” / driver hatası

Sebep: Superset image’ında ilgili DB driver yok
Çözüm: Resmi image genelde PostgreSQL’i destekler ama sorun olursa custom image gerekebilir:

• apache/superset üzerine pip install psycopg2-binary

3) Superset açılıyor ama login olmuyor / init eksik

Çözüm: Container command içinde:

• superset db upgrade
• superset init
• admin oluşturma

4) Zaman serisinde tarih görünmüyor / empty chart

Sebep: Time column seçilmedi veya timezone/time grain uyumsuz
Çözüm: Dataset’te doğru time column = order_date seç, chart’ta “Time range” ver.

5) Performans kötü (chart çok yavaş)

Sebep: Index yok, sorgu ağır, çok geniş tarih aralığı
Çözüm: Index ekle (order_date, country, category), time range sınırla, view/materialized view düşün.

Best Practices

Modelleme / Veri tarafı

• Dashboard için view üretmek çoğu zaman en temiz yaklaşım.
• Time-series KPI’larında date_trunc() ile “grain” sabitle.
• Büyük tabloda mutlaka order_date index’i.

Superset kullanım

• Dataset içinde metric’leri tanımla (tekrar kullanılabilirlik).
• Dashboard’ta Native Filters kullan.
• İsimlendirme standardı:
  • CH__Revenue_Trend_Daily
  • CH__Revenue_By_Country
  • DS__orders_daily
  • DB__demo_postgres

Kaynakça:

• https://superset.apache.org/docs/intro/
• https://github.com/apache/superset