duckstring refresh
Commands that ask for a Pond's data to be refreshed: now, on a recurring basis, or whenever an app queries it through a Tap. See Orchestration for how a Refresh behaves. Refreshes are meant to be placed on Outlets, though any deployed Pond accepts them.
Every command takes -c / --catchment, -m / --major and -v / --version; see CLI Overview.
refresh now
duckstring refresh now POND [--fresh-within DURATION] [--silent] [--watch]
Asks for data at least as fresh as the moment the command runs. Every Pond upstream that is older runs (an optional Source only if it has never run), and the result flows down to POND. Requests that arrive faster than the pipeline can serve them are paced to its slowest step. Opens the live status view until the Pond settles; --watch keeps it open, and --silent returns once the request is sent.
| Option | Default | Description |
|---|---|---|
--fresh-within, -f | none | Ask for data no older than this duration instead. Only the Ponds older than it run: the request stops at any Pond upstream that is already that fresh. |
refresh add
duckstring refresh add POND --every PERIOD [--start TIME [--on DAYS] [--until TIME]] [--name NAME] [--silent]
duckstring refresh add POND --continuous [--name NAME] [--silent]
Adds a recurring Refresh, which repeats the request:
- Every (
--everyalone): asks oncePERIODhas passed since the later of the last request and the last refresh of the data, so any other refresh restarts the count.duckstring refresh add reports --every 1drefreshesreportsdaily, and the data is at most a day plus the pipeline's run time old. - At set times (
--everywith--start): asks at each time on the gridSTART + k × PERIOD, whatever else refreshes the Pond. A Catchment that was down through some of them asks once, for the latest, when it returns. - Continuous (
--continuous, or--every 0s): asks whenever the Pond can take more, paced to the pipeline's slowest step.
A Pond can have any number of scheduled Refreshes and one --every or continuous Refresh. Adding another --every or continuous Refresh replaces it; adding one with an existing name replaces that one. Opens the live status view (a recurring Refresh keeps it open until Ctrl+C) unless --silent.
| Option | Default | Description |
|---|---|---|
--every, -e | required unless --continuous | The period, a duration such as 30s, 30m, 12h, 1d or 1h30m. |
--continuous | As fresh as the pipeline allows. The same as --every 0s. | |
--start, -s | none | Pin the Refresh to a schedule from this time: ISO 8601, or HH:MM for today in UTC. Needs a period. |
--on, -o | every day | With --start: only on these weekdays, such as MON,TUE,WED,THU,FRI. |
--until, -u | none | With --start: when the schedule ends, in ISO 8601. |
--name, -n | described from the options | A name, unique on this Pond, such as Daily at 06:00, Weekdays at 06:00, Every 30 min or Continuous. |
duckstring refresh add reports --every 1d --start 06:00 --on MON,TUE,WED,THU,FRI
refresh ls
duckstring refresh ls POND
Lists the Pond's recurring Refreshes, scheduled first, with their details and when each next asks.
refresh rm
duckstring refresh rm POND NAME
Removes a recurring Refresh by name. Runs already in progress finish. duckstring control sleep removes them all and clears outstanding demand.
refresh tap
A Tap refreshes a Pond whenever an app queries it. It has its own key, which reads the Pond's exposed tables, and a freshness policy: a query through the Tap sends the Pond a Refresh, for data no older than --fresh-within, when the newest request on the Pond, or with none waiting its freshness, is at least that old. Queries with any other key never send one. See Refreshing on Use with Taps.
A Tap belongs to one major version of its Pond. Taps are Catchment configuration and survive redeploys; removing the major version removes them. Managing Taps needs a full-access key.
A Tap on an App has no key. Every request the Catchment forwards to the App's process counts as a query, and so does every message from a browser on a WebSocket, at most once a second.
refresh tap add
duckstring refresh tap add POND --name NAME [--fresh-within DURATION]
Adds a Tap and prints its key. The key is shown once; only a hash of it is kept. A Tap on an App has no key to print.
| Option | Default | Description |
|---|---|---|
--name, -n | required | The Tap's name: letters, digits, ., _ and -, up to 64 characters. |
--fresh-within, -f | 0 | Send a Refresh on a query when the newest request on the Pond, or the data, is at least this old. The Refresh asks for data no older than this, so Ponds upstream that are already that fresh don't run. 0 refreshes on every query, except while a request is already waiting for the Pond to start a run. |
Durations combine units: 30s, 5m, 1h30m, 1d.
refresh tap ls
duckstring refresh tap ls POND
Lists the Pond's Taps with their policy, when each was last queried, and how many queries and Refreshes each has had. Keys are never shown.
refresh tap rotate
duckstring refresh tap rotate POND NAME
Prints a new key for the Tap. The old key stops working at once. A Tap on an App has no key, so it can't be rotated.
refresh tap rm
duckstring refresh tap rm POND NAME
Removes the Tap. Its key stops working at once, and runs it already caused finish.