docs/v3/concepts/assets.mdx
<span class="badge cloud"></span>
Assets in Prefect represent any outcome or output of your Prefect workflows. They provide an interface to model all forms of data and model lineage, track dependencies between data transformations, and monitor the health of pipelines at the asset level rather than just the compute level.
An asset is fundamentally defined by its key, a URI that uniquely identifies an asset, often specifying an external storage system in which that asset lives.
Asset keys serve as both identifiers and organizational structures—assets are automatically grouped by their URI scheme (e.g., s3://, postgres://, snowflake://) and can be hierarchically organized based on their path structure.
Assets exist in three primary states within Prefect:
A materialization occurs when a workflow mutates an asset through creation, updating, or overwriting. Materializations are declared using the @materialize decorator, which functions as a specialized task decorator that tracks asset creation intent.
The materialization process operates on an "intent to materialize" model: when a function decorated with @materialize executes, Prefect records the materialization attempt. Success or failure of the materialization is determined by the underlying task's execution state.
from prefect.assets import materialize
@materialize("s3://data-lake/processed/customer-data.csv")
def process_customer_data():
# Asset materialization logic
pass
A reference occurs when an asset appears as an upstream dependency in another asset's materialization. References are automatically inferred from the task execution graph—when the output of one materialization flows as input to another, the dependency relationship is captured.
References can also be explicitly declared through the asset_deps parameter, which is particularly useful for modeling dependencies on external systems or when the task graph alone doesn't fully capture the data dependencies.
Asset definitions include optional metadata about that asset. These asset properties should have one source of truth to avoid conflicts. When you materialize an asset with properties, those properties perform a complete overwrite of all metadata fields for that asset.
Updates to asset metadata occur at runtime from any workflow that specifies metadata fields.
Asset dependencies are determined through two complementary mechanisms:
Task graph inference: When materialized assets flow through task parameters, Prefect automatically constructs the dependency graph. Each materialization acts as a dependency accumulation point, gathering all upstream assets and serving as the foundation for downstream materializations.
Explicit declaration: The asset_deps parameter allows direct specification of asset dependencies, enabling modeling of relationships that aren't captured in the task execution flow.
from prefect.assets import materialize
@materialize(
"s3://warehouse/enriched-data.csv",
asset_deps=["postgres://db/reference-tables", "s3://external/vendor-data.csv"]
)
def enrich_data():
# Explicitly depends on external database and vendor data
pass
The backend will track these dependencies across workflow boundaries, exposing a global view of asset dependencies within your workspace.
Assets support rich metadata through the AssetProperties class, which provides organizational context and improves discoverability:
Additionally, assets support dynamic metadata through the add_asset_metadata() function, allowing runtime information like row counts, processing times, and data quality metrics to be attached to materialization events.
Currently asset health provides a visual indicator of the operational status of data artifacts based on their most recent materialization attempt:
This health model enables data teams to quickly identify problematic data pipelines at the artifact level, complementing traditional task-level monitoring with data-centric observability. Soon these statuses will be backed by a corresponding event.
Assets integrate deeply with Prefect's event system, automatically emitting structured events that enable downstream automation and monitoring:
prefect.asset.materialization.{succeeded|failed} and are emitted when assets are referenced by the @materialize decorator, with status determined by the underlying task execution state.prefect.asset.referenced and are emitted for all upstream assets when a materialization occurs, independent of success or failure.Asset events follow specific emission patterns based on task execution state:
prefect.asset.materialization.succeeded for downstream assets and prefect.asset.referenced for upstream assetsprefect.asset.materialization.failed for downstream assets and prefect.asset.referenced for upstream assetsReference events are always emitted for upstream assets regardless of materialization success, enabling comprehensive dependency tracking even when downstream processes fail.
Materialization events include any metadata added during task execution through add_asset_metadata(), while reference events contain basic asset identification information. This enables rich event-driven automation based on both asset state changes and associated metadata.
Assets are automatically organized in the Prefect UI based on their URI structure:
s3://, postgres://) are grouped together