Önkoşullar ve Kurulum

dbt Core, Python 3.8+ gerektirir ve pip aracılığıyla yüklenir. Önemli olan yüklemek yalnızca temel paket değil, aynı zamandaözel adaptör deponuz için. SQL lehçeleri farklı olduğundan her deponun kendi bağdaştırıcısı vardır. 

# Installa dbt Core con l'adapter per PostgreSQL (ottimo per iniziare in locale)
pip install dbt-postgres

# Per BigQuery
pip install dbt-bigquery

# Per Snowflake
pip install dbt-snowflake

# Per DuckDB (ideale per sviluppo locale senza infrastruttura)
pip install dbt-duckdb

# Verifica l'installazione
dbt --version
# Core:
#   - installed: 1.9.0
#   - latest:    1.9.0 - Up to date!

Yerel Kalkınma için DuckDB'yi kullanmaya başlayın

BigQuery veya Snowflake'e anında erişiminiz yoksa DuckDB yol bu başlamak daha hızlıdır: doğrudan yerel olarak çalışan yerleşik bir veritabanıdır, Hiçbir altyapı gerektirmez ve dbt-duckdb her makinede çalışır. Öğrenmek için mükemmel masrafsız.

İlk dbt Projesini Oluşturun

komut dbt init Bir dbt projesinin klasör yapısını oluşturur ve size yol gösterir ilk konfigürasyonda: 

dbt init jaffle_shop

# dbt chiederà:
# 1. Quale database vuoi usare? (postgres/bigquery/snowflake/...)
# 2. [Per postgres] host, port, user, password, database, schema

# La struttura creata:
jaffle_shop/
├── dbt_project.yml          # configurazione principale
├── README.md
├── analyses/               # query ad hoc (non materializzate)
├── macros/                 # funzioni Jinja riutilizzabili
├── models/
│   └── example/            # modelli di esempio (da eliminare)
├── seeds/                  # CSV statici
├── snapshots/              # snapshot per SCD
└── tests/                  # test SQL singolari

dbt_project.yml dosyası

Proje konfigürasyonunun kalbi dbt_project.yml. Burayı tanımlayın proje adı, dbt sürümü, dizin yolları ve genel yapılandırma modellerden: 

# dbt_project.yml
name: 'jaffle_shop'
version: '1.0.0'

# Versione minima di dbt richiesta
require-dbt-version: ">=1.8.0"

# Percorso del profile da usare (in profiles.yml)
profile: 'jaffle_shop'

# Directory dei modelli
model-paths: ["models"]
analysis-paths: ["analyses"]
test-paths: ["tests"]
seed-paths: ["seeds"]
macro-paths: ["macros"]
snapshot-paths: ["snapshots"]

# Dove salvare i log e i target compilati
target-path: "target"
log-path: "logs"
clean-targets: ["target", "dbt_packages"]

# Configurazione dei modelli per directory
models:
  jaffle_shop:
    # Tutti i modelli del progetto sono view per default
    +materialized: view

    staging:
      # I modelli in staging/ sono sempre view
      +materialized: view
      +schema: staging          # savedano in schema 'staging'

    marts:
      +materialized: table      # I marts sono table per performance
      +schema: marts

profiles.yml dosyası

Bağlantı kimlik bilgileri girer ~/.dbt/profiles.yml (ana dizinde, Asla depoda). Her profilin birden fazla hedefi olabilir (geliştirme, aşamalandırma, üretim): 

# ~/.dbt/profiles.yml
jaffle_shop:
  target: dev                    # target di default

  outputs:
    dev:
      type: postgres
      host: localhost
      port: 5432
      user: "{{ env_var('DB_USER') }}"      # usa variabili d'ambiente
      password: "{{ env_var('DB_PASSWORD') }}"
      dbname: jaffle_shop_dev
      schema: dbt_dev_federico   # schema personale per sviluppo
      threads: 4

    prod:
      type: postgres
      host: "{{ env_var('PROD_DB_HOST') }}"
      port: 5432
      user: "{{ env_var('PROD_DB_USER') }}"
      password: "{{ env_var('PROD_DB_PASSWORD') }}"
      dbname: jaffle_shop_prod
      schema: dbt_prod
      threads: 8

Kural, her geliştiricinin kişisel bir modele sahip olmasıdır (örn. dbt_dev_federico) paralel geliştirme sırasında çatışmaları önlemek için.

dbt modelleri: Temel Birim

Bir dbt modeli bir dosyadır .sql rehberde models/. içerik bu basit bir SELECT — dbt, depoda ilgili görünümü veya tabloyu oluşturmayla ilgilenir.

Gerçekçi bir örnekle başlayalım. Diyelim ki bir masamız var raw.orders içinde uygulamadan alınan ham verileri içeren depo: 

-- models/staging/stg_orders.sql
-- Staging model: rinomina, casta, pulisce — nessuna logica di business

WITH source AS (
    SELECT * FROM {{ source('raw', 'orders') }}   -- 'source' punta alla sorgente raw
),

renamed AS (
    SELECT
        id                                         AS order_id,
        user_id                                    AS customer_id,
        order_date                                 AS created_at,
        status,
        CAST(amount AS DECIMAL(10,2))              AS total_amount,
        LOWER(payment_method)                      AS payment_method,
        _loaded_at                                 AS loaded_at    -- metadata pipeline
    FROM source
    WHERE id IS NOT NULL                           -- filtra record corrotti
)

SELECT * FROM renamed

ref() Makrosu

Makro ref() dbt'nin en önemli özelliğidir. Yazdığında {{ ref('stg_orders') }}, veri tabanı:

  1. Geçerli ortam için depodaki tablonun/görünümün doğru adını çözer
  2. Bağımlılığı yönlendirilmiş döngüsel olmayan grafikte (DAG) kaydedin
  3. Bağımlı modelin ilk önce çalışmasını sağlar
-- models/marts/finance/orders_monthly.sql
-- Usa ref() per dipendere da stg_orders

WITH orders AS (
    SELECT * FROM {{ ref('stg_orders') }}          -- dbt risolve automaticamente lo schema
),

monthly_aggregated AS (
    SELECT
        DATE_TRUNC('month', created_at)            AS month,
        payment_method,
        COUNT(*)                                   AS order_count,
        SUM(total_amount)                          AS gross_revenue,
        AVG(total_amount)                          AS avg_order_value,
        COUNT(DISTINCT customer_id)                AS unique_customers
    FROM orders
    WHERE status = 'completed'
    GROUP BY 1, 2
)

SELECT * FROM monthly_aggregated

Kaynak() Makrosu

Ham kaynaklara (dbt tarafından oluşturulmayan tablolar) erişmek için şunu kullanın: source() yerine ref(). Kaynaklar bir dosyada bildirilmelidir sources.yml: 

# models/staging/sources.yml
version: 2

sources:
  - name: raw                    # nome del source group
    database: raw_db             # database nel warehouse
    schema: public               # schema nel warehouse
    tables:
      - name: orders
        description: "Ordini grezzi dall'applicazione"
        loaded_at_field: _loaded_at    # campo per freshness check
        freshness:
          warn_after: {count: 12, period: hour}
          error_after: {count: 24, period: hour}
      - name: customers
        description: "Clienti grezzi dall'applicazione"

Bu kurulumla çalıştırabilirsiniz dbt source freshness bunu doğrulamak için Kaynaklar, dönüşümlere başlamadan önce güncellenir.

Dbt'yi çalıştırın: Temel Komutlar

# Esegui tutti i modelli (materialization nel warehouse)
dbt run

# Esegui solo i modelli staging
dbt run --select staging

# Esegui un singolo modello e tutte le sue dipendenze (+)
dbt run --select +orders_monthly

# Esegui tutti i test definiti nello schema YAML
dbt test

# Testa solo un modello specifico
dbt test --select stg_orders

# Compila i modelli senza eseguirli (utile per debug)
dbt compile

# Verifica freshness delle sorgenti
dbt source freshness

# Genera e serve la documentazione
dbt docs generate
dbt docs serve                  # apre http://localhost:8080

Önerilen Şablon Yapısı

dbt topluluğu tarafından önerilen üç katmanlı yapı: 

models/
├── staging/                    # Layer 1: vicino alla sorgente
│   ├── sources.yml            # dichiarazione sorgenti
│   ├── schema.yml             # test + documentazione
│   ├── stg_orders.sql
│   ├── stg_customers.sql
│   └── stg_products.sql
├── intermediate/               # Layer 2: join complessi (opzionale)
│   ├── int_orders_enriched.sql # join ordini + clienti
└── marts/                      # Layer 3: pronti per consumo
    ├── finance/
    │   ├── schema.yml
    │   ├── orders_monthly.sql
    │   └── revenue_by_country.sql
    └── marketing/
        └── customer_cohorts.sql

Anti-örüntü: Aşamalandırmada İş Mantığı

Hazırlama şablonlarının yalnızca "aptal" işlemler yapması gerekir: sütunları yeniden adlandırma, tür değiştirme türleri, tekilleştirme. İş mantığı (hesaplamalar, toplamalar, birleştirmeler) ara modellere gider veya martlar. Aşama modelinizde GROUP BY veya birkaçtan fazla hesaplanmış sütun varsa, muhtemelen bu katmanda çok fazla şey yapıyorsunuzdur.

Kurulumu dbt debug ile kontrol etme

Koşmadan önce dbt run, ambar bağlantısının çalıştığını doğrulayın: 

dbt debug

# Output atteso:
# Configuration:
#   profiles.yml file [OK found and valid]
#   dbt_project.yml file [OK found and valid]
# Required dependencies:
#  - git [OK found]
# Connection:
#   host: localhost
#   port: 5432
#   user: federico
#   database: jaffle_shop_dev
#   schema: dbt_dev_federico
#   [OK connection ok]

Sonuçlar ve Sonraki Adımlar

Üç seviyeli yapıya sahip çalışan bir dbt projesi yapılandırdık (aşama → ara → martlar), farklı ortamlar için bağlantı profilleri, beyan edilen kaynaklar tazelik kontrolü ve ilk modeller ref() e source().

Bir sonraki adım SQL'imizi Jinja ile dinamik hale getirmek: değişkenler, döngüler, koşullar ve depoda kod tekrarını ortadan kaldıran yeniden kullanılabilir makrolar.

Önceki makale ← dbt ve Analitik Mühendisliği Nedir?
Serideki sonraki Dbt'de Jinja ve Makrolar: Dinamik SQL →