Os metadados transformam uma materialização em evidência. Uma contagem de linhas, um total ou uma pré-visualização curta, registrados toda vez que o asset é executado, permitem identificar um dia ruim no histórico do asset sem abrir os dados.
Há dois lugares para anexá-los. Os metadados de execução mudam a cada execução. Se o asset retorna um valor para o IO manager guardar, chame context.add_output_metadata({"row_count": len(rows)}) antes de retorná-lo. Se o asset grava os próprios dados (uma tabela do warehouse, um arquivo), retorne dg.MaterializeResult(metadata={...}): o Dagster registra a materialização e os metadados, e não chama o IO manager.
Os metadados de definição são fixos e ficam no decorador: @dg.asset(metadata={"docs": dg.MetadataValue.url("...")}). Eles descrevem o asset, e não uma execução.
Valores comuns do Python funcionam (inteiros, decimais, strings, dicionários). dg.MetadataValue torna o tipo explícito: .int, .float, .text, .md para uma pré-visualização em Markdown, .url, .path e .json.
O IO manager guarda o valor e a contagem de linhas fica registrada com esta materialização.