Setting the file. One moment.
Subchapter 2.1
references/asset-selection.mdMarkdown6 KBView on GitHub
Assets can be selected two ways:
dg CLI (--assets), and dg.AssetSelection.from_coercible() in PythonAssetSelection in Python — programmatic API with set operations (|, &, -), traversals, and methods not available in string syntaxkey:<name> or just <name> — select by asset key (e.g. customers)tag:<key>=<value> or tag:<key> — select by tag (e.g. tag:priority=high)owner:<value> — select by owner (e.g. owner:team@company.com)group:<value> — select by group (e.g. group:sales_analytics)kind:<value> — select by kind (e.g. kind:dbt)code_location:<value> — select by code location (e.g. code_location:my_project)status:<value> — select by materialization statuscolumn:<value> — select by column name (assets with table schema metadata)table_name:<value> — select by table namecolumn_tag:<key>=<value> or column_tag:<key> — select by column-level tagchanged_in_branch:<value> — select assets changed in a git branch (Dagster Plus)Wildcards: key:customer*, key:*_raw, * (all assets)
and / AND — e.g. tag:priority=high and kind:dbtor / OR — e.g. group:sales or group:marketingnot / NOT — e.g. not kind:dbt(expr) — grouping, e.g. tag:priority=high and (kind:dbt or kind:python)sinks(expr) — assets with no downstream dependents (e.g. sinks(group:analytics))roots(expr) — assets with no upstream dependencies (e.g. roots(kind:dbt))+expr — all upstream dependencies (e.g. +customers)expr+ — all downstream dependents (e.g. customers+)N+expr — N levels upstream (e.g. 2+kind:dbt)expr+N — N levels downstream (e.g. group:sales+1)N+expr+M — N up, M down (e.g. 1+key:customers+2)Selection strings (work identically in UI, CLI, and Python):
# By metadata
tag:priority=high and kind:dbt
group:sales or group:marketing
not kind:dbt
owner:team@company.com
# With traversals
+kind:dbt # all upstream of dbt assets
group:sales+ # group:sales + all downstream
2+key:customers # customers + 2 levels upstream
# With functions
sinks(group:analytics) # terminal assets in group
roots(kind:dbt) # source dbt assetsUsing in the CLI:
dg launch --assets "tag:priority=high and kind:dbt"
dg list defs --assets "group:sales"Using in Python (via from_coercible):
sel = dg.AssetSelection.from_coercible("tag:priority=high and kind:dbt")dg.AssetSelection.from_coercible() converts a selection string (or other coercible types) into an AssetSelection object. It accepts:
AssetSelection instance (returned as-is)AssetsDefinition or AssetKey objects# Parse a selection string
sel = dg.AssetSelection.from_coercible("tag:priority=high and kind:dbt")
# Pass to APIs that expect AssetSelection
job = dg.define_asset_job("my_job", selection=sel)# Select specific assets
dg.AssetSelection.assets("asset_a", "asset_b", "asset_c")
# Select all assets
dg.AssetSelection.all()
# Select by group
dg.AssetSelection.groups("analytics", "raw_data")
# Select by tag
dg.AssetSelection.tag("priority", "high")# Select asset and all upstream dependencies
dg.AssetSelection.assets("final_report").upstream()
# Select asset and all downstream dependencies
dg.AssetSelection.assets("raw_data").downstream()
# Select asset and immediate upstream only
dg.AssetSelection.assets("final_report").upstream(depth=1)selection_a = dg.AssetSelection.assets("a")
selection_b = dg.AssetSelection.assets("b")
# Union: assets in A OR B
selection_a | selection_b
# Intersection: assets in A AND B
selection_a & selection_b
# Difference: assets in A but not in B
selection_a - selection_b
# Example: All analytics assets except one
dg.AssetSelection.groups("analytics") - dg.AssetSelection.assets("excluded_asset")analytics_job = dg.define_asset_job(
name="analytics_job",
selection=dg.AssetSelection.groups("analytics").downstream(),
)These methods are only available via the Python API and have no string syntax equivalent:
dg.AssetSelection.key_prefixes(["warehouse", "staging"]) — select by key prefix (key:prefix* in string syntax is a partial alternative)dg.AssetSelection.key_substring("customer") — select by substring match on asset keyselection.required_multi_asset_neighbors() — include co-selected assets in non-subsettable multi-asset definitionsselection.materializable() — filter to only materializable (non-observable, non-external) assetsselection.upstream_source_assets() — select external/source assets that are upstream parentsselection.without_checks() — remove asset checks from a selectiondg.AssetSelection.checks_for_assets("my_asset") — select asset checks targeting specific assetsdg.AssetSelection.checks(my_check_key) — select specific asset checks by keydg.AssetSelection.all_asset_checks() — select all asset checks