Implementation:Dagster io Dagster Definitions Decorator

Attribute	Value
Title	Definitions Decorator
Category	Implementation
Domains	Data_Engineering, Project_Structure
Repository	Dagster_io_Dagster
Source	`python_modules/dagster/dagster/components/definitions.py:L50`

Overview

Concrete decorator and loader for folder-based definition discovery provided by the Dagster core library.

Description

The @definitions decorator marks a function as an entry point for loading Dagster definitions. It provides a lazy loading mechanism for Definitions objects, which is the preferred approach over directly instantiating Definitions at module import time. The decorator wraps the function in a LazyDefinitions object that defers execution until Dagster's loading mechanisms invoke it.

The decorated function can optionally accept a ComponentLoadContext parameter, which is populated when loaded in the context of autoloaded defs folders in the dg project layout.

Usage

Use as the entry point for any Dagster project. The decorator can be used with or without a ComponentLoadContext parameter. Combine with load_from_defs_folder() for automatic discovery of assets from a directory tree.

Code Reference

Source Location

python_modules/dagster/dagster/components/definitions.py:L50

Signature

@public
def definitions(
    fn: Union[Callable[[], Definitions], Callable[[ComponentLoadContext], Definitions]],
) -> Callable[..., Definitions]:
    """Decorator that marks a function as an entry point for loading Dagster definitions.

    The decorated function must return a Definitions object and can optionally accept a
    ComponentLoadContext parameter.

    Args:
        fn: A function that returns a Definitions object. Either:
            - Accept no parameters: () -> Definitions
            - Accept a ComponentLoadContext: (ComponentLoadContext) -> Definitions

    Returns:
        A callable (LazyDefinitions) that will invoke the original function
        and return its Definitions object when called.
    """
    ...

@record
class LazyDefinitions(Generic[T_Defs]):
    """An object that can be invoked to load a set of definitions."""
    load_fn: Callable[..., T_Defs]
    has_context_arg: bool

    def __call__(self, context: Optional[ComponentLoadContext] = None) -> T_Defs:
        ...

Import

from dagster import definitions, Definitions, load_from_defs_folder

Or via the dg namespace:

import dagster as dg

@dg.definitions
def defs():
    return dg.Definitions(...)

I/O Contract

Inputs

fn: A callable that returns a Definitions object. Can accept zero parameters or one ComponentLoadContext parameter.
Project root path: When using load_from_defs_folder(), the path to the project root containing the defs/ directory.
Resources dict: Optional mapping of resource keys to resource objects, passed to Definitions(resources={...}).
defs/ folder: Directory tree containing Python modules with @asset functions and YAML component configurations.

Outputs

LazyDefinitions: A callable wrapper that defers definition loading until invoked.
Definitions: When invoked, returns a unified Definitions object containing all discovered assets, asset checks, resources, schedules, sensors, and jobs.

Usage Examples

Basic Usage Without Context

import dagster as dg


@dg.definitions
def defs():
    @dg.asset
    def sales_data():
        return [1, 2, 3]

    return dg.Definitions(assets=[sales_data])

With Resources

import dagster as dg
from dagster_duckdb import DuckDBResource


@dg.definitions
def defs():
    return dg.Definitions(
        resources={"duckdb": DuckDBResource(database=dg.EnvVar("DUCKDB_DATABASE"))},
    )

With Folder Loading and Merge

from pathlib import Path
import dagster as dg
from dagster import Definitions, load_from_defs_folder


@dg.definitions
def defs():
    return Definitions.merge(
        load_from_defs_folder(project_root=Path(__file__).parent),
        Definitions(
            resources={
                "duckdb": DuckDBResource(database=dg.EnvVar("DUCKDB_DATABASE")),
            }
        ),
    )

With ComponentLoadContext

import dagster as dg


@dg.definitions
def defs(context: dg.ComponentLoadContext):
    @dg.asset
    def sales_data():
        return load_data_from(context.path)

    return dg.Definitions(assets=[sales_data])

Recommended Project Structure

src/my_project/
  definitions.py          # @definitions entry point
  defs/
    assets.py             # @asset functions (auto-discovered)
    resources.py          # Resource configuration
    transform/
      defs.yaml           # DbtProjectComponent config
    ingestion/
      my_asset.py         # Auto-discovered assets
  pyproject.toml

Related Pages

Requires Environment

Environment:Dagster_io_Dagster_Python_3_10_Runtime

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment