mirror of
https://github.com/lancedb/lancedb.git
synced 2026-10-30 15:26:52 +00:00
Jack Ye
ddb318567a
## Summary - Complete the SQL reference: `ATTACH DATABASE`, the `CHANGES` clause, and `dedupe()`/`duplicate_pairs()` (verified against current sophon source; these were recently renamed from `vector_dedup`/`vector_duplicate_pairs`). Fix the blob-column default-projection claim and add the previously undocumented `blob_descriptor()`. - Enrich the gated Functions draft (still `.mintignore`'d, pre-release): chained Functions over blob outputs, GPU-produced blobs, Secrets, multi-input/output binding, `code=[module]` packaging. - Upgrade the materialized-view and computed-column auto-refresh drafts with precise, verified catch-up semantics, and add the missing `ALTER MATERIALIZED VIEW` / `CREATE ... WITH(...)` sections (also gated — the automatic-refresh scheduler is still dev/staging-only). - Thread one running example (video frames → GPU extract/caption → dedup → auto-refreshing materialized view) through Functions, materialized views, and the LeRobotDataset integration guide instead of a separate tutorial. - Rename "LanceDB OSS"/"OSS" to "LanceDB Embedded"/"Embedded" throughout (52 files); activate the existing availability-comparison mechanism on `basics/offerings.mdx` for a full feature-by-feature comparison table.
148 lines
5.4 KiB
Plaintext
148 lines
5.4 KiB
Plaintext
---
|
|
title: "Authorization"
|
|
sidebarTitle: "Authorization"
|
|
description: "Who may do what: privileges granted on catalog objects to principals, groups, roles, and API keys."
|
|
icon: shield-halved
|
|
keywords: ["authorization", "authz", "privileges", "rbac", "access control"]
|
|
availability:
|
|
embedded: unavailable
|
|
enterprise: available
|
|
---
|
|
|
|
[Authentication](/enterprise/authentication) establishes who is calling.
|
|
Authorization decides what they may do.
|
|
|
|
An access control entry grants **one privilege** on **one object** to **one
|
|
subject**. Everything below is a consequence of that shape.
|
|
|
|
## Subjects {#subjects}
|
|
|
|
A grant is held by one of four kinds of subject, distinguished by a prefix:
|
|
|
|
| Prefix | Subject |
|
|
| --- | --- |
|
|
| `p:` | a principal, by ID (`P:` by name) |
|
|
| `g:` | a group, by ID (`G:` by name) |
|
|
| `r:` | a role |
|
|
| `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.
|
|
|
|
`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}
|
|
|
|
Objects are addressed by kind and path:
|
|
|
|
```
|
|
system
|
|
database:db
|
|
namespace:db:ns
|
|
table:db:ns$table
|
|
view:db:ns$view
|
|
```
|
|
|
|
{/*
|
|
Draft for the Functions release. Replaces the object kinds above:
|
|
|
|
```
|
|
system
|
|
database:db
|
|
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.
|
|
|
|
## Privileges {#privileges}
|
|
|
|
| Privilege | Granted on | Allows |
|
|
| --- | --- | --- |
|
|
| `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, view | reading rows |
|
|
| `INSERT` | table | appending rows |
|
|
| `UPDATE` | table | modifying existing rows |
|
|
| `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 | describing and controlling jobs, managing caches, and reading server configuration |
|
|
|
|
{/*
|
|
Draft for the Functions release. Add these rows to the table above.
|
|
After the `USAGE` row for namespace:
|
|
| `USAGE` | function | binding it to a column, and refreshing a column it computes |
|
|
| `USAGE` | secret | binding and resolving it |
|
|
After the `UPDATE` row for table:
|
|
| `UPDATE` | secret | rotating it, without the right to bind or read it |
|
|
After the `CREATE_VIEW` row:
|
|
| `CREATE_FUNCTION` | namespace | registering a function in it |
|
|
| `CREATE_SECRET` | namespace | creating a secret in it |
|
|
*/}
|
|
|
|
The four data privileges map onto the four
|
|
[ingestion operations](/ingestion), so a principal that may append but not
|
|
modify is expressed by granting `INSERT` without `UPDATE`.
|
|
|
|
<Note>
|
|
`CREATE_MATERIALIZED_VIEW` and `CREATE_VIEW` are separate privileges because
|
|
[the two objects differ](/basics/catalog): one stores rows and is refreshed,
|
|
the other stores only a query. Granting the ability to create one does not
|
|
grant the other.
|
|
</Note>
|
|
|
|
## Creation privileges resolve upward {#upward}
|
|
|
|
A subtlety worth knowing, because it explains grants that appear to work on
|
|
objects that do not exist yet.
|
|
|
|
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 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
|
|
subject = G:data-science
|
|
```
|
|
|
|
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
|
|
grant.
|