Assets

Assets are Python nodes that produce or observe an external artifact - an exported file, a published dataset, a dashboard refresh, an ML model. They behave like tasks but add dataset-like metadata (columns, column lineage) and a materialization flag. See Python Nodes for the shared model and the SQL boundary rules.

Defining an asset

Place Python files under assets/ and decorate functions with @asset:

# assets/exports.py
from sqlbuild.assets import asset, AssetContext


@asset
def orders_export(ctx: AssetContext):
    path = write_orders_csv()
    return ctx.result(metadata={"path": path, "rows": 1200}, materialized=True)

The asset receives an AssetContext and returns through ctx.result(...).

Materialization

Assets record whether they actually produced an artifact via materialized:

@asset
def orders_export(ctx: AssetContext):
    if nothing_changed():
        return ctx.result(metadata={"status": "unchanged"}, materialized=False)
    return ctx.result(metadata={"path": export()}, materialized=True)

materialized=True - the artifact was produced this run.
materialized=False - the asset ran but produced nothing (e.g. it only observed state). This is not a skip; the node still succeeded.

Only assets have materialized; tasks do not.

Dependencies

Assets declare dependencies with depends_on (a single function, tuple, or list), and may depend on tasks, assets, and loaders:

from sqlbuild.assets import asset
from tasks.orders import export_orders


@asset(depends_on=export_orders)
def orders_dashboard(ctx):
    result = ctx.result_of(export_orders)
    return ctx.result(metadata={"rows": result.payload["rows"]}, materialized=True)

To read a SQL model or source, declare a typed reference and resolve it at runtime - see SQL references:

from sqlbuild.assets import asset
from sqlbuild.refs import model


@asset(depends_on=model("fact_orders"))
def orders_extract(ctx):
    relation = ctx.relation(model("fact_orders"))
    rows = ctx.query(f"SELECT count(*) FROM {relation}").fetchone()[0]
    return ctx.result(metadata={"rows": rows}, materialized=True)

Columns and column lineage

Assets can declare a schema for catalog and lineage purposes. This does not enforce anything at runtime; it describes the artifact:

@asset(
    columns=[
        {"name": "order_id", "type": "INTEGER"},
        {"name": "total_cents", "type": "INTEGER", "nullable": False},
    ],
    column_lineage={
        "order_id": [{"node": "fact_orders", "column": "order_id"}],
        "total_cents": [{"node": "fact_orders", "column": "total_cents"}],
    },
)
def orders_export(ctx):
    ...

columns - column declarations with name, optional type, nullable, description, and meta.
column_lineage - maps each asset column to upstream {node, column} references, surfaced in the DAG artifact and integrations.

Tasks and checks do not support columns or column_lineage.

Skipping and retries

Assets support the same ctx.skip(...) and retry behavior as tasks:

from sqlbuild.assets import asset, SkipMode
from sqlbuild.retries import RetryPolicy


@asset(retry=RetryPolicy(max_attempts=3, retry_on=(IOError,)))
def export(ctx):
    if not ready():
        return ctx.skip("upstream not ready", mode="soft")  # or SkipMode.SOFT
    return ctx.result(metadata={"path": do_export()}, materialized=True)

See Tasks for the full retry policy fields.

Decorator parameters

Parameter	Description
`name`	Override the node name (defaults to the function name)
`depends_on`	Upstream nodes (function, tuple, or list); `model()`/`source()` for read-only SQL refs
`columns`	Column declarations for the produced artifact
`column_lineage`	Map of asset column to upstream `{node, column}` references
`tags`	Labels for selection and grouping
`group`	Display/catalog grouping
`description`	Docs (defaults to docstring)
`meta`	Freeform JSON metadata
`retry`	A `RetryPolicy`

Running assets

# Run an asset and its required graph
sqb build --select orders_export --no-tests --no-audits

# Include in a full build with its upstreams
sqb build --select +orders_export

Assets run during sqb build. Use --no-python to suppress read-side assets while still loading sources.

Getting Started

dbt Compatibility

Concepts

Python Nodes

Virtual Environments (Alpha)

Integrations

CLI Reference

Defining an asset

Materialization

Dependencies

Columns and column lineage

Skipping and retries

Decorator parameters

Running assets

​Defining an asset

​Materialization

​Dependencies

​Columns and column lineage

​Skipping and retries

​Decorator parameters

​Running assets

Defining an asset

Materialization

Dependencies

Columns and column lineage

Skipping and retries

Decorator parameters

Running assets