Chart bindings
How charts reference datasets — live bindings, snapshots, revisions, and concurrency.
A ChartBinding links a chart spec to data. Bindings come in two modes:
| Mode | Behavior |
|---|---|
| Live | Reflects the dataset as it changes; refreshed manually or on an authorized schedule |
| Snapshot | Pinned to one frozen dataset version; the rendered chart never changes underneath viewers |
Live bindings and captures
A live binding renders from the dataset's current evaluated capture. A refresh is explicit: manual, or on a schedule attached to the binding. If the source read fails, the prior capture is retained — a live chart never silently goes blank because its source was briefly unavailable.
Snapshot bindings
A snapshot binding pins one dataset version — the chart, its exports, and its shares all reference the same frozen data. Independent snapshot copies can be made from the editor when you need two divergent frozen views.
Concurrency and idempotency
Writes to chart bindings are guarded by two mechanisms:
- Optimistic locking — updates carry an expected revision counter; a conflicting write is rejected rather than overwriting another edit.
- Idempotency keys — retried requests with the same key and identical body safely return the first result; reusing a key for a different action fails.
Version pinning
Because datasets version their captures and artifacts version their revisions, every rendered output can state exactly which spec revision and which data version produced it. See exports.