Skip to content

Commit 07ca7c9

Browse files
docs: clarify read consistency behavior for db:// remote tables (#276)
* docs: clarify read consistency behavior for db:// remote tables * docs: note monotonic-read guarantee for remote table handles --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
1 parent 8154d43 commit 07ca7c9

1 file changed

Lines changed: 10 additions & 5 deletions

File tree

docs/tables/consistency.mdx

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -37,17 +37,22 @@ write operations are always consistent.
3737
<Callout color="blue">
3838
**Consistency in Remote Tables**
3939

40-
For remote tables, `read_consistency_interval` is also
40+
For remote tables (`db://` connections), `read_consistency_interval` is also
4141
respected by the client. The interval is sent to the server as a freshness bound on each read:
4242

4343
- **Unset (default)**: no freshness header is sent; reads use the server's cached view of the table.
4444
- **Zero seconds**: every read asks the server for the latest committed version.
4545
- **Non-zero interval**: reads accept data at least as fresh as `now - interval`.
4646

47-
In addition, after any write through the client (`add`, `update`, `delete`, `merge_insert`, `add_columns`,
48-
`alter_columns`, `drop_columns`), the next read on the same table automatically pins the minimum
49-
version so you read your own writes without extra configuration. `checkout`, `checkout_tag`,
50-
`checkout_latest`, and `restore` reset this state appropriately.
47+
In addition, after any write or after a `checkout_latest` / `restore` on a table handle, subsequent
48+
reads on that same handle carry a freshness floor so you read your own writes without extra
49+
configuration. The floor is the later of the configured interval and the moment of the last
50+
write or refresh, and it is shared across handles to the same table on the same connection.
51+
52+
Each remote table handle also tracks the highest dataset version it has observed in a read
53+
response and sends it back with every subsequent read, so successive reads on the same handle
54+
never observe an older version even when a load balancer routes them to query nodes with
55+
differently-cached views. `checkout_latest` resets this watermark.
5156

5257
Stronger consistency is not free — the smaller the interval, the more often each read pays the cost
5358
of refreshing against storage, which raises per-read latency and cost.

0 commit comments

Comments
 (0)