⏱ Scheduled pipelines
A clock cell makes a workbook run by itself. It is an ordinary formula that calls
every(...) or at(...); its value is the time of its last tick. Everything that
references the clock re-runs on each tick — resources reload, formulas recompute,
effects fire.
every(30) # every 30 seconds
every(minutes=5) # every 5 minutes
at("08:00", "17:30", days="mon-fri") # a schedule, local time
every(refresh_seconds, enabled=running) # configurable, with a pause switch
Try it
Refresh every (s): 5 Running: True Alert above (°C): 23.5| What | Now |
|---|---|
| Last tick | 23:06:02 |
| Latest reading | 23.68 °C — HIGH |
| Mean of 1 readings | 23.68 °C |
| Trend | ▁ |
| Last scheduled report | Tue 23:06 — 1 readings, min 23.68 °C, mean 23.68 °C, max 23.68 °C |
| Tariff (own 10 min timer) | 29.4 ct/kWh, loaded 23:06 |
How the pipeline is wired
flowchart LR
clock["clock<br/>every(5 s)"] --> reading["reading<br/>resource: fetch"]
reading --> history["history<br/>collect"]
history --> stats["latest · average · trend"]
stats --> status["status<br/>HIGH"]
status --> alert["alert<br/>effect: notify"]
schedule["report_clock<br/>at(08:00, 12:00, 17:30)"] --> report["report"]
A cell re-runs when something it references changes. reading mentions clock, so
it reloads on every tick. report mentions only report_clock (it reads HISTORY from
shared code, which is not a cell), so it runs three times a day and not on every reading.
When to use it
- Polling — refresh prices, sensor values, a queue length, or an API status every few
seconds or minutes (
reading). - Live dashboards — a note or dashboard that stays current on a wall screen.
- Scheduled reports — a summary at fixed times on working days (
report), exported by an effect or by--export. - Monitoring and alerts — an effect that acts when a value crosses a limit (
alert), or a heartbeat that proves the pipeline is alive (heartbeat). - Slow reference data — give one resource its own timer instead of the shared clock
(
tariffcallsevery(minutes=10)itself). - Time-dependent values — "days until the deadline", the age of the data.
Good to know
- Clocks tick only while the workbook runs: open in the app, or headless with
python -m reaktiv_workbook scheduled-pipeline.workbook.py --watch. Missed ticks are not caught up. For unattended jobs, run the CLI under cron, systemd, or a container. - One shared clock keeps a pipeline consistent: every cell sees the same tick. Use a
cell's own
every()only when it has its own rhythm. - The shortest interval is one second. Schedules use the local time of the machine.
- Keep the fetch in a resource (
~), so a slow request never blocks the sheet. - Keep state that must survive ticks in Shared code (
HISTORY); cells themselves stay functions of their inputs. - Ticks are not edits: they never mark the file as changed.