Skip to content

Commit

Permalink
add docs page on asset selection syntax (dagster-io#12871)
Browse files Browse the repository at this point in the history
## Summary & Motivation


## How I Tested These Changes
  • Loading branch information
sryza committed Mar 12, 2023
1 parent 49180eb commit 6f0d5b6
Show file tree
Hide file tree
Showing 3 changed files with 40 additions and 0 deletions.
4 changes: 4 additions & 0 deletions docs/content/_navigation.json
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,10 @@
{
"title": "Multi-Assets",
"path": "/concepts/assets/multi-assets"
},
{
"title": "Asset Selection Syntax",
"path": "/concepts/assets/asset-selection-syntax"
}
]
},
Expand Down
4 changes: 4 additions & 0 deletions docs/content/concepts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,10 @@ An asset is an object in persistent storage, such as a table, file, or persisted
title="Multi-assets"
href="/concepts/assets/multi-assets"
></ArticleListItem>
<ArticleListItem
title="Asset selection syntax"
href="/concepts/assets/asset-selection-syntax"
></ArticleListItem>
</ArticleList>

---
Expand Down
32 changes: 32 additions & 0 deletions docs/content/concepts/assets/asset-selection-syntax.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
title: Asset Selection Syntax | Dagster
description: To specify an asset selection, Dagster supports a simple query syntax.
---

# Asset Selection Syntax

To specify an asset selection as a string, Dagster supports a simple query syntax. This selection syntax is accepted in a few different places:

- The `list` and `materialize` commands in the [asset command-line interface](/\_apidocs/cli#dagster-asset).
- The asset filter text box on the asset graph page, in the UI.
- The `selection` parameter of <PyObject object="define_asset_job" />. (This parameter alternatively accepts an <PyObject object="AssetSelection"/> object, which supports more complex selections built from compositions of Python objects.)

It works as follows:

- A query includes a list of clauses. Clauses are separated by commas, except in the case of the `selection` parameter of <PyObject object="define_asset_job" />, where each clause is a separate element in a list.
- A clause can be an asset key, in which case that asset is selected.
- An asset key with multiple components can be specified by inserting slashes between the components.
- A clause can be an asset key preceded by `*`, in which case that asset and all of its ancestors (upstream dependencies) are selected.
- A clause can be an asset key followed by `*`, in which case that asset and all of its descendents (downstream dependencies) are selected.
- A clause can be an asset key followed by any number of `+`s, in which case that asset and descendents up to that many hops away are selected.
- A clause can be an asset key preceded by any number of `+`s, in which case that asset and ancestors up to that many hops away are selected.

**Clause examples**

- `some_asset`: select "some_asset" itself
- `my/prefixed/asset`: select the asset whose <PyObject object="AssetKey"/> in Python is `AssetKey(["my", "prefixed", "asset"])`
- `*some_asset`: select "some_asset" and all ancestors (upstream dependencies).
- `some_asset*`: select "some_asset" and all descendants (downstream dependencies).
- `*some_asset*`: select "some_asset" and all of its ancestors and descendants.
- `+some_asset`: select "some_asset" and its direct parents.
- `some_asset+++`: select "some_asset" and its children, its children's children, and its children's children's children.

0 comments on commit 6f0d5b6

Please sign in to comment.