Skip to main content

​
Runbook: replay-split — replace unadjusted bars for a split symbol

When to run: A user reports wrong historical prices for a recently-split ticker; or sequency.corporate_actions.replay_status = 'pending' for a split you want to clear.

​
Prerequisites

  • SSH access to compute server (for binary location + env).
  • ALPACA_API_KEY / ALPACA_API_SECRET (sourced from /opt/sequency/config/corporate-actions.env on compute).
  • CH_URL pointing at data-server via vRack: http://10.0.0.2:8123.

​
Build

​
Dry-run first, always

Inspect:
  • Factor: matches the known corporate action (10.0 for a 10:1 split).
  • Price range: adjusted prices should be roughly pre-split-price / factor.
  • Current row counts: non-zero in all five tables; the 1min count is the dominant source of truth.

​
Real run

Phases logged in order:
  1. phase=delete_rollups — 5m/15m/1h/daily ALTER DELETEs submitted.
  2. phase=delete_1min — base-table ALTER DELETE submitted.
  3. phase=wait_mutations — polls system.mutations until drained.
  4. phase=insert_adjusted — bulk INSERTs via JSONEachRow; MVs auto-fire.
  5. phase=verify — post-replay counts logged.
Exit code 0 on success; 1 on any phase failure (CLI marks replay_status='failed').

​
What if it fails partway?

  • Mutation timeout — CH is probably busy. Wait; re-run the CLI; it’ll skip any already-done mutations via the is_done filter and proceed to INSERT.
  • Alpaca error — check curl -s -o /dev/null -w '%{http_code}' https://data.alpaca.markets/v2/stocks/BKNG/bars?... with your creds. Rerun the CLI once resolved.
  • INSERT partial success — re-run with --force; it re-DELETES and re-INSERTs idempotently.
  • Interrupted mid-run (CTRL+C) — the CLI catches SIGINT and tries to mark replay_status='failed' with a fresh 5-second context. If that succeeds, re-run normally (with --force if you see replay_status='failed'). If the CLI couldn’t reach CH during shutdown, replay_status will stay at whatever it was (likely 'pending'); re-run without --force.

​
After a successful run

If pattern-detector was mid-cycle during replay, its next scheduled run picks up the adjusted data automatically. To force an immediate recompute for the symbol:
(Endpoint exists only if PD exposes one; otherwise wait for the next 5-min tick.)

​
What the CLI does NOT do

  • Snapshot to S3 (re-fetching is cheap — Alpaca is the source of truth).
  • Update the FalkorDB graph’s Stock.split_replay_pending flag (not needed for an operator-run sync replay; the graph stays consistent because PD reads from the same CH tables we just fixed).
  • Adjust options-chain strikes (separate issue).
  • Handle multiple symbols per invocation (script a bash loop if needed).