From b596be918a74cd7845330129c329c665da1319d3 Mon Sep 17 00:00:00 2001 From: Erin Cochran Date: Wed, 22 May 2024 16:05:55 -0400 Subject: [PATCH] [docs] - Add guide for schedule timezone execution (DOC-238) (#22034) ## Summary & Motivation This PR splits the timezone content in the Schedules concept page out into its own guide. ## How I Tested These Changes eyes, local, `dagster dev` for examples --- .../customizing-executing-timezones.mdx | 150 ++++++++++++++++++ .../automation/schedules/examples.mdx | 2 +- .../schedules.mdx | 2 +- .../partition_with_timezone.py | 5 + .../schedules/schedules.py | 2 +- 5 files changed, 158 insertions(+), 3 deletions(-) create mode 100644 docs/content/concepts/automation/schedules/customizing-executing-timezones.mdx create mode 100644 examples/docs_snippets/docs_snippets/concepts/partitions_schedules_sensors/partition_with_timezone.py diff --git a/docs/content/concepts/automation/schedules/customizing-executing-timezones.mdx b/docs/content/concepts/automation/schedules/customizing-executing-timezones.mdx new file mode 100644 index 000000000000..e37d7c3c8fa5 --- /dev/null +++ b/docs/content/concepts/automation/schedules/customizing-executing-timezones.mdx @@ -0,0 +1,150 @@ +--- +title: "Customizing a schedule's executing timezone | Dagster Docs" +description: "By default, schedules without a set timezone execute in UTC. Learn to specify custom timezones on your Dagster schedules." +--- + +# Customizing a schedule's executing timezone + +[Schedules](/concepts/partitions-schedules-sensors/schedules) that don't have a set timezone will, by default, execute in [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time). By the end of this guide, you'll know how to: + +- Set custom timezones on schedule definitions +- Set custom timezones on partitioned jobs +- Account for the impact of Daylight Savings Time on schedule execution times + +--- + +## Prerequisites + +To follow this guide, you need to be familiar with: + +- [Schedules](/concepts/partitions-schedules-sensors/schedules) +- Jobs, either [asset](/concepts/assets/asset-jobs) or [op-based](/concepts/ops-jobs-graphs/op-jobs) +- [Partitions](/concepts/partitions-schedules-sensors/partitions) (Optional) + +--- + +## Setting timezones on schedule definitions + +Using the `execution_timezone` parameter allows you to specify a timezone for the schedule on the following objects: + +- +- +- + +This parameter accepts any [`tz` timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). For example, the following schedule will execute **every day at 9:00 AM in US Pacific time (America/Los_Angeles)**: + +```python file=concepts/partitions_schedules_sensors/schedules/schedules.py startafter=start_timezone endbefore=end_timezone +my_timezone_schedule = ScheduleDefinition( + job=my_job, cron_schedule="0 9 * * *", execution_timezone="America/Los_Angeles" +) +``` + +--- + +## Setting timezones on partitioned jobs + +Schedules constructed from partitioned jobs execute in the timezone defined on the partition's config. Partitions definitions have a `timezone` parameter, which accepts any [`tz` timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). + +For example, the following partition uses the **US Pacific (America/Los_Angeles)** timezone: + +```python file=concepts/partitions_schedules_sensors/partition_with_timezone.py +from dagster import DailyPartitionsDefinition + +daily_partition = DailyPartitionsDefinition( + start_date="2024-05-20", timezone="America/Los_Angeles" +) +``` + +--- + +## Execution times and Daylight Savings Time + +When Daylight Savings Time (DST) begins and ends, there may be some impact on your schedules' execution times. + +### Impact on daily schedules + +Because of DST transitions, it's possible to specify an execution time that doesn't exist for every scheduled interval. + +Let's say you have a **schedule that executes every day at 2:30 AM.** On the day DST begins, time jumps from 2:00AM to 3:00AM, which means the time of 2:30 AM won't exist. + +Dagster would instead run the schedule at the next time that exists, which would be 3:00 AM: + +```markdown +# DST begins: time jumps forward an hour at 2:00 AM + +- 12:30 AM +- 1:00 AM +- 1:30 AM +- 3:00 AM ## time transition; schedule executes +- 3:30 AM +- 4:00 AM +``` + +It's also possible to specify an execution time that exists twice on one day every year. + +Let's say you have a **schedule that executes every day at 1:30 AM.** On the day DST ends, the hour from 1:00 AM to 2:00 AM repeats, which means the time of 1:30 AM will exist twice. This means there are two possible times the schedule could run. + +In this case, Dagster would execute the schedule at the second iteration of 1:30 AM: + +```markdown +# DST ends: time jumps backward an hour at 2:00 AM + +- 12:30 AM +- 1:00 AM +- 1:30 AM +- 1:00 AM ## time transition +- 1:30 AM ## schedule executes +- 2:00 AM +``` + +### Impact on hourly schedules + +Hourly schedules are unaffected by daylight savings time transitions. Schedules will continue to run exactly once an hour, even as DST ends and the hour from 1:00 AM to 2:00 AM repeats. + +Let's say you have a **schedule that executes hourly at 30 minutes past the hour.** On the day DST ends, the schedule would run at 12:30 AM and both instances of 1:30 AM before proceeding normally at 2:30 AM: + +```markdown +# DST ends: time jumps backward an hour at 2:00 AM + +- 12:30 AM ## schedule executes +- 1:00 AM +- 1:30 AM ## schedule executes +- 1:00 AM ## time transition +- 1:30 AM ## schedule executes +- 2:00 AM +- 2:30 AM ## schedule executes +``` + +--- + +## APIs in this guide + +| Name | Description | +| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| | Decorator that defines a schedule that executes according to a given cron schedule. | +| | Class for schedules. | +| | A function that constructs a schedule whose interval matches the partitioning of a partitioned job. | +| | A function that constructs a schedule that materializes a set of specified dbt resources. | + +--- + +## Related + + + + + + + diff --git a/docs/content/concepts/automation/schedules/examples.mdx b/docs/content/concepts/automation/schedules/examples.mdx index e16c476575f6..d32e64af51aa 100644 --- a/docs/content/concepts/automation/schedules/examples.mdx +++ b/docs/content/concepts/automation/schedules/examples.mdx @@ -456,7 +456,7 @@ This example demonstrates how to customize the timezone a schedule executes in. ```python file=concepts/partitions_schedules_sensors/schedules/schedules.py startafter=start_timezone endbefore=end_timezone my_timezone_schedule = ScheduleDefinition( - job=my_job, cron_schedule="0 9 * * *", execution_timezone="US/Pacific" + job=my_job, cron_schedule="0 9 * * *", execution_timezone="America/Los_Angeles" ) ``` diff --git a/docs/content/concepts/partitions-schedules-sensors/schedules.mdx b/docs/content/concepts/partitions-schedules-sensors/schedules.mdx index e44ebee852cd..ceb8aa78fc37 100644 --- a/docs/content/concepts/partitions-schedules-sensors/schedules.mdx +++ b/docs/content/concepts/partitions-schedules-sensors/schedules.mdx @@ -217,7 +217,7 @@ For example, the following schedule executes daily at 9AM in US/Pacific time: ```python file=concepts/partitions_schedules_sensors/schedules/schedules.py startafter=start_timezone endbefore=end_timezone my_timezone_schedule = ScheduleDefinition( - job=my_job, cron_schedule="0 9 * * *", execution_timezone="US/Pacific" + job=my_job, cron_schedule="0 9 * * *", execution_timezone="America/Los_Angeles" ) ``` diff --git a/examples/docs_snippets/docs_snippets/concepts/partitions_schedules_sensors/partition_with_timezone.py b/examples/docs_snippets/docs_snippets/concepts/partitions_schedules_sensors/partition_with_timezone.py new file mode 100644 index 000000000000..9e87c03f6b96 --- /dev/null +++ b/examples/docs_snippets/docs_snippets/concepts/partitions_schedules_sensors/partition_with_timezone.py @@ -0,0 +1,5 @@ +from dagster import DailyPartitionsDefinition + +daily_partition = DailyPartitionsDefinition( + start_date="2024-05-20", timezone="America/Los_Angeles" +) diff --git a/examples/docs_snippets/docs_snippets/concepts/partitions_schedules_sensors/schedules/schedules.py b/examples/docs_snippets/docs_snippets/concepts/partitions_schedules_sensors/schedules/schedules.py index 3f76e53360cd..06d6b2c1a805 100644 --- a/examples/docs_snippets/docs_snippets/concepts/partitions_schedules_sensors/schedules/schedules.py +++ b/examples/docs_snippets/docs_snippets/concepts/partitions_schedules_sensors/schedules/schedules.py @@ -64,7 +64,7 @@ def configurable_job_schedule(context: ScheduleEvaluationContext): # start_timezone my_timezone_schedule = ScheduleDefinition( - job=my_job, cron_schedule="0 9 * * *", execution_timezone="US/Pacific" + job=my_job, cron_schedule="0 9 * * *", execution_timezone="America/Los_Angeles" ) # end_timezone