Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add docs on per-schedule parameters #17000

Merged
merged 11 commits into from
Feb 6, 2025
93 changes: 90 additions & 3 deletions docs/v3/automate/add-schedules.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ There are several ways to create a schedule for a deployment:

- Through the Prefect UI
- With the `cron`, `interval`, or `rrule` parameters if building your deployment with the
[`serve` method](/v3/develop/write-flows/#serving-a-flow) of the `Flow` object or
[the `serve` utility](/v3/develop/write-flows/#serving-multiple-flows-at-once) for managing multiple flows simultaneously
[`serve` method](/v3/deploy/run-flows-in-local-processes#serve-a-flow) of the `Flow` object or
[the `serve` utility](/v3/deploy/run-flows-in-local-processes#serve-multiple-flows-at-once) for managing multiple flows simultaneously
Comment on lines +17 to +18
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these were broken

- If using [worker-based deployments](/v3/deploy/infrastructure-concepts/workers/)
- When you define a deployment with `flow.serve` or `flow.deploy`
- Through the interactive `prefect deploy` command
Expand Down Expand Up @@ -65,7 +65,24 @@ If using work pool-based deployments, the `deploy` method has the same schedule-

When `my_flow` is served with this interval schedule, it will run every 10 minutes beginning at midnight on January, 1, 2026 in the `America/Chicago` timezone:

```python
<CodeGroup>
```python prefect >= 3.1.16
from datetime import timedelta, datetime
from prefect.schedules import Interval

from myproject.flows import my_flow

my_flow.serve(
name="flowing",
schedule=Interval(
timedelta(minutes=10),
anchor_date=datetime(2026, 1, 1, 0, 0),
timezone="America/Chicago"
)
)
```

```python prefect < 3.1.16
from datetime import timedelta, datetime
from prefect.client.schemas.schedules import IntervalSchedule

Expand All @@ -83,6 +100,8 @@ my_flow.serve(
)
```

</CodeGroup>

### Create schedules in the terminal

You can create a schedule through the interactive `prefect deploy` command. You will be prompted to choose which type of schedule to create.
Expand Down Expand Up @@ -268,6 +287,74 @@ A 9 AM daily schedule with a DST-aware start date maintains a local 9 AM time th
with a UTC start date maintains a 9 AM UTC time.
</Note>

## Associate parameters with schedules
Using any of the above methods to create a schedule, you can bind parameters to your schedules.

For example, say you have a flow that sends an email.
Every day at 8:00 AM you want to send a message to one recipient, and at 8:05 AM you want to send a different message to another recipient.

Instead of creating independent deployments with different default parameters and schedules, you can bind parameters to the schedules themselves:

### Schedule parameters in Python

Whether using `.serve` or `.deploy`, you can pass `parameters` to your deployment `schedules`:

```python send_email_flow.py {13,17-20}
from prefect import flow
from prefect.schedules import Cron

@flow
def send_email(to: str, message: str = "Stop goofing off!"):
print(f"Sending email to {to} with message: {message}")

send_email.serve(
name="my-flow",
schedules=[
Cron(
"0 8 * * *",
parameters={"to": "jim.halpert@dundermifflin.com"}
),
Cron(
"5 8 * * *",
parameters={
"to": "dwight.schrute@dundermifflin.com",
"message": "Stop goofing off! You're assistant _to_ the regional manager!"
}
)
]
)
```
Note that our flow has a default `message` parameter, but we've overridden it for the second schedule.

This deployment will schedule runs that:

- Send "Stop goofing off!" to Jim at 8:00 AM every day
- Send "Stop goofing off! You're assistant _to_ the regional manager!" to Dwight at 8:05 AM every day

<Tip>
Use the same pattern to bind parameters to any schedule type in `prefect.schedules`.
You can provide one schedule via the `schedule` kwarg or multiple schedules via `schedules`.
</Tip>
zzstoatzz marked this conversation as resolved.
Show resolved Hide resolved

### Schedule parameters in `prefect.yaml`

You can also provide parameters to schedules in your `prefect.yaml` file.

```yaml prefect.yaml {4-11}
deployments:
name: send-email
entrypoint: send_email_flow.py:send_email
schedules:
- cron: "0 8 * * *"
parameters:
to: "jim.halpert@dundermifflin.com"
- cron: "5 8 * * *"
parameters:
to: "dwight.schrute@dundermifflin.com"
message: "Stop goofing off! You're assistant _to_ the regional manager!"
```


## How scheduling works

Prefect's `Scheduler` service evaluates each deployment's schedules and creates new runs appropriately. It starts
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -227,7 +227,7 @@ To deploy a flow with a schedule, you can use one of the following options:
```python schedules.py
from datetime import datetime, timedelta
from prefect import flow
from prefect.client.schemas.schedules import IntervalSchedule
from prefect.schedules import Interval


@flow(log_prints=True)
Expand All @@ -244,8 +244,8 @@ To deploy a flow with a schedule, you can use one of the following options:
# Run every 10 minutes starting from January 1, 2023
# at 00:00 Central Time
schedules=[
IntervalSchedule(
interval=timedelta(minutes=10),
Interval(
timedelta(minutes=10),
anchor_date=datetime(2023, 1, 1, 0, 0),
timezone="America/Chicago"
)
Expand Down
4 changes: 2 additions & 2 deletions docs/v3/resources/upgrade-to-prefect-3.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -287,15 +287,15 @@ my_flow.serve(
```python Prefect 3.0 {11}
from datetime import timedelta
from prefect import flow
from prefect.client.schemas.schedules import IntervalSchedule
from prefect.schedules import Interval

@flow
def my_flow():
pass

my_flow.serve(
name="my-flow",
schedules=[IntervalSchedule(interval=timedelta(minutes=1))]
schedules=[Interval(timedelta(minutes=1))]
)
```
</CodeGroup>