From df661cdab03410f6a347ca314e0da6c1ac36f6e3 Mon Sep 17 00:00:00 2001 From: Xuanwo Date: Tue, 15 Sep 2026 14:55:25 +0800 Subject: [PATCH] docs: clarify Function creation and registration boundaries --- python/python/lancedb/db.py | 16 +++++++++------- rust/lancedb/src/connection.rs | 7 ++++--- rust/lancedb/src/database.rs | 2 +- 3 files changed, 14 insertions(+), 11 deletions(-) diff --git a/python/python/lancedb/db.py b/python/python/lancedb/db.py index 88718e968..7ac96408e 100644 --- a/python/python/lancedb/db.py +++ b/python/python/lancedb/db.py @@ -693,19 +693,20 @@ class DBConnection(EnforceOverrides): raise NotImplementedError("serialize is not supported for this connection type") def create_function(self, definition: UdfDefinition) -> FunctionVersion: - """Register a scalar Python UDF and wait for its immutable version. + """Build and register a scalar Python UDF, then return its version. + The server builds the OCI image and registers the completed artifact. This is the blocking counterpart of :meth:`create_function_async`. Local connections raise ``NotImplementedError``. """ return self.create_function_async(definition).wait() def create_function_async(self, definition: UdfDefinition) -> Job[FunctionVersion]: - """Register a scalar Python UDF through the remote Function catalog. + """Submit a scalar Python UDF for building and registration. - Submission returns a typed job. The immutable Function version becomes - available only when :meth:`Job.wait` succeeds. Local connections raise - ``NotImplementedError``. + The server-side job builds the OCI image, then registers the completed + artifact. Waiting on the job returns the immutable Function version. + Local connections raise ``NotImplementedError``. """ raise NotImplementedError( "Function catalog operations are not supported for this connection type" @@ -2267,9 +2268,10 @@ class AsyncConnection(object): async def create_function_async( self, definition: UdfDefinition ) -> AsyncJob[FunctionVersion]: - """Register a scalar Python UDF through the remote Function catalog. + """Submit a scalar Python UDF for building and registration. - The returned typed job resolves to the immutable Function version. + The server-side job builds the OCI image, then registers the completed + artifact. Waiting on the job returns the immutable Function version. Local connections raise ``NotImplementedError``. """ if not isinstance(definition, UdfDefinition): diff --git a/rust/lancedb/src/connection.rs b/rust/lancedb/src/connection.rs index df7da3d62..8b0c16537 100644 --- a/rust/lancedb/src/connection.rs +++ b/rust/lancedb/src/connection.rs @@ -581,10 +581,11 @@ impl Connection { ) } - /// Register a Python callable as a new immutable Function version. + /// Build and register a Python callable as an immutable Function version. /// - /// Registration is remote-only and always asynchronous. Waiting on the - /// returned typed job yields the durable [`crate::function::FunctionVersion`]. + /// The server-side job builds the OCI image, then registers the completed + /// artifact. Waiting on the returned typed job yields the durable + /// [`crate::function::FunctionVersion`]. Creation is remote-only. /// Local databases return [`Error::NotSupported`]. pub async fn create_function_async( &self, diff --git a/rust/lancedb/src/database.rs b/rust/lancedb/src/database.rs index 843170030..41e5768e0 100644 --- a/rust/lancedb/src/database.rs +++ b/rust/lancedb/src/database.rs @@ -294,7 +294,7 @@ pub trait Database: /// /// See [`CloneTableRequest`] for detailed documentation and examples. async fn clone_table(&self, request: CloneTableRequest) -> Result>; - /// Register an immutable Function version through the remote catalog. + /// Submit a Function creation job that builds an image and registers it. async fn create_function_async( &self, _request: crate::function::FunctionRegistrationRequest,