From 6b67c9135aa57ae2136e21ed26c66e80018693f7 Mon Sep 17 00:00:00 2001 From: Brendan Clement Date: Fri, 9 Oct 2026 09:12:04 -0700 Subject: [PATCH] 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. --- docs/web/basics/guarantees.mdx | 6 ++++-- docs/web/tables/consistency.mdx | 15 +++++++++------ 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/web/basics/guarantees.mdx b/docs/web/basics/guarantees.mdx index b71ad68d4..669e42aef 100644 --- a/docs/web/basics/guarantees.mdx +++ b/docs/web/basics/guarantees.mdx @@ -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} diff --git a/docs/web/tables/consistency.mdx b/docs/web/tables/consistency.mdx index 66adfe854..43ba7e504 100644 --- a/docs/web/tables/consistency.mdx +++ b/docs/web/tables/consistency.mdx @@ -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.