dbt docs: kendi data kataloğunu yayınla

Kendi Veri Kataloğunu Yayınla

Yazılımcılar GitHub profilini portfolyo olarak gösterir. Analytics mühendisleri için dbt docs sitesi aynı şey: yazdığın modelleri, tabloları, lineage’ı görsel olarak sunan bir HTML site. İşe alım sürecinde “LinkedIn’e koy, mülakatta göster” seviyesinde değer.

Üretim

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

target/ klasöründe:

• manifest.json: her modelin, her macro’nun, her testin metadata’sı.
• catalog.json: her sütunun veri tipi, yorumu, istatistikleri.
• index.html: UI bundle.

Site Özellikleri

localhost:8080’de gezerken:

• Sol ağaç: tüm modeller (marts, staging, intermediate), source’lar, seed’ler, testler, macro’lar.
• Model sayfası: açıklama, sütunlar, DAG (lineage) görselleştirmesi — hangi modelden doğmuş, hangi modele akmış.
• Sütun açıklamaları: docblock’ta yazdığın description görünür.
• Search: herhangi bir sütun adını arat, hangi modelde geçiyor bul.
• Test durumu: kaç test geçti, kaç kaldı.

Lineage (Soy Ağacı) Grafiği

En güçlü özellik: DAG görselleştirmesi. Bir modelin hangi source’lardan geldiğini, hangi downstream modellere aktığını görürsün. Impact analysis için kritik: “Şu source’u değiştirsem hangi tablolar etkilenir?” sorusunun cevabı.

Public Yayınlama: GitHub Pages

serve sadece local çalışır. Siteyi herkes görebilsin diye GitHub Pages’e koy. CI workflow ile otomatik.

.github/workflows/dbt-docs.yml:

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

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dbt
        run: pip install dbt-core dbt-bigquery

      - name: dbt deps
        run: dbt deps

      - name: dbt docs generate
        run: dbt docs generate
        env:
          BIGQUERY_KEYFILE_JSON: ${{ secrets.GCP_SA_KEY }}
          DBT_PROFILES_DIR: ${{ github.workspace }}

      - uses: actions/configure-pages@v5

      - uses: actions/upload-pages-artifact@v3
        with:
          path: target

      - id: deployment
        uses: actions/deploy-pages@v4

git push origin main → Actions çalışır → site https://<user>.github.io/<repo>/ adresinde yayınlanır.

Secrets: BigQuery service account JSON’u GitHub Secrets’a koy (GCP_SA_KEY). Workflow BIGQUERY_KEYFILE_JSON env’ine yaz, profiles.yml’de oku.

dbt Cloud ile Ücretsiz Hosted Docs

GitHub Pages ile uğraşmak istemezsen dbt Cloud ücretsiz tier:

1. Repo’yu dbt Cloud’a bağla.
2. Production environment’ta “Generate docs on schedule” aç.
3. dbt Cloud cloud.getdbt.com/discover/<account>/<project> adresinde docs’u host eder.

Custom domain de bağlanabilir.

Portfolyo Hikayesi

LinkedIn’de “Data Engineer” diyen 1000 kişi var. Hangi biri gerçekten üretim kalitesinde SQL yazıyor belli değil. Senin public dbt docs siten fark yaratır:

• “NYC taksi verisi üzerine 12 dbt modeli, 8 test, lineage grafiği: [link]”
• “Snowflake üzerinde 50 model, incremental strateji, CI/CD: [link]”

Mülakatta “bu modeli neden böyle yazdın?” sorusuna cevap — siteye bakarak gösterirsin.

Ne Öğrendik?

• dbt docs generate + dbt docs serve ile lokal katalog sitesi.
• Lineage DAG görselleştirmesi upstream/downstream analizi sağlar.
• GitHub Pages + workflow ile ücretsiz public hosting.
• dbt Cloud ücretsiz tier alternatif hosting sağlar.
• Docs sitesi portfolyo olarak iş başvurusunda fark yaratır.

Küçük Ödev

1. Tüm model ve sütunlara açıklayıcı description yaz.
2. dbt docs generate && dbt docs serve çalıştır, lineage grafiğini incele.
3. .github/workflows/dbt-docs.yml ekle, push’la, sitenin *.github.io URL’inde açıldığını doğrula.
4. Siteyi LinkedIn profiline “Featured” bölümüne ekle.

Sıradaki

Modül 5: lineage + veri kalitesi otomasyonu →