docs: stop promising read-your-writes on a deployment

The consistency page said reads after any write carry a freshness floor,
so you read your own writes without extra configuration, and that the
floor follows the last write. The pinned client records a write's
version as x-lancedb-min-version, which Sophon does not read (neither at
75f4bf28 nor on main); its time floor comes from the interval and from
checkout_latest() and restore(); and its version watermark follows the
x-lancedb-version a response reports. Whether that watermark covers a
write depends on the version the write's response reports, which the
code alone does not settle.

The page now describes those three mechanisms and says how to be sure a
read reflects your write: an interval of zero, or checkout_latest()
after writing. The guarantees page keeps its read-your-writes promise
for the embedded library, on the handle that wrote.
This commit is contained in:
Brendan Clement
2026-10-09 09:12:04 -07:00
parent 058dca70b0
commit 6b67c9135a
2 changed files with 13 additions and 8 deletions
+4 -2
View File
@@ -58,8 +58,10 @@ Set `read_consistency_interval` when several processes write the same table and
readers must observe those writes. The cost is a metadata check on that
interval. See [Consistency](/tables/consistency).
**Your own writes are always visible to you.** The interval governs other
writers, not yourself.
**In the embedded library, your own writes are always visible to you** on the
table handle that made them. The interval governs other writers, not yourself.
On a deployment, see [Consistency](/tables/consistency) for how to make sure a
read reflects your own write.
## Durability and history {#durability}
+9 -6
View File
@@ -51,16 +51,19 @@ respected by the client. The interval is sent to the server as a freshness bound
- **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 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. Each opened table handle keeps its own floor.
In addition, `checkout_latest` and `restore` set a time floor on that table handle: later
reads ask for data at least as fresh as that moment, or as the configured interval allows,
whichever is later. Each opened table handle keeps its own floor.
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
Each remote table handle also tracks the highest dataset version a response from the server has
reported and sends it back with every subsequent request, 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.
A write also records its new version on the handle, but deployments do not use that record to
choose what a read sees, so the client alone does not guarantee that the next read reflects your
own write. To be sure it does, set the interval to zero, or call `checkout_latest` after writing.
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.