Metadata turns a materialization into evidence. A row count, a total or a short preview, recorded every time the asset runs, lets you spot a bad day in the asset's history without opening the data.
There are two places to attach it. Runtime metadata changes on every run. If the asset returns a value for the IO manager to store, call context.add_output_metadata({"row_count": len(rows)}) before returning. If the asset writes its data itself (a warehouse table, a file), return dg.MaterializeResult(metadata={...}): Dagster records the materialization and the metadata, and does not call the IO manager.
Definition metadata is fixed, written on the decorator: @dg.asset(metadata={"docs": dg.MetadataValue.url("...")}). It describes the asset rather than one run.
Plain Python values work (ints, floats, strings, dicts). dg.MetadataValue makes the type explicit: .int, .float, .text, .md for a Markdown preview, .url, .path and .json.
The value is stored by the IO manager, and the row count is recorded with this materialization.