Implementation:Dagster io Dagster MaterializeResult API

Knowledge Sources	Dagster Dagster Docs
Domains	Data_Engineering, Observability
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete result class for returning materialization metadata from asset functions provided by the Dagster core library.

Description

The MaterializeResult class is the primary mechanism for returning structured metadata from asset functions. When an asset function returns a MaterializeResult, Dagster records the attached metadata in the event log and displays it in the UI. The class also supports inline asset check results, data versioning, and tags.

MaterializeResult is used instead of a bare return value when the asset needs to communicate information about what was produced beyond the data itself. It is particularly useful for assets that write data to external systems (where there is no return value to serialize) and need to report metrics like row counts, processing statistics, or quality indicators.

Usage

Import from the dagster package. Return a MaterializeResult instance from an asset function. When used inside a @asset-decorated function, the asset_key parameter is optional (it defaults to the current asset's key).

Code Reference

Source Location

• Repository: dagster
• File: python_modules/dagster/dagster/_core/definitions/result.py:L62-106

Signature

class MaterializeResult:
    def __new__(
        cls,
        asset_key: Optional[CoercibleToAssetKey] = None,
        metadata: Optional[RawMetadataMapping] = None,
        check_results: Optional[Sequence[AssetCheckResult]] = None,
        data_version: Optional[DataVersion] = None,
        tags: Optional[Mapping[str, str]] = None,
        value: T = NoValueSentinel,
    )

Import

from dagster import MaterializeResult

# or

import dagster as dg

dg.MaterializeResult(metadata={"key": "value"})

I/O Contract

Inputs

Name	Type	Required	Description
asset_key	CoercibleToAssetKey	No	The key of the asset being materialized. Optional when returned from a @asset-decorated function (defaults to the current asset key). Required in @multi_asset functions.
metadata	RawMetadataMapping	No	Dictionary of metadata key-value pairs to attach to the materialization event. Keys are strings; values can be int, float, str, markdown, JSON, URL, and other supported types.
check_results	Sequence[AssetCheckResult]	No	Inline asset check results to record alongside the materialization.
data_version	DataVersion	No	A version identifier for the data produced, enabling staleness detection and incremental computation.
tags	Mapping[str, str]	No	Tags to attach to the materialization event for categorization and filtering.
value	T	No	An optional value to pass to the I/O manager for serialization. Used when the asset has an I/O manager configured.

Outputs

Name	Type	Description
(return)	MaterializeResult	The result object returned from the asset function. Dagster processes this to record the materialization event with associated metadata.

Usage Examples

Basic Metadata Reporting

import dagster as dg

@dg.asset(kinds={"duckdb"})
def monthly_orders(
    context: dg.AssetExecutionContext, duckdb: DuckDBResource
) -> dg.MaterializeResult:
    partition_key = context.partition_key
    with duckdb.get_connection() as conn:
        result = conn.execute(
            f"SELECT COUNT(*) FROM orders WHERE date = '{partition_key}'"
        ).fetchone()
    return dg.MaterializeResult(
        metadata={"row_count": result[0], "partition": partition_key}
    )

Metadata with Inline Check Results

import dagster as dg

@dg.asset(
    kinds={"python"},
    check_specs=[dg.AssetCheckSpec(name="positive_count", asset="processed_data")],
)
def processed_data(duckdb: DuckDBResource) -> dg.MaterializeResult:
    with duckdb.get_connection() as conn:
        count = conn.execute("SELECT COUNT(*) FROM processed").fetchone()[0]
    return dg.MaterializeResult(
        metadata={"row_count": count, "status": "success"},
        check_results=[
            dg.AssetCheckResult(
                passed=count > 0,
                check_name="positive_count",
            )
        ],
    )

Rich Metadata Types

import dagster as dg

@dg.asset(kinds={"python"})
def analysis_report() -> dg.MaterializeResult:
    results = run_analysis()
    return dg.MaterializeResult(
        metadata={
            "row_count": results["count"],
            "accuracy": results["accuracy"],
            "preview": dg.MetadataValue.md(results["summary_table"]),
            "report_url": dg.MetadataValue.url("https://dashboard.example.com/report/123"),
        }
    )

Related Pages

Implements Principle

• Principle:Dagster_io_Dagster_Materialization_Metadata

Uses Heuristic

• Heuristic:Dagster_io_Dagster_Record_Over_Dataclass