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.
This commit is contained in:
Jack Ye
2026-11-15 08:55:42 +08:00
committed by GitHub
parent e2f836da99
commit e8a8dd1b2a
22 changed files with 663 additions and 695 deletions
+25 -12
View File
@@ -135,20 +135,33 @@ from it.
## SHOW FUNCTIONS {#show}
<CodeGroup>
```sql SQL icon="database"
SHOW FUNCTIONS
SHOW FUNCTIONS HISTORY IN "analytics" WITH (name = 'embed', limit = 100)
SHOW FUNCTIONS HISTORY WITH (after_name = 'embed', after_version = '1', limit = 100)
```sql
SHOW FUNCTIONS IN analytics.`team$ml` LIMIT 100;
SHOW FUNCTIONS IN analytics.`team$ml` LIMIT 100 FROM '<page-token>';
```
</CodeGroup>
`SHOW FUNCTIONS` returns the highest published numeric revision for each name.
Add `HISTORY` to list every published revision, as Python's `list_functions()`
does. Rows are ordered by name and numeric revision, so `2` comes before `10`.
`after_name` and `after_version` must be supplied together for keyset pagination.
`limit` bounds
the response; `include_definition = false` omits the optional definition JSON.
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.
`SHOW FUNCTIONS` lists each function once. Add `HISTORY` to list every
published revision with its metadata and definition, as `list_functions()`
does. History uses the same pagination suffix; numeric revision order is
encoded in the token, so revision `2` precedes `10`.
```sql
SHOW FUNCTIONS HISTORY IN analytics.`team$ml` LIMIT 100;
SHOW FUNCTIONS HISTORY IN analytics.`team$ml` LIMIT 100 FROM '<page-token>';
```
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).
## DROP FUNCTION {#drop}