From 0a1c8fcddd2bcb02b8a084dbeff638f6572789de Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 17 Jun 2026 17:33:45 +0000 Subject: [PATCH 1/2] docs: clarify read consistency behavior for db:// remote tables --- docs/tables/consistency.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/tables/consistency.mdx b/docs/tables/consistency.mdx index bc84a424..0be9cb9e 100644 --- a/docs/tables/consistency.mdx +++ b/docs/tables/consistency.mdx @@ -37,17 +37,17 @@ write operations are always consistent. **Consistency in Remote Tables** -For remote tables, `read_consistency_interval` is also +For remote tables (`db://` connections), `read_consistency_interval` is also respected by the client. The interval is sent to the server as a freshness bound on each read: - **Unset (default)**: no freshness header is sent; reads use the server's cached view of the table. - **Zero seconds**: every read asks the server for the latest committed version. - **Non-zero interval**: reads accept data at least as fresh as `now - interval`. -In addition, after any write through the client (`add`, `update`, `delete`, `merge_insert`, `add_columns`, -`alter_columns`, `drop_columns`), the next read on the same table automatically pins the minimum -version so you read your own writes without extra configuration. `checkout`, `checkout_tag`, -`checkout_latest`, and `restore` reset this state appropriately. +In addition, after any write or after a `checkout_latest` / `restore` on a table handle, subsequent +reads on that same handle carry a freshness floor so you read your own writes without extra +configuration. The floor is the later of the configured interval and the moment of the last +write or refresh, and it is shared across handles to the same table on the same connection. Stronger consistency is not free — the smaller the interval, the more often each read pays the cost of refreshing against storage, which raises per-read latency and cost. From 6c597bb232946d9fa5f98e64ed63d0bca4a89318 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 30 Jun 2026 18:23:48 +0000 Subject: [PATCH 2/2] docs: note monotonic-read guarantee for remote table handles --- docs/tables/consistency.mdx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/tables/consistency.mdx b/docs/tables/consistency.mdx index 0be9cb9e..715d265f 100644 --- a/docs/tables/consistency.mdx +++ b/docs/tables/consistency.mdx @@ -49,6 +49,11 @@ reads on that same handle carry a freshness floor so you read your own writes wi configuration. The floor is the later of the configured interval and the moment of the last write or refresh, and it is shared across handles to the same table on the same connection. +Each remote table handle also tracks the highest dataset version it has observed in a read +response and sends it back with every subsequent read, so successive reads on the same handle +never observe an older version even when a load balancer routes them to query nodes with +differently-cached views. `checkout_latest` resets this watermark. + Stronger consistency is not free — the smaller the interval, the more often each read pays the cost of refreshing against storage, which raises per-read latency and cost.