Files
lancedb/docs/web/sql/ddl/secret.mdx
T
Jack Ye e8a8dd1b2a feat(sql): use server-issued catalog listing tokens (#5026)
Migrates SQL-backed catalog listing APIs to `LIMIT ... FROM
'<page-token>'` and server-issued Arrow continuation metadata.
Namespace-specific APIs send an explicit `IN` schema clause, including
`IN "public"` for root, so raw SQL can default to all namespaces.

```sql
SHOW VIEWS LIMIT 100;
SHOW VIEWS IN team$ml LIMIT 100;
SHOW VIEWS IN team$ml LIMIT 100 FROM '<page-token>';
SHOW VIEWS IN other_db.team$ml LIMIT 100;
```

SDK clients forward opaque tokens unchanged, preserve empty
continuations, and decode identifier columns by name. Removes legacy
cursor reconstruction and updates the SQL reference and Python Flight
fixture. Public docs cover optional direct schema paths, all-namespace
defaults, and the shared pagination syntax across every catalog listing.
2026-11-15 08:55:42 +08:00

180 lines
6.4 KiB
Plaintext

---
title: "Secret"
tag: "Early access"
sidebarTitle: "Secret"
description: "CREATE, ALTER, DROP, SHOW and DESCRIBE SECRET, and granting privileges on Secrets."
icon: key
keywords: ["secret", "create secret", "alter secret", "drop secret", "show secrets", "describe secret", "grant", "sql"]
---
<Badge color="purple">Early access</Badge> <Badge color="red">Enterprise</Badge> [SQL runs in LanceDB Enterprise.](/sql)
A [Secret](/management/secret) is a named credential that Functions bind by
reference. These statements store, rotate, list, describe and drop Secrets.
A Secret is addressed like a table: `[db.][namespace.]name`. An unqualified
name uses the session's database and namespace. A nested namespace is one
backtick-quoted name with `$` between its components, and `public` is the
database's root namespace. A Secret name may contain letters, digits, `_`, `.`
and `-`, so quote one that contains `.` or `-`:
<CodeGroup>
```sql SQL icon="database"
api_key
platform.`model-api-key`
analytics.`ml$vision`.`model-api-key`
```
</CodeGroup>
`CREATE`, `ALTER` and `DROP` return one row of `operation`, `name` and
`status`. Without `IF [NOT] EXISTS`, a taken name (for `CREATE`) or a missing
Secret (for `ALTER` and `DROP`) is an error rather than a status.
## CREATE SECRET {#create}
<CodeGroup>
```sql SQL icon="database"
CREATE SECRET platform.`model-api-key` TYPE = GENERIC_STRING SECRET_STRING = '<api-key>'
CREATE SECRET IF NOT EXISTS api_key TYPE = GENERIC_STRING SECRET_STRING = $$<api-key>$$
```
</CodeGroup>
Stores a new Secret. `TYPE = GENERIC_STRING` is required; it is currently the
only supported type. The value may be single-quoted or dollar-quoted, or a
bound `$1` parameter -- the same choice `ALTER SECRET` offers below -- so the
value never has to appear in the SQL text itself:
<CodeGroup>
```python Python icon="python"
db.execute_query(
"CREATE SECRET platform.`model-api-key` TYPE = GENERIC_STRING SECRET_STRING = $1",
parameters=["<api-key>"],
)
```
</CodeGroup>
Requires `CREATE SECRET` on the namespace; the caller becomes the Secret's
owner.
The status is `created`, or `already_exists` with `IF NOT EXISTS`. It never
overwrites an existing Secret; use `ALTER SECRET`.
## ALTER SECRET {#alter}
<CodeGroup>
```sql SQL icon="database"
ALTER SECRET platform.`model-api-key` SET SECRET_STRING = '<api-key>'
ALTER SECRET IF EXISTS api_key SET SECRET_STRING = $$<api-key>$$
```
</CodeGroup>
Replaces the Secret's value -- `SECRET_STRING` takes the same single-quoted,
dollar-quoted, or bound `$1` parameter forms `CREATE SECRET` does. Every
Function bound to it gets the latest value the next time a job starts -- a
job already running, and its retries, keep the value they captured at their
own start -- without a new Function version. Requires `UPDATE` on the
Secret.
The status is `altered`, or `not_found` with `IF EXISTS`.
## DROP SECRET {#drop}
<CodeGroup>
```sql SQL icon="database"
DROP SECRET platform.`model-api-key`
DROP SECRET IF EXISTS api_key
```
</CodeGroup>
Deletes the Secret and every grant on it. Functions bound to it fail at their
next job, naming the Secret. Requires `OWNERSHIP` on the Secret.
The status is `dropped`, or `not_found` with `IF EXISTS`.
<Warning>
`DROP SECRET` cannot be undone. A new Secret created under the same name is
picked up by every Function still bound to that name.
</Warning>
## SHOW SECRETS {#show}
```sql
SHOW SECRETS IN analytics.`team$ml` LIMIT 100;
SHOW SECRETS IN analytics.`team$ml` LIMIT 100 FROM '<page-token>';
```
Returns two non-null string columns: `namespace_path`, a compact JSON array
of parent namespace components (`[]` for root), and `name`, the unqualified
object name. Omitting `IN` lists all authorized namespaces in the current database;
`IN team$ml` selects that exact path without a database qualifier; `IN public` selects
the current database's root. Listings require the relevant database and
namespace `USAGE` privileges.
Secret listings contain no values or Secret metadata.
Page through results using `LIMIT n [FROM '<page-token>']`. Read the opaque
`lancedb.next_page_token` from the Arrow result schema metadata and pass it back
unchanged with the same object type and scope. Stop when no token is returned;
a short or empty page can still carry a continuation. See
[catalog listing pagination](/sql/pagination).
## DESCRIBE SECRET {#describe}
<CodeGroup>
```sql SQL icon="database"
DESCRIBE SECRET platform.`model-api-key`
DESC SECRET api_key
```
</CodeGroup>
Returns one row:
| Column | Type | Meaning |
| --- | --- | --- |
| `name` | string | The Secret's name |
| `created_at_millis` | int64 | When it was created, in milliseconds since the Unix epoch |
| `updated_at_millis` | int64 | When its value was last set. Watch this change to confirm a rotation landed. |
| `history` | list of struct `{generation: uint64, at_millis: int64}` | Creation and each rotation since, oldest first, up to the most recent 100 |
A missing Secret is an error. Requires `USAGE` on the Secret.
## GRANT and REVOKE {#grant}
<CodeGroup>
```sql SQL icon="database"
GRANT CREATE SECRET ON SCHEMA platform TO ROLE platform_admins
GRANT USAGE, UPDATE ON SECRET platform.`model-api-key` TO ROLE etl, rotation_service
REVOKE UPDATE ON SECRET platform.`model-api-key` FROM ROLE etl
```
</CodeGroup>
`CREATE SECRET` on the containing `SCHEMA` creates one; `OWNERSHIP`, `USAGE`
(bind it to a Function) and `UPDATE` (rotate it) apply to the Secret itself.
See [GRANT and REVOKE](/sql/ddl/grant) for the full statement grammar, every
target type, and the shared mechanics -- grantee forms, no-op rules, and the
status a statement returns -- which apply the same way to a Secret as to
any other object.
## The value stays out of output {#redaction}
A Secret's value never appears in a statement's result, an error message,
`EXPLAIN` output, or the query log. The query log masks everything after the
name in `CREATE SECRET`, and everything after `SET` in `ALTER SECRET`.
<Note>
SQL has no syntax for binding a Secret to a Function. Register Functions that
bind Secrets through the Python SDK; see
[Vend a Secret to a Function](/curation/vend-secret).
</Note>
## What to read next {#next}
<CardGroup cols={2}>
<Card title="Secret" icon="key" href="/management/secret">
Create, rotate, list and drop the credential from the Python SDK and SQL.
</Card>
<Card title="Privileges" icon="key" href="/governance/privileges#sql">
Every object's privileges, and how grants resolve.
</Card>
</CardGroup>