From 05c7ba4889d6d626f804145e1ca6df8a16507533 Mon Sep 17 00:00:00 2001 From: Brendan Clement Date: Thu, 8 Oct 2026 21:31:15 -0700 Subject: [PATCH] docs: correct the labelled pages against the pinned deployment 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. --- .../materialized-views.mdx | 28 +++++---- docs/web/governance/authorization.mdx | 60 ++++++++++++------- docs/web/search/vector-search.mdx | 5 +- docs/web/sql/dml/refresh.mdx | 13 ++-- 4 files changed, 65 insertions(+), 41 deletions(-) diff --git a/docs/web/feature-engineering/materialized-views.mdx b/docs/web/feature-engineering/materialized-views.mdx index f8750e2d9..cc807f0db 100644 --- a/docs/web/feature-engineering/materialized-views.mdx +++ b/docs/web/feature-engineering/materialized-views.mdx @@ -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 diff --git a/docs/web/governance/authorization.mdx b/docs/web/governance/authorization.mdx index b47f32351..6ad7e23a9 100644 --- a/docs/web/governance/authorization.mdx +++ b/docs/web/governance/authorization.mdx @@ -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. diff --git a/docs/web/search/vector-search.mdx b/docs/web/search/vector-search.mdx index f6c793e78..b635be19d 100644 --- a/docs/web/search/vector-search.mdx +++ b/docs/web/search/vector-search.mdx @@ -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. -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. ## Supported distance metrics diff --git a/docs/web/sql/dml/refresh.mdx b/docs/web/sql/dml/refresh.mdx index 2d00c1104..4882c86ed 100644 --- a/docs/web/sql/dml/refresh.mdx +++ b/docs/web/sql/dml/refresh.mdx @@ -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. `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. ## Watching a refresh {#watching}