> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grant

> GRANT and REVOKE: privileges on every catalog object, from a database down to a Function.

**Applies to:** Embedded ❌, Enterprise ✅

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
GRANT <privilege>[, <privilege>...] ON <target> TO <grantee>[, <grantee>...]
REVOKE <privilege>[, <privilege>...] ON <target> FROM <grantee>[, <grantee>...]

<target> ::= SYSTEM | DATABASE <name> | SCHEMA <namespace> | NAMESPACE <name> [IN <schema>] | TABLE <name> | VIEW <name>
          | MATERIALIZED VIEW <name> | SECRET <name> | STORAGE INTEGRATION <name> | FUNCTION <name>
<grantee> ::= [ROLE] <role> | [USER] { <name> | ID '<id>' } | [GROUP] { <name> | ID '<id>' }
```

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
GRANT OPERATE, USAGE ON SYSTEM TO ROLE ops
GRANT USAGE, CREATE SCHEMA ON DATABASE analytics TO ROLE readers
GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE events TO ROLE etl
GRANT CREATE SECRET, CREATE FUNCTION ON SCHEMA platform TO ROLE platform_admins
GRANT USAGE, UPDATE ON SECRET platform.`openai-prod` TO ROLE etl, rotation_service
GRANT USAGE ON SECRET platform.`openai-prod` TO USER alice, GROUP ID 'g1'
GRANT USAGE ON FUNCTION platform.embed TO ROLE research
GRANT OWNERSHIP ON SECRET platform.`openai-prod` TO ROLE platform_admins
REVOKE USAGE ON FUNCTION platform.embed FROM ROLE research
```

## Privileges

| Target | Privileges it accepts |
| - | - |
| `SYSTEM` | `OPERATE`, `CREATE DATABASE`, `USAGE` -- no `OWNERSHIP`; the system itself has no owner |
| `DATABASE` | `OWNERSHIP`, `USAGE`, `CREATE SCHEMA` (or `CREATE NAMESPACE`) |
| `SCHEMA` (a namespace) | `OWNERSHIP`, `USAGE`, `CREATE NAMESPACE`, `CREATE TABLE`, `CREATE MATERIALIZED VIEW`, `CREATE VIEW`, `CREATE SECRET`, `CREATE STORAGE INTEGRATION`, `CREATE FUNCTION` |
| `TABLE`, `MATERIALIZED VIEW` | `OWNERSHIP`, `SELECT`, `INSERT`, `UPDATE`, `DELETE` |
| `VIEW` | `OWNERSHIP`, `SELECT` |
| `SECRET` | `OWNERSHIP`, `USAGE` (bind it to a Function), `UPDATE` (rotate it) |
| `STORAGE INTEGRATION` | `OWNERSHIP`, `USAGE` |
| `FUNCTION` | `OWNERSHIP`, `USAGE` (call it in a query, bind it to a column, or refresh a column it computes) |

> [!WARNING]
>
> `OWNERSHIP` cannot be revoked, only granted to someone else, which transfers
> it: an object always has exactly one owner. `GRANT OWNERSHIP` is refused with
> more than one grantee for the same reason.

See [Privileges](https://docs.lancedb.com/governance/privileges.md) for what each privilege allows in
full, and how a creation privilege resolves against an object's parent when
the object doesn't exist yet.

## Grantees

A grantee is a role, or a user or group named by its identity-directory name
or its directory ID. A grantee with no leading `ROLE`/`USER`/`GROUP` keyword
takes the kind of the one before it, so `TO ROLE a, b` names two roles --
but the first grantee in the list always needs its keyword. An unquoted name
is folded to lowercase before it is looked up; quote one that has capitals,
such as `TO ROLE "DataEng"`.

## Naming the target

A `SECRET` or `FUNCTION` target can be qualified with its namespace and
database, the same as anywhere else: `SECRET analytics.api_key`,
`SECRET db1.analytics.api_key`. `SCHEMA` and `NAMESPACE` both target a
namespace but aren't interchangeable: `SCHEMA <namespace>` takes the
namespace's complete path, while `NAMESPACE <name> [IN <schema>]` takes
one unqualified component, resolved under an explicit parent schema or the
session's current namespace when `IN` is omitted -- `NAMESPACE a.b` (a
qualified name with no `IN`) is refused. A `MATERIALIZED VIEW` is a table
for authorization purposes: the same privileges apply, and granting one
does not reach the non-materialized `VIEW` beside it.

## How a statement is applied

* A statement applies all of its changes or none of them.
* The caller must already hold `OWNERSHIP` on the object to change any grant
  on it.
* Granting a privilege a grantee already holds, or revoking one it does not
  hold, is a no-op.
* `GRANT` requires the object to exist; `REVOKE` does not, so an entry left
  on a dropped object can still be removed. A role need not exist
  beforehand, but a `USER` or `GROUP` name must resolve to exactly one
  identity in your identity provider -- checked only after the caller's
  `OWNERSHIP` -- or the statement fails. The `ID '<id>'` form is not looked
  up.
* `GRANT ... ON ... FROM ...` and `REVOKE ... ON ... TO ...` are both
  refused; `GRANT` always takes `TO`, `REVOKE` always takes `FROM`.
* Returns one row per privilege and grantee, with status `granted`,
  `already_granted`, `revoked` or `not_granted`.

> [!NOTE]
>
> SQL has no syntax for binding a Secret to a Function; that's a
> registration-time argument to `create_function` in the Python SDK. See
> [Vend a Secret to a Function](https://docs.lancedb.com/curation/vend-secret.md).

## SHOW GRANTS

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
SHOW GRANTS [ON <target>] [TO <grantee>[, <grantee>...]] [LIMIT n]
```

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
SHOW GRANTS
SHOW GRANTS ON TABLE events TO ROLE readers LIMIT 2
SHOW GRANTS ON NAMESPACE features IN analytics.team
SHOW GRANTS TO USER ID 'p1'
```

Lists grants as rows of `subject_id`, `subject_name`, `object` and
`privilege`. `ON` filters to one target's own grants; `TO` filters to one
or more grantees; combine both, or omit both for every grant the caller
can see. `ON <target>` requires `USAGE` on that target; a target-less call
requires system `USAGE` instead, since it can surface grants across the
whole catalog. `SHOW ROLE BINDINGS` is the counterpart for role
membership rather than object privileges -- see
[Role membership in SQL](https://docs.lancedb.com/governance/principals.md#membership).

## What to read next

> [card] [Privileges](https://docs.lancedb.com/governance/privileges.md)
>
> The full privilege model, and how creation privileges resolve upward.

> [card] [Namespace](https://docs.lancedb.com/sql/ddl/namespace.md)
>
> Creating the schemas these privileges apply to.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.