mirror of
https://github.com/lancedb/lancedb.git
synced 2026-11-16 07:36:50 +00:00
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.
180 lines
6.4 KiB
Plaintext
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>
|