Skip to content

GS: ClickHouse 26.8+ commit-cursor append refresh #403

Description

@BorisTyshkevich

Parent: #398
Depends on: #400, #401, #402

Design:

  • docs/design/google-sheets/append-refresh.md
  • docs/design/google-sheets/decisions.md

Scope

Implement capability-gated append-only refresh for eligible direct MergeTree/ReplicatedMergeTree sources using per-partition persistent _block_number and _block_offset checkpoints and finite bounded SELECT queries.

Acceptance criteria

  • Append UI requires configured minimum version (initially 26.8) and successful runtime capability probes.
  • Eligible query validation permits one deterministic direct source and rejects joins, views, FINAL, aggregation, DISTINCT, window functions, UNION, table functions, and business LIMIT.
  • Binding pins table UUID, query hash, schema hash, source-subset parameters, and initialization mode.
  • Initial modes support history export and future-only checkpoints.
  • Refresh captures finite per-partition upper boundaries.
  • Pages are ordered and filtered by _block_number / _block_offset and use decimal-string UInt64 values.
  • Each Google commit copies exact staged rows and advances only the corresponding partition checkpoint in the same publication batch.
  • A closed tab resumes from the last committed page without duplicates.
  • Invalid capability, UUID, query, schema, parameter, row-count, or checkpoint state requires explicit full refresh.
  • SELECT ... STREAM, updates, deletes, and silent fallback are absent.

Concurrency

Use advisory lease metadata and generation rechecks. Strict distributed locking is out of scope.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions