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