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:
Jack Ye
2026-10-30 22:35:35 +08:00
committed by GitHub
parent 10c9973479
commit 564474f51a
18 changed files with 607 additions and 874 deletions
+40 -13
View File
@@ -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}