dbt / Basic: project and model foundations / Lesson 1

Framework, runtime and project boundaries

Locate dbt inside a library analytics system and distinguish authoring, execution, adapters and hosted capabilities.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Explain what dbt models and what the data platform executes.
Name the v1.12 teaching baseline without conflating current product names.

Transformation begins after data is available

A regional library has loan records, branch reference data and circulation reports. dbt organizes transformations of available data into modeled relations, tests and documentation. The warehouse or other supported data platform executes the generated work through an adapter; dbt is not automatically the ingestion service, database server or source of business truth. A model describing open loans still needs a trustworthy source and an agreed definition of returned_at. Establish who loads raw data, who owns transformation logic and who publishes the resulting report. A successful transformation cannot prove every branch sent all expected records.

Use a named engine generation and version

This course pins its language and workflow assumptions to dbt v1.12, the Python-based generation historically called dbt Core 1.x. Official documentation reviewed in October 2026 distinguishes this from Rust-based dbt v2, formerly Fusion, and from the Apache-only dbt OSS distribution. The hosted platform adds services and release tracks rather than being identical to a local engine binary. These names changed, so an old screenshot or package name is weak evidence of capabilities. Verify actual engine, adapter and platform separately. The selected baseline is not a claim that v1.12 is the newest release or the right production choice for every team.

A project file declares scope rather than credentials

The small dbt_project.yml fragment names a synthetic project, its model directory and a v1.12 compatibility range. It is illustrative configuration and is never passed to dbt. require-dbt-version constrains accepted framework versions; it does not certify adapter, SQL dialect or warehouse compatibility. Project settings and resource configuration have scope and precedence rules that later lessons examine. Credentials belong to the approved environment and connection mechanism, not a public model file. The example deliberately contains no database endpoint, account secret or command that could contact a configured warehouse.

yaml Illustrative technical example; logical results are reasoned, not engine-tested.

name: library_analytics
version: '1.0.0'
config-version: 2
require-dbt-version: ['>=1.12.0', '<1.13.0']
model-paths: ['models']

A minimal teaching project fragment. The version range is deliberate for this course and is not an installation or deployment recommendation.

A model is a declared relation-building query

A SQL model commonly contains a select statement that dbt wraps according to its materialization. The Jinja call ref resolves another model and declares a dependency, instead of hardcoding a particular development schema. The fragment counts open loans from a previously defined staging model. It does not include the entire project and therefore remains non-runnable. A relation name produced by ref depends on the target, configuration and graph context. Reading the file alone establishes intent, not that any table exists, a query succeeded or a result was tested.

jinja Illustrative technical example; logical results are reasoned, not engine-tested.

select count(*) as open_loans
from {{ ref('stg_loans') }}
where returned_at is null

A model fragment with a dependency on stg_loans. Count correctness depends on its grain and source-completeness contract.

Separate authored, compiled and executed artifacts

Source SQL and YAML express the project. Parsed metadata records resources and dependencies; compiled SQL records rendered statements; run results and warehouse evidence describe particular execution outcomes. None of these is a universal substitute for the others. In v1, compilation and macros can perform adapter or metadata work, so do not assume every compile-related command is an offline syntax check. This course runs no dbt command, adapter, connection or cloud job. Validation uses explicit local graph and parser models only, and every dbt SQL, Jinja and configuration fragment is marked runnable:false.

Common errors and fixes

dbt is expected to load an absent upstream feed

Why it happens: Transformation responsibilities were confused with ingestion ownership.
How to fix it: Identify and repair the approved ingestion contract before interpreting model output.
Prevent it next time: Document source ownership and completeness alongside models.

A project version range certifies the whole stack

Why it happens: Framework compatibility was mistaken for adapter and database compatibility.
How to fix it: Review engine, adapter and target capabilities independently.
Prevent it next time: Keep exact runtime and adapter evidence in release records.

Compiled SQL is called a successful data test

Why it happens: Rendered text was confused with warehouse execution and assertions.
How to fix it: State which artifact and execution boundary the evidence covers.
Prevent it next time: Separate parse, compile, build and test outcomes.

Check your understanding

1. What must be established before interpreting open_loans from the model fragment?

Show worked solution

Verify that stg_loans has one row per intended loan, defines returned_at consistently and contains the accepted source population. Also identify the target relation and execution evidence. The model text alone cannot certify the feed arrived or that a warehouse ever evaluated the count.

2. Are v1.12, a hosted release track and a v2 distribution interchangeable version labels?