rust/lancedb
1
0
Fork 0
mirror of https://github.com/lancedb/lancedb.git synced 2026-10-12 23:02:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: correct the labelled pages against the pinned deployment

Browse Source 
Authorization wrote objects as namespace:db/ns and table:db/ns/table,
which the deployment rejects; it writes namespace:db:ns and
table:db:ns$table, nesting namespaces with $. The page now lists the
view, function and secret objects, CREATE_FUNCTION and CREATE_SECRET,
USAGE and UPDATE where they apply beyond tables, and what OPERATE and
USAGE on system allow. An a: subject names the principal holding a key
rather than a narrower grantee, creation falls back to the parent's
create privilege only for an unowned database or namespace, and a
listing page holds at most 100 entries.

The materialized view page said a deployment's refresh, options and
stable row id needs depend on version and configuration. Newer versions
rebuild the whole view on every create and refresh as a job, need no
stable row ids, take no refresh options, and have no REST route to create
one; earlier ones differed, and their views have to be recreated. The
page and the REFRESH reference now say so, without naming which version
a deployment runs.

Vector search no longer says it has no SQL form: some deployment
versions plan ORDER BY distance(...) LIMIT k as one.
This commit is contained in:
Brendan Clement
2026-10-08 21:31:15 -07:00
parent f228295c34
commit 05c7ba4889
4 changed files with 65 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/web/feature-engineering/materialized-views.mdx
+16 -12
View File
@@ -61,8 +61,8 @@ at creation time. `where` filters source rows; `limit` caps the view.
A local refresh does not track which source rows the view came from, so a local
view's source does not need stable row ids (`new_table_enable_stable_row_ids`):
the example above creates its source with the defaults. Earlier development
builds and the published 0.39.0 required them, and a deployment may still
require them; see [Against a deployment](#availability).
builds and the published 0.39.0 required them, and an earlier deployment
version may still require them; see [Against a deployment](#availability).
The source is still checked, when the view is created and on every refresh: one
with an LSM write spec, or with retained write-ahead-log rows not yet compacted,
@@ -91,19 +91,23 @@ in your process. `with_no_data` and `source_version` are for local views only;
the SDK refuses them on a `db://` connection.
Materialized views are off by default on a deployment and have to be enabled
there. How a deployment refreshes a view -- rebuilding the whole view, as above,
or reconciling what changed in the source -- depends on its LanceDB Enterprise
version and configuration, and so do the options
[`REFRESH MATERIALIZED VIEW`](/sql/dml/refresh#refresh-materialized-view)
accepts and whether the source table needs stable row ids.
there. How a deployment handles a view then depends on its LanceDB Enterprise
version. Newer versions run every create and refresh as a job that rebuilds the
whole view, as a local refresh does; the source does not need stable row ids,
and [`REFRESH MATERIALIZED VIEW`](/sql/dml/refresh#refresh-materialized-view)
accepts no options. Earlier versions could instead reconcile only what changed
in the source, and could require the source to have stable row ids. A view
created by an earlier version has to be recreated once the deployment moves to
a newer one.
Stable row ids are set up on the deployment, not by the SDK: a `db://`
connection does not send `new_table_enable_stable_row_ids`, and no SDK call adds
them to an existing table. Depending on its version and configuration, a
deployment may give new tables stable row ids, may refuse a view created through
SQL -- as the SDK creates one -- over a source without them, or may convert an
existing source when a view is created through its REST API. Check with the
deployment's administrator what it requires before relying on a source.
them to an existing table. An earlier version that requires them may give new
tables stable row ids, may refuse a view created through SQL -- as the SDK
creates one -- over a source without them, or may convert an existing source
when a view is created through its REST API, which newer versions no longer
have. Check with the deployment's administrator which version it runs before
relying on a source.
`SHOW MATERIALIZED VIEWS` lists them, which is cheaper than
`list_materialized_views` -- that method finds views by reading every table's
docs/web/governance/authorization.mdx
+38 -22
View File
@@ -8,9 +8,10 @@ availability:
oss: unavailable
enterprise: varies
summary: >-
A deployment checks privileges on its databases, namespaces and tables only
when its administrator has configured it to. Embedded LanceDB has no such
layer: access is whatever the object store allows.
A deployment checks privileges on its databases, namespaces, tables and
other catalog objects only when its administrator has configured it to.
Embedded LanceDB has no such layer: access is whatever the object store
allows.
---
[Authentication](/enterprise/authentication) establishes who is calling.
@@ -28,15 +29,16 @@ A grant is held by one of four kinds of subject, distinguished by a prefix:
| `p:` | a principal, by ID -- `P:` by name |
| `g:` | a group, by ID -- `G:` by name |
| `r:` | a role |
| `a:` | an API key |
| `a:` | the principal holding an API key, named by the key |
Granting to a group or role rather than a principal is what keeps the entry
count manageable: a principal's effective privileges are the union of what it
holds directly and what it inherits.
Granting to an API key is narrower than granting to the principal that owns
it -- useful when a key is issued for one job and should not carry that
principal's full authority.
`P:`, `G:` and `a:` are ways of naming a subject when you make a request. The
entry is stored against the ID they resolve to, so a grant to `a:` belongs to
the principal holding that key and carries that principal's full authority,
not a narrower one.
## Objects {#objects}
@@ -45,10 +47,16 @@ Objects are addressed by kind and path:
```
system
database:db
namespace:db/ns
table:db/ns/table
namespace:db:ns
table:db:ns$table
view:db:ns$view
function:db:ns$function
secret:db:ns$secret
```
A nested namespace joins its path with `$`, as in `namespace:db:parent$child`
or `table:db:parent$child$table`.
The hierarchy is not decorative. Reaching a table requires `USAGE` on the
namespace containing it and on the database containing that -- a grant on the
table alone is not enough to traverse to it.
@@ -57,19 +65,25 @@ table alone is not enough to traverse to it.
| Privilege | Granted on | Allows |
| --- | --- | --- |
| `OWNERSHIP` | any object | ownership, conveying full authority |
| `OWNERSHIP` | any object but `system` | ownership, conveying full authority |
| `USAGE` | system | listing jobs and their events, and looking up other identities |
| `USAGE` | database | accessing the namespaces inside |
| `USAGE` | namespace | accessing the tables inside |
| `SELECT` | table | reading rows |
| `USAGE` | function | binding it to a column, and refreshing a column it computes |
| `USAGE` | secret | binding and resolving it |
| `SELECT` | table, view | reading rows |
| `INSERT` | table | appending rows |
| `UPDATE` | table | modifying existing rows |
| `UPDATE` | secret | rotating it, without the right to bind or read it |
| `DELETE` | table | deleting rows |
| `CREATE_DATABASE` | system | creating a database |
| `CREATE_NAMESPACE` | database, namespace | creating immediate child namespaces |
| `CREATE_TABLE` | namespace | creating a table in it |
| `CREATE_MATERIALIZED_VIEW` | namespace | creating a materialized view in it |
| `CREATE_VIEW` | namespace | creating a non-materialized view in it |
| `OPERATE` | system | reading server configuration |
| `CREATE_FUNCTION` | namespace | registering a function in it |
| `CREATE_SECRET` | namespace | creating a secret in it |
| `OPERATE` | system | describing and controlling jobs, managing caches, and reading server configuration |
The four data privileges map onto the four
[ingestion operations](/ingestion), so a principal that may append but not
@@ -87,26 +101,28 @@ grant the other.
A subtlety worth knowing, because it explains grants that appear to work on
objects that do not exist yet.
When `USAGE` is checked on a database and **no entries exist for it at all**,
the database is assumed not to exist yet, and `CREATE_DATABASE` on `system` is
checked instead. The same applies to the default namespace: absent any
entries, the check falls back to `CREATE_NAMESPACE` on the containing
database.
When you create an object, the deployment checks the database and each
namespace that will contain it. One that **has no owner** -- because it does
not exist yet, or predates per-object authorization -- is treated as one you are
creating: the check falls back to `CREATE_DATABASE` on `system` for the
database, or to `CREATE_NAMESPACE` on its parent for a namespace, and you become
its owner. One that has an owner needs `USAGE` as usual.
So a principal holding `CREATE_DATABASE` can act on a database that has not
been created -- which is what makes creation possible at all, and why an empty
ACL set is not the same as a deny.
So a principal holding `CREATE_DATABASE` can create a table in a database that
has not been created -- which is what makes creation possible at all, and why
an empty ACL set is not the same as a deny. The fallback applies only when
creating; other operations on a database or namespace need `USAGE` on it.
## Listing grants {#listing}
Entries can be listed filtered by object, by subject, or both:
```
object = table:db/ns/documents
object = table:db:ns$documents
subject = G:data-science
```
Results paginate through a continuation token. One stored `(object, subject)`
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.
docs/web/search/vector-search.mdx
+4 -1
View File
@@ -57,7 +57,10 @@ Vector search is a technique used to search for similar items based on their vec
Raw data (e.g. text, images, audio, etc.) is converted into embeddings via an embedding model, which are then stored in a multimodal lakehouse like LanceDB. To perform similarity search at scale, an index is created on the stored embeddings, which can then used to perform fast lookups.
<Note>
Vector search has **no SQL form**. Run it here and use [SQL](/sql) over the result.
In [SQL](/sql), vector search depends on the deployment: some versions plan
`ORDER BY distance(vector, query_vector) LIMIT k` as one -- see
[SQL](/basics/sql#no-vector-sql). The query builder on this page works with
every embedded and deployed database.
</Note>
## Supported distance metrics
docs/web/sql/dml/refresh.mdx
+7 -6
View File
@@ -69,15 +69,16 @@ REFRESH MATERIALIZED VIEW chunks
REFRESH MATERIALIZED VIEW chunks WITH (full = true)
```
`full = true` asks for every row to be recomputed. Without it, whether a
refresh rebuilds the whole view -- as every local SDK refresh does -- or
reconciles only what changed in the source depends on the deployment's LanceDB
Enterprise version and configuration.
On earlier deployment versions, `full = true` asks for every row to be
recomputed, and without it a refresh can reconcile only what changed in the
source. Newer versions rebuild the whole view on every refresh, as every local
SDK refresh does, and refuse `WITH` options.
<Warning>
`CASCADE` asks for the views this one is built on to be refreshed first, in
dependency order. Whether a deployment carries it out depends on its version;
where it does not, refresh each view yourself, its sources first.
dependency order. Whether a deployment carries it out depends on its version,
and newer versions refuse it; where it is refused, refresh each view yourself,
its sources first.
</Warning>
## Watching a refresh {#watching}