Skip to content

Commit shards incrementally within a month#9

Merged
tamnd merged 1 commit into
mainfrom
incremental-shard-commits
Jul 19, 2026
Merged

Commit shards incrementally within a month#9
tamnd merged 1 commit into
mainfrom
incremental-shard-commits

Conversation

@tamnd

@tamnd tamnd commented Jul 19, 2026

Copy link
Copy Markdown
Owner

Why

Publish uploaded a whole month's shards in one hub commit after the entire .zst finished processing. A big month (2021-05 submissions is ~64 shards, comments months run to hundreds) takes hours, so:

  • the first commit and any proof the pipeline works were hours away
  • a restart mid-month redid the month from shard zero, re-uploading everything
  • every shard staged on disk until the single commit

What

Stream shards to the hub in batches of --commit-every (default 8, ARCTIC_COMMIT_EVERY) as they are written:

  • ProcessFileStream adds a StartShard and a per-shard callback to both the go and duckdb engines; ProcessFile/ProcessFileTo stay as thin wrappers.
  • After each batch, publish-progress.json records how far the month got (shards, records, bytes) and the uploaded shards are removed locally, keeping disk low on the comments months.
  • A restart reads the marker and resumes after the committed shards. The marker is engine-tagged because the two engines draw shard boundaries differently, so a cross-engine marker is ignored and the month restarts clean.
  • The ledger row and README still land once, at month end; then the marker is cleared.
  • --commit-every 0 keeps the old behavior (one commit at month end).

Tests

  • ProcessFileStream resume skips already-committed shards, emits only the rest, and the resumed shard holds the same rows.
  • Progress marker round-trips; the engine guard rejects a cross-engine marker.
  • End-to-end publish with a fake uploader: shards land in batches, local copies are dropped, the marker tracks then clears, and one ledger row is written; a seeded marker resumes from the right shard.

Default go build/vet/test and -race pass; -tags duckdb builds clean. (The pre-existing TestProcessFileComments failure under -tags duckdb is unrelated — it asserts go-engine skip counts while running the duckdb engine, and fails the same way on main.)

Publish uploaded a month's shards in one hub commit after the whole file
was processed. A big month runs for hours, so the first commit and any
proof the pipeline works were hours away, and a restart redid the entire
month from shard zero.

Stream the shards to the hub in batches of --commit-every (default 8) as
they are written. Each batch records how far the month has progressed in
publish-progress.json and drops the uploaded shards locally, so disk stays
low on the large comments months. A restart reads the marker and resumes
after the committed shards instead of reprocessing them; the marker is
engine-tagged since the go and duckdb engines draw shard boundaries
differently. The ledger row and README still land once, at month end.

ProcessFileStream carries the StartShard and per-shard callback for both
engines; ProcessFile and ProcessFileTo stay as thin wrappers.
@tamnd
tamnd merged commit 5510afc into main Jul 19, 2026
6 of 7 checks passed
@tamnd
tamnd deleted the incremental-shard-commits branch July 19, 2026 18:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant