dbt docs: kendi data kataloğunu yayınla

Tarif Defterini Herkes Okusun

Elif’in annesi yemek defterini sadece mutfakta tutmuyor — Instagram’da paylaşıyor, komşulara dağıtıyor, hatta küçük bir kitapçık bastırıyor. “Yaptığım yemekleri herkes görsün” diyor.

dbt de docs üretir. Yazdığın her modelin, her sütunun, her testin açıklamasını toplar, güzel bir HTML sitesi oluşturur. Hem takımınla paylaşırsın hem portfolyo olarak LinkedIn’e koyarsın.

Üç Komut Yeter

dbt docs generate    # manifest.json + catalog.json üretir
dbt docs serve       # localhost:8080'de site açar

dbt docs serve çalıştırınca tarayıcıda http://localhost:8080 açılır. Göreceğin şeyler:

• Sol panel: tüm modeller, source’lar, seed’ler, testler.
• Orta: seçili modelin açıklaması, SQL kodu, bağımlılıkları (DAG).
• Sağ: modelin sütunları ve açıklamaları.
• Lineage view: hangi model hangi modelden doğmuş, görsel akış.

Site Çok Güzel Ama Yerel — Onu Yayınlayalım

serve sadece kendi bilgisayarında çalışır. Siteyi herkes görsün istiyorsan GitHub Pages’e koymak en kolay yol.

.github/workflows/docs.yml:

name: dbt docs
on:
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install dbt-core dbt-bigquery
      - run: dbt deps
      - run: dbt docs generate
        env:
          BIGQUERY_KEYFILE_JSON: ${{ secrets.GCP_SA_KEY }}
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./target

Her git push’ta GitHub Actions:

1. dbt’yi kurar, modelleri generate eder.
2. target/ klasörünü (HTML site) gh-pages branch’ine yükler.
3. Siten https://<kullanıcı>.github.io/<repo>/ adresinde yayınlanır.

Siteyi Güzelleştir

dbt_project.yml’e tema ekleyebilirsin:

models:
  limonata_analiz:
    +description: "Elif'in limonata dükkanı analitik pipeline"
    +meta:
      owner: "@elif"
      domain: "satış"

Modellerine yazdığın description’lar katalogda görünür. Yarın biri takıma katılırsa, “hangi tablo ne işe yarar” diye kendine sormaz, siteye bakar.

Ne Öğrendik?

• dbt docs generate + dbt docs serve ile yerel katalog sitesi oluşur.
• GitHub Pages + GitHub Actions ile site herkes tarafından erişilebilir olur.
• Yazdığın description’lar otomatik toplanır — açıklama yazmak boşuna değil.
• Bu site, portfolyo olarak işe alım sürecinde altın değerinde.

Küçük Ödev

1. dbt docs generate && dbt docs serve çalıştır, localhost:8080’de gezin.
2. En sevdiğin 3 modele güzel description yaz.
3. .github/workflows/docs.yml ekle, push’la, sitenin *.github.io adresinde açıldığını gör.

Sıradaki

Modül 5: lineage ve veri kalitesi →