> For the complete documentation index, see [llms.txt](https://docs.slingdata.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.slingdata.io/concepts/build.md).

# Build

Sling Build is a lightweight SQL model builder built into the Sling CLI. It compiles Jinja-templated SQL models, resolves dependencies via a DAG, and executes them against any of Sling's 30+ supported database connectors. Think of it as a simpler alternative to dbt — no extra dependencies, no profiles, no packages — just SQL files and a single optional config.

{% hint style="success" %}
Sling Build integrates with the [Sling VSCode Extension](/sling-cli/vscode.md). The extension gives you schema validation, auto-completion, and diagnostics for your `sling_build.yml` configuration.
{% endhint %}

## Quick Start

### 1. Create a project

Write a `sling_build.yml` in the model folder. For a full Sling project, run `sling init`. That command writes `models/sling_build.yml`.

### 2. Add models

```
my_project/
├── sling_build.yml
├── staging/
│   ├── stg_orders.sql
│   └── stg_customers.sql
└── marts/
    └── fct_orders.sql
```

{% code title="sling\_build.yml" %}

```yaml
target: MY_POSTGRES

defaults:
  mode: full-refresh
```

{% endcode %}

{% code title="staging/stg\_orders.sql" %}

```sql
SELECT id, customer_id, amount, created_at
FROM raw_data.orders
```

{% endcode %}

{% code title="marts/fct\_orders.sql" %}

```sql
/**
mode: incremental
unique_key: id
update_key: created_at
**/

SELECT
    o.id,
    o.customer_id,
    o.amount,
    c.name as customer_name,
    o.created_at
FROM {{ ref('stg_orders') }} o
JOIN {{ ref('stg_customers') }} c ON o.customer_id = c.id
WHERE {{ incremental_where_cond() }}
```

{% endcode %}

### 3. Run the build

```bash
sling build
```

### 4. Preview without executing

```bash
sling build compile
```

## Key Concepts

* [**Structure**](/concepts/build/structure.md) — Project layout, `sling_build.yml` configuration, naming conventions, dev & prod mode, selectors, multi-target projects.
* [**Models**](/concepts/build/models.md) — SQL model files, config declaration, materialization modes, template functions, macros, seeds, hooks, and data tests.
* [**Incremental**](/concepts/build/incremental.md) — Two styles (dbt-compatible and sling-native), the `range:` front-matter (lookback, paged mode), and `--range` CLI backfills.

## Commands

```bash
sling build run      [path] [flags]   # materialize models, then run declarative tests
sling build list     [path] [flags]   # list selected models
sling build test     [path] [flags]   # run declarative data tests only
sling build compile  [path] [flags]   # render SQL + DAG, no execute
sling build                           # prints help, builds nothing
```

`run` materializes and then runs each model's declarative tests. `test` runs tests only and skips seeds.

## CLI Reference

Common flags (`run`, `list`, `test`, `compile`): `--target`/`-t`, `--select`/`-s`, `--exclude`, `--schema`, `--prod`, `--vars`, `--recursive`/`-R`, `--debug`/`-d`, `--trace`.

| Flag                 | Short | run | list | test | compile |
| -------------------- | ----- | --- | ---- | ---- | ------- |
| `[path]`             |       | yes | yes  | yes  | yes     |
| `--target`           | `-t`  | yes | yes  | yes  | yes     |
| `--select`           | `-s`  | yes | yes  | yes  | yes     |
| `--exclude`          |       | yes | yes  | yes  | yes     |
| `--schema`, `--prod` |       | yes | yes  | yes  | yes     |
| `--vars`             |       | yes | yes  | yes  | yes     |
| `--recursive`        | `-R`  | yes | yes  | yes  | yes     |
| `--json`             |       |     | yes  | yes  | yes     |
| `--full-refresh`     | `-f`  | yes |      |      |         |
| `--range`            |       | yes |      |      |         |
| `--no-seeds`         |       | yes |      |      |         |
| `--threads`          |       | yes |      | yes  |         |
| `--fail-fast`        | `-x`  | yes |      | yes  |         |
| `--debug`            | `-d`  | yes | yes  | yes  | yes     |

`list` does not require a target. Without one it prints model names and files and omits the table column.

{% hint style="info" %}
If you give no `--target` and no `-R`, and the path has no `sling_build.yml`, `sling build run` prints the help menu instead of walking the directory tree. Bare `sling build` prints the verb list.
{% endhint %}

## Parallelism

Models run on a ready-queue: a model starts as soon as all of its selected dependencies complete. It does not wait for the full DAG level to finish.

* Default is 4 threads. Set `--threads` to change it.
* For single-writer targets (the DuckDB family), Sling forces 1 thread.
* With `--fail-fast`, models already in flight complete, but no new models start. Models that never started are reported as skipped.
* When a model fails, its downstream models are skipped, not failed.

## Examples

```bash
# Run all models in current directory
sling build run

# Run specific models with 8 threads
sling build run -s "stg_*" --threads 8

# Run a model and all its upstream dependencies
sling build run -s "+fct_orders"

# Compile only — preview SQL and DAG without executing
sling build compile

# Force full-refresh in production mode
sling build run --prod --full-refresh

# Override target and pass variables
sling build run -t MY_SNOWFLAKE --vars '{"start_date": "2024-01-01"}'

# List selected models without executing
sling build list -s "tag:daily"

# Run data tests only, no materialization
sling build test

# Machine-readable compile output
sling build compile --json
```

## Build Step in Hooks and Pipelines

A build project can run as a step in a [pipeline](/concepts/pipeline.md) or as a [hook](/concepts/hooks.md), with `type: build`.

```yaml
steps:
  - type: build
    build: ./models
    command: run
    target: MY_POSTGRES
    select: [ "tag:daily" ]
    threads: 4
```

| Key            | Type           | Description                                                                       |
| -------------- | -------------- | --------------------------------------------------------------------------------- |
| `build`        | string         | Project directory. Also becomes the working directory. Accepts a `file://` prefix |
| `command`      | string         | `run` (default), `test`, `compile`, or `list`. Same verbs as `sling build`        |
| `target`       | string         | Target connection                                                                 |
| `select`       | string or list | Model selectors                                                                   |
| `exclude`      | string or list | Exclusion patterns                                                                |
| `vars`         | map            | Template variables                                                                |
| `env`          | map            | Environment variables for this step (`${VAR}` in `sling_build.yml`)               |
| `schema`       | string         | Dev schema override                                                               |
| `prod`         | bool           | Force prod mode                                                                   |
| `full_refresh` | bool           | Force full-refresh (`command: run` only)                                          |
| `no_seeds`     | bool           | Skip seeds (`command: run` only)                                                  |
| `fail_fast`    | bool           | Stop on first failure (`run` / `test`)                                            |
| `threads`      | int            | Parallel model executions (`run` / `test`)                                        |
| `range`        | string         | Backfill range (`command: run` only)                                              |
| `recursive`    | bool           | Discover child `sling_build.yml` files                                            |
| `test`         | bool           | Alias for `command: test`                                                         |

### Step State

The step publishes results to `state.<step_id>`:

| Field                       | Description                                                                                                                       |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `path`                      | Resolved project directory                                                                                                        |
| `target`                    | Target connection name                                                                                                            |
| `command`                   | Resolved verb (`run`, `test`, `compile`, or `list`)                                                                               |
| `results`                   | List of `{name, type, mode, duration, status, error}`. Status is `success`, `error`, or `skipped`. `compile` uses `nodes` instead |
| `total`                     | Model count                                                                                                                       |
| `ok` / `failed` / `skipped` | Counts by status                                                                                                                  |
| `ok_names`                  | Comma-joined names of successful models (`run` / `test`)                                                                          |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.slingdata.io/concepts/build.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.