Skip to main content

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.

OptionDefaultDescription
--fresh-within, -fnoneAsk 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 (--every alone): asks once PERIOD has 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 1d refreshes reports daily, and the data is at most a day plus the pipeline's run time old.
  • At set times (--every with --start): asks at each time on the grid START + 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.

OptionDefaultDescription
--every, -erequired unless --continuousThe period, a duration such as 30s, 30m, 12h, 1d or 1h30m.
--continuousAs fresh as the pipeline allows. The same as --every 0s.
--start, -snonePin the Refresh to a schedule from this time: ISO 8601, or HH:MM for today in UTC. Needs a period.
--on, -oevery dayWith --start: only on these weekdays, such as MON,TUE,WED,THU,FRI.
--until, -unoneWith --start: when the schedule ends, in ISO 8601.
--name, -ndescribed from the optionsA 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.

OptionDefaultDescription
--name, -nrequiredThe Tap's name: letters, digits, ., _ and -, up to 64 characters.
--fresh-within, -f0Send 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.