-
Notifications
You must be signed in to change notification settings - Fork 1.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[docs] - Add asset owners to docs (DOC-155) (#21163)
## Summary & Motivation This PR adds a section for **Asset owners** to the **Asset metadata** documentation. It also updates the content of the Asset metadata page to accommodate the new owners section. ## How I Tested These Changes 👀
- Loading branch information
1 parent
569541f
commit 913c358
Showing
3 changed files
with
55 additions
and
14 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -13,25 +13,30 @@ By the end of this guide, you'll understand how to attach metadata to assets and | |
|
||
## How it works | ||
|
||
Attaching metadata to an asset is done using the `metadata` argument and a dictionary of key/value pairs. Keys must be a string, but values can: | ||
There are two main types of metadata in Dagster: | ||
|
||
- Be any of the <PyObject object="MetadataValue" /> classes provided by Dagster | ||
- Primitive Python types, which Dagster will convert to the appropriate <PyObject object="MetadataValue" /> | ||
- [**Definition metadata**](#attaching-definition-metadata) is information that's fixed or doesn't frequently change. For example, definition metadata could be the storage location of a table, a link the asset's definition in GitHub, or who owns the asset. | ||
- [**Runtime, or materialization metadata**](#attaching-materialization-metadata) is information that changes after a materialization occurs. This could be how many records were processed or how long an asset took to materialize. | ||
|
||
How metadata is attached to an asset depends on the type of metadata being attached. Refer to the following sections for more details. | ||
|
||
--- | ||
|
||
## Defining metadata | ||
## Attaching definition metadata | ||
|
||
There are two main types of metadata in Dagster: | ||
Dagster supports attaching a few different types of definition metadata: | ||
|
||
- [**Arbitrary metadata**](#arbitrary-metadata-using-the-metadata-parameter), such as the storage location of the table produced by the asset | ||
- [**Asset owners**](#asset-owners), which are the people and/or teams who own the asset | ||
|
||
- **Definition metadata** is information that's fixed or doesn't frequently change. For example, definition metadata could be the expected columns an asset should produce or a link to its definition in GitHub. | ||
- **Runtime, or materialization metadata** is information that changes after a materialization occurs. This could be how many records were processed, or how long an asset took to materialize. | ||
### Arbitrary metadata using the metadata parameter | ||
|
||
### Definition metadata | ||
Attaching arbitrary metadata to an asset is done using the `metadata` argument and a dictionary of key/value pairs. Keys must be a string, but values can: | ||
|
||
Definition metadata is attached to the asset's definition using the `metadata` argument. In the following example, we attached the storage location of the table produced by the asset: | ||
- Be any of the <PyObject object="MetadataValue" /> classes provided by Dagster | ||
- Primitive Python types, which Dagster will convert to the appropriate <PyObject object="MetadataValue" /> | ||
|
||
In the following example, we attached the storage location of the table produced by the asset: | ||
|
||
```python file=/concepts/assets/asset_definition_metadata.py startafter=start endbefore=end | ||
from dagster_duckdb import DuckDBResource | ||
|
@@ -53,12 +58,37 @@ def small_petals(duckdb: DuckDBResource) -> None: | |
) | ||
``` | ||
|
||
### Materialization metadata | ||
### Asset owners | ||
|
||
<Note> | ||
<strong>Did you know?</strong> If using Dagster+ Pro, you can create | ||
asset-based alerts that will automatically notify an asset's owners when | ||
triggered. Refer to the{" "} | ||
<a href="/dagster-plus/managing-deployments/alerts"> | ||
Dagster+ alert documentation | ||
</a>{" "} | ||
for more information. | ||
</Note> | ||
|
||
An asset can have multiple owners, defined using the `owners` argument on the <PyObject object="asset" decorator /> decorator. This argument accepts a dictionary of owners, where each value is either an individual email address or a team. Teams must include a `team:` prefix; for example: `team:data-eng`. | ||
|
||
The asset in the following example has two owners: `[email protected]` and the `data-eng` team. | ||
|
||
```python file=/concepts/metadata-tags/asset_owners.py | ||
from dagster import asset | ||
|
||
|
||
@asset(owners=["[email protected]", "team:data-eng"]) | ||
def leads(): ... | ||
``` | ||
|
||
--- | ||
|
||
## Attaching materialization metadata | ||
|
||
To add materialization metadata to an asset, you'll need to: | ||
Attaching materialization metadata to an asset is accomplished by returning a <PyObject object="MaterializeResult" /> object containing a `metadata` parameter. This parameter accepts a dictionary of key/value pairs, where keys must be a string. | ||
|
||
- Return a <PyObject object="MaterializeResult" /> object with the `metadata` parameter | ||
- Use the <PyObject object="MetadataValue" /> utility class to wrap the data, ensuring it displays correctly in the UI | ||
When specifying values, use the <PyObject object="MetadataValue" /> utility class to wrap the data, ensuring it displays correctly in the UI. Values can also be primitive Python types, which Dagster will convert to the appropriate <PyObject object="MetadataValue" />. | ||
|
||
In the following example, we added a row count and preview to a `topstories` asset: | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
5 changes: 5 additions & 0 deletions
5
examples/docs_snippets/docs_snippets/concepts/metadata-tags/asset_owners.py
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
from dagster import asset | ||
|
||
|
||
@asset(owners=["[email protected]", "team:data-eng"]) | ||
def leads(): ... |
913c358
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Deploy preview for dagster-docs ready!
✅ Preview
https://dagster-docs-ejb2e7fxp-elementl.vercel.app
https://master.dagster.dagster-docs.io
Built with commit 913c358.
This pull request is being automatically deployed with vercel-action