slingdata-io/sling-cli/sling-build

Sling Build — SQL Models with Dependency Resolution

sling build is Sling's lightweight SQL model builder with Jinja-style templating, dependency resolution from ref() calls, and incremental materializations. The single canonical reference is https://docs.slingdata.io/llms.txt — load that first if you need anything beyond the quick reference below.

Gather first

Resolve each row before you write YAML, in this order: the user's request, existing files, discovery (MCP / CLI), then the default in the table. Ask the user only for rows that stay unresolved, one at a time, with a proposed default. If every row resolves, do not ask — build, and state the assumptions you took. Confirm first only for destructive resolutions (for example a mode that drops or rewrites existing tables).

When you update a model, read the files first. Preserve incremental-state semantics unless asked otherwise.

Project layout

A build project is any directory containing sling_build.yml. Models are .sql files — usually grouped under schema folders or, with dbt_project: true, under models/ and seeds/.

In a full Sling project, put this tree under models/ (see PROJECT.md in the sling skill). First folder = schema. Naming rules: STRUCTURE.md.

models/
  sling_build.yml
  staging/          # views: stg_<source>__<entity>
    stg_stripe__users.sql
    stg_stripe__orders.sql
  intermediate/     # views: int_<entity>__<verb>
    int_orders__joined.sql
  marts/            # tables: fct_* / dim_*
    fct_orders.sql

Staging selects from raw via src(). Marts use ref() to staging or intermediate only. Marts never touch raw.

src() and ref()

src() is a passthrough. It does not add a raw_ prefix.

-- two args: schema, table
select * from {{ src('raw_stripe', 'invoice') }}
-- result: select * from raw_stripe.invoice
 
-- one arg: schema.table
select * from {{ src('raw_stripe.invoice') }}
-- result: select * from raw_stripe.invoice

source() is an alias of src().

ref('name') resolves a model or seed in this project to its full table name. An unknown name is a compile error.

select * from {{ ref('stg_orders') }}
-- result: select * from staging.stg_orders

Duplicate model names in the project are a hard error at load time.

Front-matter

Put YAML in a /** **/ block. It must be the first content in the file. Leading whitespace is allowed. Comments before the block are not. The engine treats the rest of the file as SQL.

You can also use /* { ... } */ or -- { ... } with a brace object.

Front-matter does not rename the model. The model name is the file stem. ref(), selectors, and @name accept the stem or the prod table schema.table. Model names are unique across the project.

sling_build.yml essentials

target: MY_SNOWFLAKE
defaults:
  mode: full-refresh
dev:
  schema: dev_${USER}
  target: MY_SNOWFLAKE_DEV
dbt_project: false   # set true for models/+seeds/ layout

Model materialization modes

Canonical modes: view, full-refresh, incremental, append. Prefer these names.

• view — CREATE OR REPLACE VIEW.
• full-refresh — drop and rebuild every run (default). table is an accepted alias.
• incremental — append/merge based on update_key + unique_key.
• append — insert only. snapshot is a deprecated alias.
• truncate — truncate target then reload.

Per-model overrides go in a YAML front-matter block at the top of the SQL. Jinja {%- config(...) -%} is dbt-compat only — prefer YAML:

/**
mode: incremental
update_key: updated_at
unique_key: [id]
range:
  start: '2020-01-01'
  advance: 1mo
  lookback: 2d
**/
 
select * from {{ ref("stg_orders") }} where {{ incremental_where_cond() }}

Front-matter range: (start, advance, lookback) is the durable backfill window. Pair it with update_key and unique_key. Do not reverse-engineer the binary for this.

Read raw table columns before you write SQL (sling conns discover CONN --columns or MCP database.get_columns). Do not guess column names or types.

Never reference a SELECT alias inside the same query's JOIN or WHERE. Use the source column (c_nationkey, not c.nation_key).

Common workflows

When the warehouse stores an authoritative total (for example o_totalprice), aggregate that column. Recompute from components only when asked.

Notes:

• Seeds (CSV files, in seeds/ with dbt_project: true) load before models unless --no-seeds is passed.
• --range is a one-shot CLI backfill (start,end[,step], e.g. 2024-01-01,2024-12-31,1mo). Prefer front-matter range: for a durable window.
• --schema forces dev mode and cannot combine with --prod.
• One project root. Do not leave nested scratch projects (probe/, .probe/). Parent compile skips a subdirectory that has its own sling_build.yml unless you pass -R.
• Resolve the Gather first checklist before you write a new model. When you edit an incremental model, preserve saved-state semantics unless asked otherwise.

Definition of done: sling build run . --target X (or sling build test) completes with 0 failures. Compile alone does not execute SQL, so it does not prove correctness.

${VAR} in sling_build.yml (for example dev.schema: dev_${USER}) is expanded from the environment. An unset variable in an active field is an error; use ${VAR:-fallback} or --prod / --schema to skip the field.

Use the MCP tools to validate

• database.get_columns / database.get_schemata — read columns before you write SQL.
• database.query — sanity-check the SQL against the target before committing.
• connection.test — make sure target: resolves before the first sling build.

When the user asks for a new model, prefer to:

1. Inspect upstream columns with database.get_columns (or sling conns discover CONN --columns).
2. Draft the SQL, including YAML frontmatter when materialization isn't full-refresh.
3. Run sling build compile -s <model> to confirm the SQL renders cleanly.
4. Run sling build run . --target <conn> (or -s <model>) until it completes with 0 failures.
5. Remove scratch files and nested probe projects before you finish.

Full Documentation

Append .md paths to https://docs.slingdata.io to fetch raw markdown. Full index: https://docs.slingdata.io/llms.txt