From 565d6d2433eaec54c5a6155cb58dc47b839c8a2c Mon Sep 17 00:00:00 2001 From: stroblme Date: Fri, 28 Aug 2026 14:55:06 +0200 Subject: [PATCH] Docs: warn about the half-filled bucket, and say which node schedules Say on the querying-chart page that a flow doing its own binning has to drop the newest bucket, as the observability endpoints already do, and make plain that `inject` is the scheduler while `trigger` is a debounce and hold. --- docs/interface/dashboards.md | 9 +++++++++ docs/reference/node-types.md | 11 +++++++---- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/interface/dashboards.md b/docs/interface/dashboards.md index ca48fd1..cb36509 100644 --- a/docs/interface/dashboards.md +++ b/docs/interface/dashboards.md @@ -92,6 +92,15 @@ it, so swapping the store is a change to one flow and nothing else. The answer also states what it was computed for, so an answer to a different question is ignored rather than two charts overwriting each other's picture. +!!! note "Drop the bucket that is still filling" + + The request carries a window and an interval, and the binning is the flow's + own work — so the newest bucket only ever holds the part of an interval + that has elapsed. Drawn, it reads as a fall that never happened. The + engine's own [Activity charts](index.md#activity) end on the last closed + bin for that reason; a flow answering a chart has to drop or hold back its + newest bucket the same way. + ## Media tiles A media widget draws what its message points at: a picture, a clip with diff --git a/docs/reference/node-types.md b/docs/reference/node-types.md index 8753fb3..bb691a6 100644 --- a/docs/reference/node-types.md +++ b/docs/reference/node-types.md @@ -126,7 +126,7 @@ thing configured elsewhere. ### Inject -**`inject`** — emit a value on request, on a timer, or when the flow starts. +**`inject`** — emit a value on request, on a schedule, or when the flow starts. | Setting | Default | Notes | |---|---|---| @@ -137,8 +137,9 @@ thing configured elsewhere. | `at_start` | `false` | emit once when the flow starts | | `start_delay` | `1.0` | how long to wait before that first emission | -The most-placed trigger in a real installation — mostly as a button someone -presses. +The scheduler: a `cron` expression here is what makes a flow run by the clock. +It is also the most-placed node in a real installation — mostly as a button +someone presses. ### Delay & schedule @@ -169,7 +170,9 @@ needs a busy cascade slot waits for one. ### Trigger -**`trigger`** — send one value now and another once things go quiet. +**`trigger`** — send one value now and another once things go quiet. Despite +the name, a debounce and hold rather than a scheduler: everything it sends +starts from a value arriving. For a cron tick, see [`inject`](#inject). | Setting | Default | Notes | |---|---|---|