docs: correct grant pagination and the two read-freshness watermarks

A grant listing was said to hold at most 100 entries a page. The server
counts 100 stored (object, subject) tuples a page and then expands each
into its privileges, so a page can return more; the page now says so
and to keep requesting with the token.

The consistency page said a write's version is never used to choose
what a read sees. The client sends two version headers: the write
result in x-lancedb-min-version, which deployments ignore, and the
highest version any response reported in x-lancedb-min-read-version,
which they check. A successful write's response advances the second.
The page now separates them and keeps the advice to read with a zero
interval or after checkout_latest when a read must reflect a write.
This commit is contained in:
Brendan Clement
2026-10-09 13:33:32 -07:00
parent 53c2f0b782
commit b4bafa38f6
2 changed files with 13 additions and 8 deletions
+5 -3
View File
@@ -134,9 +134,11 @@ object = table:db:ns$documents
subject = G:data-science
```
Results paginate through a continuation token, at most 100 entries to a page. One stored `(object, subject)`
tuple carrying several privileges expands into several entries in the
response, so the count reflects privileges rather than tuples.
Results paginate through a continuation token. A page holds at most 100 stored
`(object, subject)` tuples, and a tuple carrying several privileges expands
into several entries in the response, so a page can return more than 100
entries: the count reflects privileges rather than tuples. Keep requesting with
the returned token until a page comes back without one.
Listing by subject answers "what can this team reach"; listing by object
answers "who can reach this table". Both are worth running before changing a
+8 -5
View File
@@ -56,13 +56,16 @@ reads ask for data at least as fresh as that moment, or as the configured interv
whichever is later. Each opened table handle keeps its own floor.
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
reported and sends it back with every subsequent request, as `x-lancedb-min-read-version`. A
deployment checks it against the version it has cached, so successive reads on the same handle do
not 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.
A successful write's response reports the version it committed, so it advances the same watermark:
the next read on that handle asks for at least that version. The client also sends the version a
write returned in a separate header, `x-lancedb-min-version`, which deployments do not use. How a
deployment honors the read watermark depends on its version and configuration, so when a read must
reflect your own write, 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.