diff --git a/docs/src/python/python.md b/docs/src/python/python.md
index 5aa21f691..b7eb1704a 100644
--- a/docs/src/python/python.md
+++ b/docs/src/python/python.md
@@ -564,6 +564,14 @@ with BlobReader(read_range, len(payload)) as reader:
::: lancedb.functions.FunctionVersion
+::: lancedb.functions.FunctionEnvironment
+
+::: lancedb.functions.ResolvedEnvironment
+
+::: lancedb.functions.ResolvedPackage
+
+::: lancedb.functions.ResolvedEnvironmentProvenance
+
::: lancedb.functions.HuggingFaceModel
::: lancedb.functions.PythonRuntimeSpec
diff --git a/docs/web/management/function.mdx b/docs/web/management/function.mdx
index f6264edbf..efcbcc799 100644
--- a/docs/web/management/function.mdx
+++ b/docs/web/management/function.mdx
@@ -178,6 +178,13 @@ with `db.get_function(name, version=...)`. The version may be an integer or
its string form. Omit `version` to resolve and return the latest currently
visible revision.
+Re-registering unchanged code reuses the published version and its resolved
+environment lock. Pass `refresh_lock=True` to `create_function` or
+`create_function_async` to request a fresh lock for this registration. It is a
+registration action, not part of the Function's source or runtime identity.
+A deployment must support the field; an older server rejects the unknown
+field rather than silently reusing the old lock.
+
{/* Draft for the function exist_ok release.
Use `exist_ok=True` on `create_function` or `create_function_async` to return
@@ -246,6 +253,117 @@ are not included; list each namespace separately. A version's
`created_at_millis`, `metadata`, `disabled` flag, and `secret_bindings` are
all readable this way without applying or calling the function.
+### Inspect the resolved environment {#resolved-environment}
+
+The version keeps the requested runtime separate from what the server actually
+installed. The typed catalog API is available in Python and Rust; TypeScript
+does not yet expose this readback API. `version.runtime` is the specification
+sent at registration. `version.resolved_environment` is measured data from the
+built image:
+
+
+```python
+version = db.get_function("double")
+print(version.runtime) # requested runtime, or None for legacy
+print(version.environment.resolved) # measured environment, or None for legacy
+print(version.environment_report) # platform -> measured environment map
+
+if version.environment.resolved is not None:
+ for package in version.environment.resolved.packages:
+ print(package.name, package.version) # versions keep labels such as +cu130
+```
+
+{/* Draft for the typed Rust environment inspection release.
+```rust
+# async fn inspect_environment(connection: &lancedb::Connection) -> Result<(), Box> {
+let version = connection.get_function_latest("double", &[]).await?;
+println!("Requested runtime: {:?}", version.runtime());
+
+if let Some(environment) = version.resolved_environment() {
+ for package in &environment.packages {
+ println!("{} {}", package.name, package.version);
+ }
+}
+
+for (platform, environment) in version.resolved_environments() {
+ println!("{platform}: {} measured packages", environment.packages.len());
+ for package in &environment.packages {
+ println!("{} {}", package.name, package.version);
+ }
+}
+# Ok(())
+# }
+```
+*/}
+
+
+`version.environment.requested` and `version.environment.resolved` are
+convenience members over the same canonical fields; they do not add another
+wire shape. The canonical JSON exposes top-level `runtime` and
+`resolved_environment`. A missing `resolved_environment` means the version or
+environment cache predates measurement; it is unknown, not an empty installed
+package list. A package's `source` is present only when the submitted lock
+retained it, and provenance fields are reported without client-side guessing.
+
+For a multiarchitecture image, the scalar field is absent and
+`version.resolved_environments` (also available as
+`version.environment_report`) maps OCI `os/architecture` keys to the measured
+environment for that platform. A missing platform key means its measurement is
+unknown; an empty `packages` list inside a key is a measured empty environment
+and is retained. The SDK never merges platforms or fabricates an aggregate
+package list.
+
+The corresponding canonical payload has this shape:
+
+```json
+{
+ "runtime": {
+ "kind": "python",
+ "python_version": "3.12",
+ "environment": {"kind": "pip", "packages": ["vllm==0.11.0"]}
+ },
+ "resolved_environment": {
+ "packages": [
+ {
+ "name": "torch",
+ "version": "2.9.0+cu130",
+ "source": "https://packages.example/simple"
+ }
+ ],
+ "provenance": {
+ "configured_index_urls": ["https://packages.example/simple"],
+ "resolved_indexes": ["https://packages.example/simple"],
+ "cuda_toolkit": "12.8",
+ "torch_version": "torch==2.9.0+cu130"
+ },
+ "warnings": [
+ "torch resolved to torch==2.9.0+cu130 but is not pinned exactly; add torch==2.9.0+cu130 to pin it."
+ ]
+ }
+}
+```
+
+The multiarchitecture form has the same package shape per platform:
+
+```json
+{
+ "resolved_environments": {
+ "linux/amd64": {
+ "packages": [{"name": "torch", "version": "2.9.0+cu130"}]
+ },
+ "linux/arm64": {
+ "packages": []
+ }
+ }
+}
+```
+
+Environment warnings are part of the registration result. Waiting on
+`create_function_async(...)` (or calling `create_function`) emits each server
+warning from the scalar or per-platform measurements as a Python `UserWarning`;
+`get_function` and `list_functions` read the same version but do not
+replay those registration warnings.
+
## Try it in SQL {#try-sql}
A registered function is callable in SQL by its name, the same as any other
diff --git a/python/python/lancedb/__init__.py b/python/python/lancedb/__init__.py
index 31285d100..acf25d35c 100644
--- a/python/python/lancedb/__init__.py
+++ b/python/python/lancedb/__init__.py
@@ -51,11 +51,15 @@ from .functions import (
FunctionApplication as FunctionApplication,
FunctionBinding as FunctionBinding,
FunctionDefinition as FunctionDefinition,
+ FunctionEnvironment as FunctionEnvironment,
FunctionRegistrationRequest as FunctionRegistrationRequest,
FunctionRetryPolicy as FunctionRetryPolicy,
FunctionVersion as FunctionVersion,
HuggingFaceModel as HuggingFaceModel,
PythonRuntimeSpec as PythonRuntimeSpec,
+ ResolvedEnvironment as ResolvedEnvironment,
+ ResolvedEnvironmentProvenance as ResolvedEnvironmentProvenance,
+ ResolvedPackage as ResolvedPackage,
RefreshColumnResult as RefreshColumnResult,
function as function,
udf as udf,
diff --git a/python/python/lancedb/db.py b/python/python/lancedb/db.py
index b84e4d581..12c7edd5c 100644
--- a/python/python/lancedb/db.py
+++ b/python/python/lancedb/db.py
@@ -154,6 +154,38 @@ def _normalize_function_version(version: Optional[Union[int, str]]) -> Optional[
raise TypeError("version must be an int, str, or None")
+def _function_registration_decoder():
+ """Parse a registration result and emit its server warnings once.
+
+ The warnings come from the scalar environment or, for a multiarchitecture
+ image, each measured platform entry. They are part of the registration job
+ result, not a new client-side package policy. Catalog get/list readbacks
+ use ``FunctionVersion.from_json`` directly and therefore do not replay
+ them.
+ """
+ warned = False
+
+ def decode(payload: str) -> FunctionVersion:
+ nonlocal warned
+ version = FunctionVersion.from_json(payload)
+ if not warned:
+ environments = [
+ environment
+ for environment in (
+ version.resolved_environment,
+ *version.resolved_environments.values(),
+ )
+ if environment is not None
+ ]
+ for environment in environments:
+ for message in environment.warnings:
+ warnings.warn(message, UserWarning, stacklevel=3)
+ warned = True
+ return version
+
+ return decode
+
+
class DBConnection(EnforceOverrides):
"""An active LanceDB connection interface.
@@ -1018,6 +1050,7 @@ class DBConnection(EnforceOverrides):
secrets: Optional[Sequence[EnvVarSecret]] = None,
exist_ok: bool = False,
namespace_path: Optional[List[str]] = None,
+ refresh_lock: bool = False,
) -> FunctionVersion:
"""Build and register a scalar Python function, then return its version.
@@ -1040,6 +1073,13 @@ class DBConnection(EnforceOverrides):
namespace_path : list of str, optional
The namespace holding the Function. None or an empty list is the
root namespace.
+ refresh_lock : bool, default False
+ Ask the server to resolve a fresh environment lock instead of
+ reusing the published version's lock.
+
+ When the registration job resolves, each resolved-environment warning
+ reported by the server is emitted as a Python ``UserWarning``. Catalog
+ reads do not replay those registration warnings.
Examples
--------
@@ -1060,6 +1100,7 @@ class DBConnection(EnforceOverrides):
secrets=secrets,
exist_ok=exist_ok,
namespace_path=namespace_path,
+ refresh_lock=refresh_lock,
).wait()
def create_function_async(
@@ -1069,6 +1110,7 @@ class DBConnection(EnforceOverrides):
secrets: Optional[Sequence[EnvVarSecret]] = None,
exist_ok: bool = False,
namespace_path: Optional[List[str]] = None,
+ refresh_lock: bool = False,
) -> Job[FunctionVersion]:
"""Submit a scalar Python function for building and registration.
@@ -1079,6 +1121,11 @@ class DBConnection(EnforceOverrides):
artifact. The returned job has type ``query`` and the SQL query UUID as
its ID. Waiting on it returns the immutable Function version.
LanceDB Embedded connections raise ``NotImplementedError``.
+
+ ``refresh_lock`` asks the server to resolve a fresh environment lock
+ instead of reusing the published version's lock. Waiting on the job
+ emits the server's resolved-environment warnings as Python warnings;
+ reading the same version later does not repeat them.
"""
raise NotImplementedError(
_append_doc_url(
@@ -2432,6 +2479,7 @@ class LanceDBConnection(DBConnection):
secrets: Optional[Sequence[EnvVarSecret]] = None,
exist_ok: bool = False,
namespace_path: Optional[List[str]] = None,
+ refresh_lock: bool = False,
) -> Job[FunctionVersion]:
job = LOOP.run(
self._conn.create_function_async(
@@ -2439,6 +2487,7 @@ class LanceDBConnection(DBConnection):
secrets=secrets,
exist_ok=exist_ok,
namespace_path=namespace_path,
+ refresh_lock=refresh_lock,
)
)
return Job(job)
@@ -3788,6 +3837,7 @@ class AsyncConnection(object):
secrets: Optional[Sequence[EnvVarSecret]] = None,
exist_ok: bool = False,
namespace_path: Optional[List[str]] = None,
+ refresh_lock: bool = False,
) -> AsyncJob[FunctionVersion]:
"""Submit a scalar Python function for building and registration.
@@ -3802,14 +3852,16 @@ class AsyncConnection(object):
the environment variable its value arrives in. ``namespace_path`` is
the namespace the Function is registered in; None or an empty list is
the root. LanceDB Embedded connections raise ``NotImplementedError``.
+ ``refresh_lock`` asks the server to resolve a fresh environment lock
+ instead of reusing the published version's lock.
"""
if not isinstance(definition, FunctionDefinition):
raise TypeError("create_function_async requires a @function definition")
- request = definition.bind_secrets(secrets)
+ request = definition.bind_secrets(secrets).with_refresh_lock(refresh_lock)
inner = await self._inner.create_function_async(
request.to_canonical_json(), namespace_path, exist_ok=exist_ok
)
- return _typed_job(inner, FunctionVersion.from_json)
+ return _typed_job(inner, _function_registration_decoder())
async def get_function(
self,
diff --git a/python/python/lancedb/functions.py b/python/python/lancedb/functions.py
index 18c504a8f..ecbc697d1 100644
--- a/python/python/lancedb/functions.py
+++ b/python/python/lancedb/functions.py
@@ -36,6 +36,7 @@ from typing import (
Any,
Callable,
Literal,
+ NamedTuple,
Optional,
TYPE_CHECKING,
Union,
@@ -101,6 +102,12 @@ def _validate_batch_size(value: Any) -> Optional[int]:
return value
+def _validate_refresh_lock(value: Any) -> bool:
+ if not isinstance(value, bool):
+ raise ValueError("refresh_lock must be a boolean")
+ return value
+
+
def _validate_max_concurrency(value: Any) -> Optional[int]:
if value is None:
return None
@@ -544,6 +551,67 @@ class FunctionImage(_RemoteValue):
models: tuple[HuggingFaceModel, ...] = ()
+class ResolvedPackage(_RemoteValue):
+ """One installed Python distribution measured from a baked environment.
+
+ ``version`` is the complete version reported by package metadata,
+ including local labels such as ``+cu130``. ``source`` is present only when
+ the submitted lock retained a per-package source; absent means unknown, not
+ an inferred index.
+ """
+
+ name: str
+ version: str
+ source: Optional[str] = None
+
+
+class ResolvedEnvironmentProvenance(_RemoteValue):
+ """Sanitized source and accelerator provenance for a resolved environment.
+
+ ``configured_index_urls`` and ``configured_find_links`` record build
+ inputs. ``resolved_indexes`` records indexes visible in the submitted lock,
+ so a configured source is not by itself evidence that a package came from
+ it. Empty lists and absent fields remain absent; the client does not
+ synthesize them.
+ """
+
+ configured_index_urls: tuple[str, ...] = ()
+ configured_find_links: tuple[str, ...] = ()
+ resolved_indexes: tuple[str, ...] = ()
+ cuda_toolkit: Optional[str] = None
+ torch_version: Optional[str] = None
+
+
+class ResolvedEnvironment(_RemoteValue):
+ """Actual installed distributions and registration warnings for one platform.
+
+ A missing value means its measurement is unknown, not an empty
+ installed-package list. Versions are retained verbatim, including local
+ labels; package ``source`` is retained only when the producer recorded it.
+ """
+
+ packages: tuple[ResolvedPackage, ...]
+ provenance: Optional[ResolvedEnvironmentProvenance] = None
+ warnings: tuple[str, ...] = ()
+
+
+class FunctionEnvironment(NamedTuple):
+ """Requested and measured environment view for a Function version.
+
+ This is a view over
+ [FunctionVersion.runtime][lancedb.functions.FunctionVersion.runtime]
+ and
+ [FunctionVersion.resolved_environment][lancedb.functions.FunctionVersion.resolved_environment].
+ It adds no wire field and performs no second parse. ``requested`` is the
+ runtime specification supplied at registration; ``resolved`` is measured
+ data and is ``None`` when unknown. For per-platform multiarchitecture
+ measurements, use ``FunctionVersion.environment_report``.
+ """
+
+ requested: Optional[PythonRuntimeSpec]
+ resolved: Optional[ResolvedEnvironment]
+
+
def _validate_object_version(value: str) -> str:
if int(value) > 2**64 - 1:
raise ValueError("Function version exceeds uint64")
@@ -593,6 +661,17 @@ class FunctionVersion(_RemoteValue):
``result_stability`` retain the execution controls reported by the
catalog. They are ``None`` for versions registered before the
corresponding declaration.
+
+ ``runtime`` is the runtime specification requested at registration. It is
+ not evidence of what was installed. ``resolved_environment`` is measured
+ data for a single-platform image: actual package names and complete
+ versions, optional per-package source, provenance, and registration
+ warnings. ``resolved_environments`` is the corresponding map for a
+ multiarchitecture image, keyed by OCI ``os/architecture``. It is never
+ flattened into an aggregate package list. ``None`` or an empty map means
+ unknown data, not an empty installed environment. ``environment`` is a
+ convenience view with ``requested`` and ``resolved`` members over the same
+ fields.
"""
name: str
@@ -613,6 +692,11 @@ class FunctionVersion(_RemoteValue):
max_concurrency: Optional[int] = None
row_timeout_seconds: Optional[float] = None
result_stability: Optional[str] = None
+ runtime: Optional[PythonRuntimeSpec] = None
+ resolved_environment: Optional[ResolvedEnvironment] = None
+ resolved_environments: Mapping[str, ResolvedEnvironment] = Field(
+ default_factory=dict
+ )
@field_validator("batch_size", mode="before")
@classmethod
@@ -629,6 +713,24 @@ class FunctionVersion(_RemoteValue):
def _validate_row_timeout(cls, value):
return _validate_row_timeout(value)
+ @property
+ def environment(self) -> FunctionEnvironment:
+ """Requested and measured environment without adding a second parser."""
+ return FunctionEnvironment(
+ requested=self.runtime,
+ resolved=self.resolved_environment,
+ )
+
+ @property
+ def environment_report(self) -> Mapping[str, ResolvedEnvironment]:
+ """Per-platform measured reports, keyed by OCI ``os/architecture``.
+
+ This is the same map as ``resolved_environments`` and is never
+ flattened. Single-platform images use ``resolved_environment`` instead;
+ an absent platform means its measurement is unknown.
+ """
+ return self.resolved_environments
+
def __call__(self, **arguments: Any) -> FunctionApplication:
"""Bind this exact version to named table columns and constant inputs.
@@ -769,6 +871,9 @@ class FunctionRegistrationRequest(_RemoteValue):
Credential values deliberately have no field here. The only secret-shaped
thing a client sends is ``secret_bindings``: the name of a Secret the
database already holds, which the remote service resolves at execution.
+ ``refresh_lock`` is a per-registration action, not part of the Function's
+ source or runtime identity; its false default is omitted from canonical
+ JSON.
"""
name: str
@@ -781,6 +886,7 @@ class FunctionRegistrationRequest(_RemoteValue):
retry_policy: Optional[FunctionRetryPolicy] = None
secret_bindings: tuple[SecretBinding, ...] = ()
models: tuple[HuggingFaceModel, ...] = ()
+ refresh_lock: bool = False
@field_validator("batch_size", mode="before")
@classmethod
@@ -797,6 +903,18 @@ class FunctionRegistrationRequest(_RemoteValue):
def _validate_row_timeout(cls, value):
return _validate_row_timeout(value)
+ @field_validator("refresh_lock", mode="before")
+ @classmethod
+ def _validate_refresh_lock(cls, value):
+ return _validate_refresh_lock(value)
+
+ def with_refresh_lock(self, refresh_lock: bool) -> FunctionRegistrationRequest:
+ """Return this request with the registration-time refresh action set."""
+ refresh_lock = _validate_refresh_lock(refresh_lock)
+ if self.refresh_lock == refresh_lock:
+ return self
+ return self._copy(update={"refresh_lock": refresh_lock})
+
class FunctionVersionRef(_OpenRemoteValue):
name: str
@@ -3043,6 +3161,7 @@ __all__ = [
"FunctionArtifactContent",
"FunctionArtifactRequest",
"FunctionBinding",
+ "FunctionEnvironment",
"FunctionOutput",
"FunctionParameter",
"FunctionRegistrationRequest",
@@ -3059,6 +3178,9 @@ __all__ = [
"PythonEnvironmentSpec",
"PythonAdapterSpec",
"PythonRuntimeSpec",
+ "ResolvedEnvironment",
+ "ResolvedEnvironmentProvenance",
+ "ResolvedPackage",
"RefreshColumnResult",
"FunctionDefinition",
]
diff --git a/python/python/lancedb/remote/db.py b/python/python/lancedb/remote/db.py
index b9928d278..913c8fc2c 100644
--- a/python/python/lancedb/remote/db.py
+++ b/python/python/lancedb/remote/db.py
@@ -1002,6 +1002,7 @@ class RemoteDBConnection(DBConnection):
secrets: Optional[Sequence[EnvVarSecret]] = None,
exist_ok: bool = False,
namespace_path: Optional[List[str]] = None,
+ refresh_lock: bool = False,
) -> Job[FunctionVersion]:
job = LOOP.run(
self._conn.create_function_async(
@@ -1009,6 +1010,7 @@ class RemoteDBConnection(DBConnection):
secrets=secrets,
exist_ok=exist_ok,
namespace_path=namespace_path,
+ refresh_lock=refresh_lock,
)
)
return Job(job)
diff --git a/python/python/tests/test_first_class_function_slice2.py b/python/python/tests/test_first_class_function_slice2.py
index 1e896f780..6dcc0bbbe 100644
--- a/python/python/tests/test_first_class_function_slice2.py
+++ b/python/python/tests/test_first_class_function_slice2.py
@@ -26,8 +26,9 @@ import pytest
import lancedb
from lancedb import BlobReader
-from lancedb.db import AsyncConnection
+from lancedb.db import AsyncConnection, DBConnection, LanceDBConnection
from lancedb.functions import (
+ FunctionRegistrationRequest,
FunctionSignature,
FunctionVersion,
HuggingFaceModel,
@@ -82,6 +83,63 @@ def analyze_caption(caption: str) -> str:
return caption.strip()
+def _function_version_with_resolved_environment():
+ version = json.loads(
+ (FIXTURES / "remote_function_version.canonical.json").read_text()
+ )
+ version["runtime"] = json.loads(
+ normalize_score.registration_request.runtime.to_canonical_json()
+ )
+ version["resolved_environment"] = {
+ "packages": [
+ {
+ "name": "torch",
+ "version": "2.9.0+cu130",
+ "source": "https://packages.example/simple",
+ },
+ {"name": "transformers", "version": "4.57.1"},
+ ],
+ "provenance": {
+ "configured_index_urls": ["https://packages.example/simple"],
+ "configured_find_links": ["https://downloads.example/wheels"],
+ "resolved_indexes": ["https://packages.example/simple"],
+ "cuda_toolkit": "12.8",
+ "torch_version": "torch==2.9.0+cu130",
+ },
+ "warnings": [
+ "transformers resolved to transformers==4.57.1 but is not pinned "
+ "exactly; add transformers==4.57.1 to pin it."
+ ],
+ }
+ return version
+
+
+def _function_version_with_resolved_environments():
+ version = json.loads(
+ (FIXTURES / "remote_function_version.canonical.json").read_text()
+ )
+ version["runtime"] = json.loads(
+ normalize_score.registration_request.runtime.to_canonical_json()
+ )
+ version["resolved_environments"] = {
+ "linux/amd64": {
+ "packages": [
+ {
+ "name": "torch",
+ "version": "2.9.0+cu130",
+ "source": "https://packages.example/simple",
+ }
+ ],
+ "warnings": ["amd64 environment warning"],
+ },
+ "linux/arm64": {
+ "packages": [],
+ "warnings": ["arm64 environment warning"],
+ },
+ }
+ return version
+
+
def test_scalar_function_matches_shared_registration_golden_and_remains_callable():
assert isinstance(normalize_score, FunctionDefinition)
assert normalize_score(25.0) == 0.25
@@ -98,6 +156,118 @@ def test_scalar_function_matches_shared_registration_golden_and_remains_callable
}
+def test_refresh_lock_is_a_registration_option_not_part_of_identity():
+ default = normalize_score.registration_request
+ old_json = default.to_canonical_json()
+ assert "refresh_lock" not in json.loads(old_json)
+
+ refreshed = default.with_refresh_lock(True)
+ payload = json.loads(refreshed.to_canonical_json())
+ assert payload["refresh_lock"] is True
+ assert (
+ FunctionRegistrationRequest.from_json(
+ refreshed.to_canonical_json()
+ ).refresh_lock
+ is True
+ )
+ assert refreshed.artifact.digest == default.artifact.digest
+ assert refreshed.runtime.digest == default.runtime.digest
+ assert default.with_refresh_lock(False).to_canonical_json() == old_json
+ with pytest.raises(ValueError, match="refresh_lock must be a boolean"):
+ default.with_refresh_lock(1)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("exist_ok", [False, True])
+async def test_async_create_function_forwards_refresh_lock(exist_ok):
+ calls = []
+
+ class Inner:
+ async def create_function_async(
+ self, request_json, namespace_path=None, *, exist_ok=False
+ ):
+ calls.append((json.loads(request_json), namespace_path, exist_ok))
+ return object()
+
+ connection = object.__new__(AsyncConnection)
+ connection._inner = Inner()
+ await connection.create_function_async(normalize_score)
+ await connection.create_function_async(
+ normalize_score, refresh_lock=True, exist_ok=exist_ok, namespace_path=["team"]
+ )
+ with pytest.raises(ValueError, match="refresh_lock must be a boolean"):
+ await connection.create_function_async(normalize_score, refresh_lock=1)
+
+ assert len(calls) == 2
+ assert "refresh_lock" not in calls[0][0]
+ assert calls[0][1:] == (None, False)
+ assert calls[1][0]["refresh_lock"] is True
+ assert calls[1][1:] == (["team"], exist_ok)
+
+
+@pytest.mark.parametrize("exist_ok", [False, True])
+def test_sync_create_function_paths_forward_refresh_lock(exist_ok):
+ calls = []
+
+ class AsyncInner:
+ async def create_function_async(
+ self,
+ definition,
+ *,
+ secrets=None,
+ exist_ok=False,
+ namespace_path=None,
+ refresh_lock=False,
+ ):
+ calls.append(("wrapped", refresh_lock, namespace_path, exist_ok))
+ return object()
+
+ for connection_type in (LanceDBConnection, RemoteDBConnection):
+ connection = object.__new__(connection_type)
+ connection._conn = AsyncInner()
+ connection.create_function_async(
+ normalize_score,
+ refresh_lock=True,
+ exist_ok=exist_ok,
+ namespace_path=["team"],
+ )
+
+ class BlockingConnection:
+ def create_function_async(
+ self,
+ definition,
+ *,
+ secrets=None,
+ exist_ok=False,
+ namespace_path=None,
+ refresh_lock=False,
+ ):
+ calls.append(("blocking", refresh_lock, namespace_path, exist_ok))
+
+ class ImmediateJob:
+ def wait(self):
+ return "version"
+
+ return ImmediateJob()
+
+ blocking = BlockingConnection()
+ assert (
+ DBConnection.create_function(
+ blocking,
+ normalize_score,
+ refresh_lock=True,
+ exist_ok=exist_ok,
+ namespace_path=["team"],
+ )
+ == "version"
+ )
+ assert calls == [
+ ("wrapped", True, ["team"], exist_ok),
+ ("wrapped", True, ["team"], exist_ok),
+ ("blocking", True, ["team"], exist_ok),
+ ]
+
+
def test_function_declares_pinned_hugging_face_models():
model = HuggingFaceModel(
repo="sentence-transformers/all-MiniLM-L6-v2",
@@ -2205,6 +2375,205 @@ class _RawFunctionCatalog:
return None
+def test_function_version_reads_requested_and_resolved_environments():
+ legacy = json.loads(
+ (FIXTURES / "remote_function_version.canonical.json").read_text()
+ )
+ legacy_version = FunctionVersion.from_json(json.dumps(legacy))
+ assert legacy_version.runtime is None
+ assert legacy_version.resolved_environment is None
+ assert legacy_version.environment.requested is None
+ assert legacy_version.environment.resolved is None
+
+ payload = _function_version_with_resolved_environment()
+ version = FunctionVersion.from_json(json.dumps(payload))
+ assert version.environment.requested is version.runtime
+ assert version.environment.resolved is version.resolved_environment
+ assert version.runtime.kind == "python"
+ resolved = version.resolved_environment
+ assert resolved.packages[0].version == "2.9.0+cu130"
+ assert resolved.packages[0].source == "https://packages.example/simple"
+ assert resolved.packages[1].source is None
+ assert resolved.provenance.torch_version == "torch==2.9.0+cu130"
+ assert resolved.warnings == tuple(payload["resolved_environment"]["warnings"])
+
+ encoded = json.loads(version.to_canonical_json())
+ assert encoded["runtime"]["kind"] == "python"
+ assert encoded["resolved_environment"]["packages"][0]["version"] == "2.9.0+cu130"
+ assert "source" not in encoded["resolved_environment"]["packages"][1]
+ assert (
+ encoded["resolved_environment"]["provenance"]["torch_version"]
+ == "torch==2.9.0+cu130"
+ )
+ assert FunctionVersion.from_json(version.to_canonical_json()) == version
+
+ invalid = json.loads(json.dumps(payload))
+ del invalid["resolved_environment"]["packages"]
+ with pytest.raises(ValueError):
+ FunctionVersion.from_json(json.dumps(invalid))
+
+
+def test_function_version_reads_resolved_environments_by_platform():
+ legacy = json.loads(
+ (FIXTURES / "remote_function_version.canonical.json").read_text()
+ )
+ legacy_version = FunctionVersion.from_json(json.dumps(legacy))
+ assert legacy_version.resolved_environment is None
+ assert legacy_version.resolved_environments == {}
+ assert legacy_version.environment_report == {}
+
+ payload = _function_version_with_resolved_environments()
+ version = FunctionVersion.from_json(json.dumps(payload))
+ assert version.resolved_environment is None
+ assert version.resolved_environments == version.environment_report
+ assert set(version.environment_report) == {"linux/amd64", "linux/arm64"}
+ assert (
+ version.environment_report["linux/amd64"].packages[0].version == "2.9.0+cu130"
+ )
+ assert version.environment_report["linux/arm64"].packages == ()
+ assert version.environment_report["linux/arm64"].warnings == (
+ "arm64 environment warning",
+ )
+
+ encoded = json.loads(version.to_canonical_json())
+ assert "resolved_environment" not in encoded
+ assert (
+ encoded["resolved_environments"]["linux/amd64"]["packages"][0]["version"]
+ == "2.9.0+cu130"
+ )
+ assert encoded["resolved_environments"]["linux/arm64"]["packages"] == []
+ assert FunctionVersion.from_json(version.to_canonical_json()) == version
+
+ missing_platform = json.loads(json.dumps(payload))
+ del missing_platform["resolved_environments"]["linux/arm64"]
+ missing_version = FunctionVersion.from_json(json.dumps(missing_platform))
+ assert "linux/arm64" not in missing_version.environment_report
+ assert "linux/amd64" in missing_version.environment_report
+
+ empty_map = json.loads(json.dumps(payload))
+ empty_map["resolved_environments"] = {}
+ empty_version = FunctionVersion.from_json(json.dumps(empty_map))
+ assert empty_version.resolved_environments == {}
+ assert "resolved_environments" not in json.loads(empty_version.to_canonical_json())
+
+ invalid = json.loads(json.dumps(payload))
+ del invalid["resolved_environments"]["linux/amd64"]["packages"]
+ with pytest.raises(ValueError):
+ FunctionVersion.from_json(json.dumps(invalid))
+
+
+@pytest.mark.asyncio
+async def test_registration_job_emits_server_environment_warnings_once():
+ payload = _function_version_with_resolved_environment()
+
+ class InnerJob:
+ async def wait(self):
+ return json.dumps(payload)
+
+ class Inner:
+ async def create_function_async(
+ self, request_json, namespace_path=None, *, exist_ok=False
+ ):
+ assert "refresh_lock" not in json.loads(request_json)
+ return InnerJob()
+
+ connection = object.__new__(AsyncConnection)
+ connection._inner = Inner()
+ job = await connection.create_function_async(normalize_score)
+ with pytest.warns(UserWarning) as recorded:
+ version = await job.wait()
+ assert [str(w.message) for w in recorded] == list(
+ payload["resolved_environment"]["warnings"]
+ )
+ assert version.environment.resolved.warnings == tuple(
+ payload["resolved_environment"]["warnings"]
+ )
+ with warnings.catch_warnings(record=True) as caught:
+ warnings.simplefilter("always")
+ assert await job.wait() is not None
+ assert caught == []
+
+
+@pytest.mark.asyncio
+async def test_registration_job_emits_per_platform_environment_warnings():
+ payload = _function_version_with_resolved_environments()
+
+ class InnerJob:
+ async def wait(self):
+ return json.dumps(payload)
+
+ class Inner:
+ async def create_function_async(
+ self, request_json, namespace_path=None, *, exist_ok=False
+ ):
+ return InnerJob()
+
+ connection = object.__new__(AsyncConnection)
+ connection._inner = Inner()
+ job = await connection.create_function_async(normalize_score)
+ with pytest.warns(UserWarning) as recorded:
+ version = await job.wait()
+ assert [str(w.message) for w in recorded] == [
+ "amd64 environment warning",
+ "arm64 environment warning",
+ ]
+ assert version.environment_report["linux/arm64"].warnings == (
+ "arm64 environment warning",
+ )
+ with warnings.catch_warnings(record=True) as caught:
+ warnings.simplefilter("always")
+ assert await job.wait() is not None
+ assert caught == []
+
+
+def test_blocking_create_function_emits_server_environment_warnings():
+ payload = _function_version_with_resolved_environment()
+
+ class InnerJob:
+ async def wait(self):
+ return json.dumps(payload)
+
+ class Inner:
+ async def create_function_async(
+ self, request_json, namespace_path=None, *, exist_ok=False
+ ):
+ return InnerJob()
+
+ connection = object.__new__(RemoteDBConnection)
+ connection._conn = AsyncConnection(Inner())
+ with pytest.warns(UserWarning) as recorded:
+ version = DBConnection.create_function(connection, normalize_score)
+ assert [str(w.message) for w in recorded] == list(
+ payload["resolved_environment"]["warnings"]
+ )
+ assert version.environment.resolved.packages[0].version == "2.9.0+cu130"
+
+
+@pytest.mark.asyncio
+async def test_catalog_readback_does_not_replay_registration_warnings():
+ payload = _function_version_with_resolved_environment()
+ connection = AsyncConnection(_RawFunctionCatalog(payload, encode=True))
+ with warnings.catch_warnings(record=True) as caught:
+ warnings.simplefilter("always")
+ version = await connection.get_function("embed")
+ listed = [item async for item in connection.list_functions()]
+ assert caught == []
+ assert version.environment.resolved.packages[0].version == "2.9.0+cu130"
+ assert listed[0].environment.resolved == version.resolved_environment
+
+
+@pytest.mark.asyncio
+async def test_catalog_readback_does_not_replay_per_platform_warnings():
+ payload = _function_version_with_resolved_environments()
+ connection = AsyncConnection(_RawFunctionCatalog(payload, encode=True))
+ with warnings.catch_warnings(record=True) as caught:
+ warnings.simplefilter("always")
+ version = await connection.get_function("embed")
+ listed = [item async for item in connection.list_functions()]
+ assert caught == []
+ assert version.environment_report == listed[0].environment_report
+
+
def _assert_execution_control_encoding(version):
encoded = json.loads(version.to_canonical_json())
assert type(encoded["batch_size"]) is int
diff --git a/rust/lancedb/src/function.rs b/rust/lancedb/src/function.rs
index 582b5b08a..d0ef6570d 100644
--- a/rust/lancedb/src/function.rs
+++ b/rust/lancedb/src/function.rs
@@ -521,6 +521,59 @@ pub struct HuggingFaceModel {
pub revision: String,
}
+/// One installed Python distribution as measured from a Function's baked
+/// environment.
+///
+/// `version` is the complete version string reported by the package metadata,
+/// including local labels such as `+cu130`. `source` is present only when the
+/// submitted lock retained a per-package source; a missing value is unknown and
+/// must not be inferred from other package indexes.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ResolvedPackage {
+ pub name: String,
+ pub version: String,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub source: Option,
+}
+
+/// Sanitized source and accelerator provenance retained with a resolved
+/// environment.
+///
+/// `configured_*` records what the build was asked to use. `resolved_indexes`
+/// records indexes visible in the submitted lock, so a configured source is
+/// not mistaken for evidence that a package came from it. Empty lists and
+/// absent fields remain absent rather than being synthesized by the client.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ResolvedEnvironmentProvenance {
+ #[serde(default, skip_serializing_if = "Vec::is_empty")]
+ pub configured_index_urls: Vec,
+ #[serde(default, skip_serializing_if = "Vec::is_empty")]
+ pub configured_find_links: Vec,
+ #[serde(default, skip_serializing_if = "Vec::is_empty")]
+ pub resolved_indexes: Vec,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub cuda_toolkit: Option,
+ /// The fully resolved `torch==` when torch was installed.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub torch_version: Option,
+}
+
+/// Actual installed distributions and registration warnings for one native
+/// Function environment.
+///
+/// A missing environment means its measurement is unknown, not an empty
+/// installed-package list. The field keeps the complete versions and only the
+/// provenance the producer recorded; SDK readers do not recompute package
+/// policy.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ResolvedEnvironment {
+ pub packages: Vec,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub provenance: Option,
+ #[serde(default, skip_serializing_if = "Vec::is_empty")]
+ pub warnings: Vec,
+}
+
/// A complete OCI Function image. Its digest is independent of catalog names.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FunctionImage {
@@ -578,7 +631,9 @@ impl<'de> Deserialize<'de> for RowTimeoutSeconds {
/// decoding, but they are not part of this value and are omitted from
/// canonical JSON. Known fields retain their complete values, while unknown
/// fields inside the open [`FunctionImage::descriptor`] JSON object remain
-/// available.
+/// available. Single-platform measurements use `resolved_environment`;
+/// multiarchitecture measurements use `resolved_environments`, keyed by OCI
+/// `os/architecture`, without flattening the platforms.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FunctionVersion {
name: String,
@@ -626,6 +681,28 @@ pub struct FunctionVersion {
/// Result-stability value declared at registration.
#[serde(default, skip_serializing_if = "Option::is_none")]
result_stability: Option,
+ /// The runtime requested at registration, with submitted lock bytes omitted.
+ ///
+ /// This is a specification, not the measured installation. Compare it with
+ /// [`Self::resolved_environment`] when the caller needs actual package
+ /// versions.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ runtime: Option,
+ /// Actual installed distributions, provenance, and registration warnings.
+ ///
+ /// This is the single-platform compatibility field. `None` on a
+ /// multiarchitecture version is expected; use
+ /// [`Self::resolved_environments`] for its per-platform measurements.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ resolved_environment: Option,
+ /// Measurements for a multiarchitecture image, keyed by OCI
+ /// `os/architecture`.
+ ///
+ /// Unmeasured platforms are absent. An empty map is unknown, not an
+ /// aggregate of packages from the available platforms. Single-platform
+ /// images use [`Self::resolved_environment`] instead.
+ #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+ resolved_environments: BTreeMap,
}
impl FunctionVersion {
@@ -716,6 +793,35 @@ impl FunctionVersion {
self.result_stability.as_deref()
}
+ /// The runtime specification requested at registration, when exposed by the
+ /// server.
+ ///
+ /// This is the requested configuration, not evidence of what was installed.
+ pub fn runtime(&self) -> Option<&PythonRuntimeSpec> {
+ self.runtime.as_ref()
+ }
+
+ /// Actual installed distributions and registration warnings for a
+ /// single-platform image, when measured by the server.
+ ///
+ /// `None` is unknown, not an empty environment. Package versions are
+ /// retained verbatim, including local labels such as `+cu130`; `source`
+ /// remains absent when the producer did not retain it.
+ pub fn resolved_environment(&self) -> Option<&ResolvedEnvironment> {
+ self.resolved_environment.as_ref()
+ }
+
+ /// Per-platform measurements for a multiarchitecture image, keyed by OCI
+ /// `os/architecture`.
+ ///
+ /// The map is returned without flattening or synthesis. A missing platform
+ /// means its measurement is unknown; an empty environment value is a
+ /// measured empty environment and is retained. Single-platform images use
+ /// [`Self::resolved_environment`] instead.
+ pub fn resolved_environments(&self) -> &BTreeMap {
+ &self.resolved_environments
+ }
+
pub fn signature(&self) -> &FunctionSignature {
&self.signature
}
@@ -827,6 +933,10 @@ fn validate_row_timeout_value(value: Option) -> std::result::Result<(), &'s
Ok(())
}
+fn is_false(value: &bool) -> bool {
+ !*value
+}
+
/// Stable request envelope for remote immutable Function registration.
///
/// Credential values deliberately have no field here. The only secret-shaped
@@ -877,10 +987,10 @@ pub struct FunctionRegistrationRequest {
/// Model snapshots prepared by the service before user code runs.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub models: Vec,
-}
-
-fn is_false(value: &bool) -> bool {
- !*value
+ /// Ask the service to resolve a fresh environment lock for this request
+ /// instead of reusing the published version's lock. Omitted when false.
+ #[serde(default, skip_serializing_if = "is_false")]
+ pub refresh_lock: bool,
}
impl FunctionRegistrationRequest {
@@ -1465,6 +1575,165 @@ mod tests {
assert!(FunctionVersion::from_json(&document.to_string()).is_err());
}
+ #[test]
+ fn function_version_preserves_requested_and_resolved_environments() {
+ const VERSION: &str = include_str!(
+ "../tests/fixtures/first_class_functions/v1/remote_function_version.canonical.json"
+ );
+ let mut document: Value = serde_json::from_str(VERSION).unwrap();
+ let legacy = FunctionVersion::from_json(VERSION).unwrap();
+ assert!(legacy.runtime().is_none());
+ assert!(legacy.resolved_environment().is_none());
+ assert!(legacy.resolved_environments().is_empty());
+
+ document["runtime"] = serde_json::json!({
+ "kind": "python",
+ "python_version": "3.12",
+ "environment": {
+ "kind": "pip",
+ "packages": ["vllm==0.11.0"]
+ }
+ });
+ document["resolved_environment"] = serde_json::json!({
+ "packages": [
+ {
+ "name": "torch",
+ "version": "2.9.0+cu130",
+ "source": "https://packages.example/simple"
+ },
+ {
+ "name": "transformers",
+ "version": "4.57.1"
+ }
+ ],
+ "provenance": {
+ "configured_index_urls": ["https://packages.example/simple"],
+ "configured_find_links": ["https://downloads.example/wheels"],
+ "resolved_indexes": ["https://packages.example/simple"],
+ "cuda_toolkit": "12.8",
+ "torch_version": "torch==2.9.0+cu130"
+ },
+ "warnings": [
+ "transformers resolved to transformers==4.57.1 but is not pinned exactly; add transformers==4.57.1 to pin it."
+ ]
+ });
+
+ let version = FunctionVersion::from_json(&document.to_string()).unwrap();
+ assert_eq!(version.runtime().unwrap().kind(), "python");
+ assert!(version.resolved_environments().is_empty());
+ let resolved = version.resolved_environment().unwrap();
+ assert_eq!(resolved.packages[0].version, "2.9.0+cu130");
+ assert_eq!(
+ resolved.packages[0].source.as_deref(),
+ Some("https://packages.example/simple")
+ );
+ assert_eq!(resolved.packages[1].source, None);
+ assert_eq!(
+ resolved
+ .provenance
+ .as_ref()
+ .unwrap()
+ .torch_version
+ .as_deref(),
+ Some("torch==2.9.0+cu130")
+ );
+ assert_eq!(resolved.warnings.len(), 1);
+
+ let encoded = version.to_canonical_json().unwrap();
+ let encoded_value: Value = serde_json::from_str(&encoded).unwrap();
+ assert_eq!(
+ encoded_value["resolved_environment"]["packages"][0]["version"],
+ "2.9.0+cu130"
+ );
+ assert!(
+ encoded_value["resolved_environment"]["packages"][1]
+ .get("source")
+ .is_none()
+ );
+ assert_eq!(FunctionVersion::from_json(&encoded).unwrap(), version);
+
+ document["resolved_environment"] = serde_json::json!({"warnings": []});
+ assert!(FunctionVersion::from_json(&document.to_string()).is_err());
+ }
+
+ #[test]
+ fn function_version_preserves_resolved_environments_by_platform() {
+ const VERSION: &str = include_str!(
+ "../tests/fixtures/first_class_functions/v1/remote_function_version.canonical.json"
+ );
+ let mut document: Value = serde_json::from_str(VERSION).unwrap();
+ document["runtime"] = serde_json::json!({
+ "kind": "python",
+ "python_version": "3.12",
+ "environment": {
+ "kind": "pip",
+ "packages": ["vllm==0.11.0"]
+ }
+ });
+ document["resolved_environments"] = serde_json::json!({
+ "linux/amd64": {
+ "packages": [
+ {"name": "torch", "version": "2.9.0+cu130"}
+ ],
+ "warnings": ["amd64 measurement"]
+ },
+ "linux/arm64": {
+ "packages": [],
+ "warnings": ["arm64 measurement"]
+ }
+ });
+
+ let version = FunctionVersion::from_json(&document.to_string()).unwrap();
+ assert!(version.resolved_environment().is_none());
+ let environments = version.resolved_environments();
+ assert_eq!(environments.len(), 2);
+ assert_eq!(
+ environments["linux/amd64"].packages[0].version,
+ "2.9.0+cu130"
+ );
+ assert!(environments["linux/arm64"].packages.is_empty());
+ assert_eq!(environments["linux/arm64"].warnings, ["arm64 measurement"]);
+
+ let encoded = version.to_canonical_json().unwrap();
+ let encoded_value: Value = serde_json::from_str(&encoded).unwrap();
+ assert!(encoded_value.get("resolved_environment").is_none());
+ assert_eq!(
+ encoded_value["resolved_environments"]["linux/amd64"]["packages"][0]["version"],
+ "2.9.0+cu130"
+ );
+ assert_eq!(
+ encoded_value["resolved_environments"]["linux/arm64"]["packages"],
+ serde_json::json!([])
+ );
+ assert_eq!(FunctionVersion::from_json(&encoded).unwrap(), version);
+
+ document["resolved_environments"]
+ .as_object_mut()
+ .unwrap()
+ .remove("linux/arm64");
+ let missing_platform = FunctionVersion::from_json(&document.to_string()).unwrap();
+ assert!(
+ !missing_platform
+ .resolved_environments()
+ .contains_key("linux/arm64")
+ );
+
+ document["resolved_environments"] = serde_json::json!({});
+ let empty_map = FunctionVersion::from_json(&document.to_string()).unwrap();
+ assert!(empty_map.resolved_environments().is_empty());
+ assert!(
+ !empty_map
+ .to_canonical_json()
+ .unwrap()
+ .contains("resolved_environments")
+ );
+
+ document["resolved_environments"] = serde_json::json!({
+ "linux/amd64": {"warnings": []}
+ });
+ assert!(FunctionVersion::from_json(&document.to_string()).is_err());
+ }
+
#[test]
fn blob_reader_access_survives_signature_round_trip() {
let parameter: FunctionParameter = serde_json::from_value(serde_json::json!({
diff --git a/rust/lancedb/src/remote/sql_test.rs b/rust/lancedb/src/remote/sql_test.rs
index 1c39eda19..5c7ae7673 100644
--- a/rust/lancedb/src/remote/sql_test.rs
+++ b/rust/lancedb/src/remote/sql_test.rs
@@ -3171,6 +3171,38 @@ async fn function_creation_and_description_use_sql_query_handles() {
version_json["max_concurrency"] = serde_json::json!(4);
version_json["row_timeout_seconds"] = serde_json::json!(8.0);
version_json["result_stability"] = serde_json::json!("input_and_context");
+ version_json["runtime"] = request_json["runtime"].clone();
+ version_json["resolved_environment"] = serde_json::json!({
+ "packages": [
+ {
+ "name": "torch",
+ "version": "2.9.0+cu130",
+ "source": "https://packages.example/simple"
+ },
+ {
+ "name": "transformers",
+ "version": "4.57.1"
+ }
+ ],
+ "provenance": {
+ "configured_index_urls": ["https://packages.example/simple"],
+ "configured_find_links": [],
+ "resolved_indexes": ["https://packages.example/simple"],
+ "cuda_toolkit": "12.8",
+ "torch_version": "torch==2.9.0+cu130"
+ },
+ "warnings": [
+ "transformers resolved to transformers==4.57.1 but is not pinned exactly; add transformers==4.57.1 to pin it."
+ ]
+ });
+ version_json["resolved_environments"] = serde_json::json!({
+ "linux/amd64": {
+ "packages": [{"name": "torch", "version": "2.9.0+cu130"}]
+ },
+ "linux/arm64": {
+ "packages": []
+ }
+ });
if with_models {
let models = serde_json::json!([{
"repo": "sentence-transformers/all-MiniLM-L6-v2",
@@ -3217,6 +3249,17 @@ async fn function_creation_and_description_use_sql_query_handles() {
assert_eq!(created.max_concurrency(), Some(4));
assert_eq!(created.row_timeout_seconds(), Some(8.0));
assert_eq!(created.result_stability(), Some("input_and_context"));
+ assert_eq!(created.runtime().unwrap().kind(), "python");
+ assert_eq!(
+ created.resolved_environment().unwrap().packages[0].version,
+ "2.9.0+cu130"
+ );
+ assert_eq!(created.resolved_environments().len(), 2);
+ assert!(
+ created.resolved_environments()["linux/arm64"]
+ .packages
+ .is_empty()
+ );
// Assert the actual SQL body, after the same native JSON decode used
// by the Python binding, rather than only the Python declaration.
{
@@ -3240,6 +3283,23 @@ async fn function_creation_and_description_use_sql_query_handles() {
assert_eq!(created_json["max_concurrency"], 4);
assert_eq!(created_json["row_timeout_seconds"], 8.0);
assert_eq!(created_json["result_stability"], "input_and_context");
+ assert_eq!(
+ created_json["resolved_environment"]["packages"][0]["version"],
+ "2.9.0+cu130"
+ );
+ assert!(
+ created_json["resolved_environment"]["packages"][1]
+ .get("source")
+ .is_none()
+ );
+ assert_eq!(
+ created_json["resolved_environments"]["linux/amd64"]["packages"][0]["version"],
+ "2.9.0+cu130"
+ );
+ assert_eq!(
+ created_json["resolved_environments"]["linux/arm64"]["packages"],
+ serde_json::json!([])
+ );
assert_eq!(
client.describe(id).await.unwrap().status,
QueryStatus::Finished
@@ -3253,6 +3313,19 @@ async fn function_creation_and_description_use_sql_query_handles() {
assert_eq!(described.max_concurrency(), Some(4));
assert_eq!(described.row_timeout_seconds(), Some(8.0));
assert_eq!(described.result_stability(), Some("input_and_context"));
+ assert_eq!(described.runtime().unwrap().kind(), "python");
+ assert_eq!(
+ described
+ .resolved_environment()
+ .unwrap()
+ .provenance
+ .as_ref()
+ .unwrap()
+ .torch_version
+ .as_deref(),
+ Some("torch==2.9.0+cu130")
+ );
+ assert_eq!(described.resolved_environments().len(), 2);
let described_json: serde_json::Value =
serde_json::from_str(&described.to_canonical_json().unwrap()).unwrap();
assert_eq!(described_json["image"].get("models"), expected_models);
@@ -3279,6 +3352,16 @@ async fn function_creation_and_description_use_sql_query_handles() {
listed.items[0].result_stability(),
Some("input_and_context")
);
+ assert_eq!(listed.items[0].runtime().unwrap().kind(), "python");
+ assert_eq!(
+ listed.items[0]
+ .resolved_environment()
+ .unwrap()
+ .warnings
+ .len(),
+ 1
+ );
+ assert_eq!(listed.items[0].resolved_environments().len(), 2);
let listed_json: serde_json::Value =
serde_json::from_str(&listed.items[0].to_canonical_json().unwrap()).unwrap();
assert_eq!(listed_json["image"].get("models"), expected_models);
@@ -3293,6 +3376,58 @@ async fn function_creation_and_description_use_sql_query_handles() {
}
}
+#[tokio::test]
+async fn function_creation_refresh_lock_is_forwarded_only_when_true() {
+ const VERSION: &str = include_str!(
+ "../../tests/fixtures/first_class_functions/v1/remote_function_version.canonical.json"
+ );
+ const REQUEST: &str = include_str!(
+ "../../tests/fixtures/first_class_functions/v1/remote_function_registration_request.json"
+ );
+ for (refresh_lock, expect_field) in [(false, false), (true, true)] {
+ let mut request_json: serde_json::Value = serde_json::from_str(REQUEST).unwrap();
+ if refresh_lock {
+ request_json["refresh_lock"] = serde_json::json!(true);
+ }
+ let request =
+ crate::function::FunctionRegistrationRequest::from_json(&request_json.to_string())
+ .unwrap();
+ assert_eq!(request.refresh_lock, refresh_lock);
+ let result = RecordBatch::try_from_iter(vec![(
+ "definition",
+ Arc::new(StringArray::from(vec![VERSION.to_string()])) as ArrayRef,
+ )])
+ .unwrap();
+ let service = TestSqlService {
+ adaptive: true,
+ defer: false,
+ result,
+ ..Default::default()
+ };
+ let statements = service.statements.clone();
+ let (client, shutdown) = start_sql_service(service, ClientConfig::default()).await;
+ let db = RemoteDatabase::new_mock(|request| -> http::Response {
+ panic!("unexpected REST request: {}", request.url().path());
+ })
+ .with_sql_client(client.clone());
+ let job = db.create_function_async(request, &[]).await.unwrap();
+ job.wait().await.unwrap();
+ let seen = statements.lock().unwrap();
+ let encoded = seen[0]
+ .strip_prefix(r#"CREATE FUNCTION "normalize_score" FROM '"#)
+ .unwrap()
+ .strip_suffix('\'')
+ .unwrap();
+ let sent: serde_json::Value = serde_json::from_str(&encoded.replace("''", "'")).unwrap();
+ assert_eq!(sent.get("refresh_lock").is_some(), expect_field);
+ if expect_field {
+ assert_eq!(sent["refresh_lock"], serde_json::json!(true));
+ }
+ drop(seen);
+ shutdown.send(()).unwrap();
+ }
+}
+
#[tokio::test]
async fn function_creation_rejects_invalid_execution_controls_before_sql() {
const REQUEST: &str = include_str!(