diff --git a/docs/tables/consistency.mdx b/docs/tables/consistency.mdx index bc84a424..715d265f 100644 --- a/docs/tables/consistency.mdx +++ b/docs/tables/consistency.mdx @@ -37,17 +37,22 @@ 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. + +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.