Implementation:Dagster io Dagster MonthlyPartitionsDefinition API

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

Overview

Concrete tool for monthly time-windowed partitioning provided by the Dagster core library.

Description

MonthlyPartitionsDefinition is a subclass of TimeWindowPartitionsDefinition that generates one partition per calendar month. Given a start date, it automatically produces partition keys for every month from the start date up to the current month (or an optional end date). Each partition key is a date string representing the first day of the month (e.g., "2023-01-01", "2023-02-01").

The class supports offsets for day, hour, and minute to customize when each monthly partition begins within the month. For example, setting day_offset=15 creates partitions that run from the 15th of one month to the 15th of the next. Timezone support ensures correct partition boundaries across daylight saving transitions.

Usage

Import and use when you need to partition an asset or job by calendar month. Attach the definition to an asset via the partitions_def parameter. The asset function then receives the partition key through context.partition_key and uses it to scope data processing.

Code Reference

Source Location

• Repository: dagster
• File: python_modules/dagster/dagster/_core/definitions/partitions/definition/time_window_subclasses.py:L268

Signature

class MonthlyPartitionsDefinition(TimeWindowPartitionsDefinition):
    def __init__(
        self,
        start_date: Union[datetime.datetime, str],
        end_date: Union[datetime.datetime, str, None] = None,
        minute_offset: int = 0,
        hour_offset: int = 0,
        day_offset: int = 1,
        timezone: Optional[str] = None,
        fmt: Optional[str] = None,
        end_offset: int = 0,
        exclusions: Optional[Sequence[Union[str, datetime.datetime]]] = None,
    )

Import

from dagster import MonthlyPartitionsDefinition

# or

import dagster as dg
dg.MonthlyPartitionsDefinition

I/O Contract

Inputs

Name	Type	Required	Description
start_date	Union[datetime.datetime, str]	Yes	The first month to include in the partition set (e.g., "2023-01-01").
end_date	Union[datetime.datetime, str, None]	No	Optional upper bound; if omitted, partitions grow to the current month.
minute_offset	int	No	Minute within the hour at which each partition starts (default 0).
hour_offset	int	No	Hour within the day at which each partition starts (default 0).
day_offset	int	No	Day of the month at which each partition starts (default 1).
timezone	Optional[str]	No	IANA timezone string for partition boundaries (e.g., "US/Eastern").
fmt	Optional[str]	No	strftime format string for partition keys (default "%Y-%m-%d").
end_offset	int	No	Number of additional partitions to include beyond the current time.
exclusions	Optional[Sequence[Union[str, datetime.datetime]]]	No	Specific months to exclude from the partition set.

Outputs

Name	Type	Description
instance	TimeWindowPartitionsDefinition	A partition definition that generates monthly partition keys as date strings (e.g., "2023-01-01").

Usage Examples

Monthly Orders Asset with DuckDB

import dagster as dg

partitions = dg.MonthlyPartitionsDefinition(start_date="2023-01-01")

@dg.asset(partitions_def=partitions, kinds={"duckdb"})
def monthly_orders(
    context: dg.AssetExecutionContext, duckdb: DuckDBResource
) -> dg.MaterializeResult:
    partition_key = context.partition_key
    with duckdb.get_connection() as conn:
        conn.execute(
            f"INSERT INTO monthly_orders SELECT * FROM stg_orders "
            f"WHERE order_date >= '{partition_key}'"
        )
    return dg.MaterializeResult(metadata={"partition": partition_key})

Related Pages

Implements Principle

• Principle:Dagster_io_Dagster_Time_Based_Partitioning