mirror of
https://github.com/lancedb/lancedb.git
synced 2026-11-18 16:43:59 +00:00
feat: use SQL for remote function lifecycle
Remote function registration, exact-version lookup, listing, and drop now execute SQL through the Flight client. Registration waits for the durable image build and catalog publication before yielding its typed `FunctionVersion`. SQL also covers source-inclusive description and pinned metadata updates. Registration and drop handles use `job_type="query"`; the single `job.id` is the SQL query UUID and can be inspected with `describe_query()` on the submitting connection. Waiting drains the SQL result once and caches completion for repeated waits. The drop boolean reports catalog removal; physical cleanup continues separately. Query handles have no registry history and cannot be reopened with `open_job()`.
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: "Function"
|
||||
sidebarTitle: "Function"
|
||||
description: "CREATE FUNCTION, SHOW FUNCTIONS, and DROP FUNCTION."
|
||||
description: "Create, describe, alter, list, and drop registered functions with SQL."
|
||||
icon: function
|
||||
keywords: ["create function", "drop function", "show functions", "sql", "udf"]
|
||||
---
|
||||
@@ -60,6 +60,35 @@ version is unaffected.
|
||||
the function is baked into an image before the version becomes usable.
|
||||
</Note>
|
||||
|
||||
## Artifact registration {#artifact}
|
||||
|
||||
`CREATE FUNCTION name FROM '<registration JSON>'` accepts the artifact,
|
||||
signature, runtime, optional secret bindings, and result stability produced by
|
||||
the SDK's registration request. Omit its `name` property because the SQL
|
||||
identifier supplies it. Escape apostrophes in the JSON as doubled apostrophes.
|
||||
|
||||
By default, the command waits for its internal image-build job to publish the
|
||||
version, then returns one UTF-8 `definition` column containing FunctionVersion
|
||||
JSON. `WITH (wait = false)` instead returns the existing image-build registry
|
||||
job ID in `job_id`, with `operation` and `status` columns. The SDK's ordinary
|
||||
registration handle has type `query` and uses the SQL query UUID as its single
|
||||
`id`; the internal image-build job has type `create_function`.
|
||||
|
||||
## DESCRIBE and ALTER FUNCTION {#describe-alter}
|
||||
|
||||
```sql
|
||||
DESCRIBE FUNCTION embed WITH (version = '1', include_source = true)
|
||||
```
|
||||
|
||||
DESCRIBE returns one `definition` JSON column for the exact version.
|
||||
`include_source` defaults to false; source-inclusive reads report an omission
|
||||
when the stored artifact exceeds the inline source limit.
|
||||
|
||||
`ALTER FUNCTION name FROM '<pinned update JSON>'` accepts a `reference` with
|
||||
name, namespace, object ID, location, version, and manifest digest, plus optional
|
||||
`metadata` and `disabled` updates. The command checks that reference before
|
||||
appending a revision and returns the resulting `definition` JSON.
|
||||
|
||||
## Call it {#call}
|
||||
|
||||
Once registered, a function is callable by name in any query, the same as a
|
||||
@@ -78,29 +107,27 @@ from it.
|
||||
|
||||
```sql
|
||||
SHOW FUNCTIONS
|
||||
SHOW FUNCTIONS IN "analytics" WITH (name = 'embed', limit = 100)
|
||||
SHOW FUNCTIONS WITH (after_name = 'embed', after_version = '1', limit = 100)
|
||||
```
|
||||
|
||||
Lists registered functions and their versions. Since a version is immutable
|
||||
and a column pins the version that fills it, this is how you find which
|
||||
versions are still in use before dropping one.
|
||||
Rows are ordered lexicographically by name and version. `after_name` and
|
||||
`after_version` must be supplied together for keyset pagination. `limit` bounds
|
||||
the response; `include_definition = false` omits the optional definition JSON.
|
||||
|
||||
## DROP FUNCTION {#drop}
|
||||
|
||||
```sql
|
||||
DROP FUNCTION embed WITH (version = '1')
|
||||
DROP FUNCTION IF EXISTS embed WITH (version = '1')
|
||||
DROP FUNCTION embed WITH (version = '1', cascade = 'true')
|
||||
```
|
||||
|
||||
`version` is required: a function is a set of immutable versions, and
|
||||
dropping is always of one specific version, never "the function" as a whole.
|
||||
`version` must identify an existing revision. DROP releases the function name
|
||||
and its object binding; physical cleanup continues separately. The result
|
||||
reports `dropped` or `not_found`. `IF EXISTS` allows a missing name.
|
||||
|
||||
<Warning>
|
||||
Without `cascade = 'true'`, dropping a version that a column still pins fails
|
||||
rather than breaking that column silently. Passing it drops the version and
|
||||
lets columns pinned to it stop refreshing. They keep their last-filled
|
||||
values, per [Guarantees](/basics/guarantees#jobs).
|
||||
</Warning>
|
||||
All function object commands retain shared results even when general query-result
|
||||
copying is disabled, so asynchronous polling can resume on another query node.
|
||||
|
||||
## What to read next {#next}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user