This guide covers how to enhance your assets with rich metadata, custom properties, and explicit dependency management beyond what’s automatically inferred from your task graph.
@materialize
and asset_deps
accept either a string referencing an asset key or a full Asset
class instance. Using the Asset
class is the way to provide additional metadata like names, descriptions, and ownership information beyond just the key.
@materialize
decorator, the Asset
class provides more control over asset properties and metadata. Create Asset
instances to add organizational context and improve discoverability.
Asset
class accepts the following parameters:
key
(required): A valid URI that uniquely identifies your asset. This is the only required field.
properties
(optional): An AssetProperties
instance containing metadata about the asset.
Asset
instances, use them directly with the @materialize
decorator:
Asset.add_metadata()
add_metadata()
method on your Asset
instances. This prevents typos in asset keys and provides better IDE support:
add_asset_metadata()
utilityadd_asset_metadata()
function, which requires specifying the asset key:
asset_deps
parameter. This is useful when:
asset_deps
to explicitly declare which assets your materialization depends on. You can reference assets by key string or by full Asset
instance:
asset_deps
referencesAsset
instances when referencing assets that are completely external to Prefect. This provides metadata about external systems that Prefect wouldn’t otherwise know about:
Asset
instance with properties will completely replace all existing metadata. Partial updates are not supported - you must provide all the metadata you want to preserve.