mirror of
https://github.com/lancedb/lancedb.git
synced 2026-10-12 14:52:26 +00:00
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:
@@ -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}
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user