Merge remote-tracking branch 'origin/main' into gatekeeper/fix-2325-1

# Conflicts:
#	Cargo.lock

python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lancedb-python"
-version = "0.40.0-beta.1"
+version = "0.40.0-beta.3"
 publish = false
 edition.workspace = true
 description = "Python bindings for LanceDB"

python/pyproject.toml

@@ -126,6 +126,7 @@ include = [
     "python/lancedb/rerankers/util.py",
     "python/lancedb/rerankers/__init__.py",
     "python/lancedb/rerankers/voyageai.py",
+    "python/lancedb/rerankers/typesafe.py",
     "python/lancedb/rerankers/jinaai.py",
     "python/lancedb/rerankers/openai.py",
     "python/lancedb/rerankers/cross_encoder.py",

python/python/lancedb/__init__.py

@@ -12,6 +12,9 @@ __version__ = importlib.metadata.version("lancedb")
 
 from ._lancedb import connect as lancedb_connect
 from ._lancedb import FtsToken
+from ._lancedb import FunctionErrorFragment as FunctionErrorFragment
+from ._lancedb import FunctionErrorRecord as FunctionErrorRecord
+from ._lancedb import FunctionErrors as FunctionErrors
 from ._lancedb import LsmWriteSpec
 from ._lancedb import tokenize as _tokenize
 from .common import URI, sanitize_uri

python/python/lancedb/_lancedb.pyi

@@ -461,6 +461,12 @@ class Table:
     ) -> AddColumnsResult: ...
     async def refresh_column(self, column: str) -> RefreshColumnResult: ...
     async def refresh_column_async(self, column: str) -> Job: ...
+    async def function_errors(
+        self,
+        job_id: Optional[str] = None,
+        column: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> FunctionErrors: ...
     async def refresh_materialized_view(
         self, full: bool = False, source_version: Optional[int] = None
     ) -> RefreshMaterializedViewResult: ...
@@ -821,6 +827,29 @@ class RefreshColumnResult:
     rows_filled: int
     version: int
 
+class FunctionErrorRecord:
+    job_id: str
+    fragment_id: int
+    row_offset: Optional[int]
+    column: str
+    function: str
+    function_version: str
+    table_version: int
+    error_type: str
+    error_message: str
+    created_at_millis: int
+
+class FunctionErrorFragment:
+    job_id: str
+    fragment_id: int
+    rows_skipped: int
+    rows_recorded: int
+
+class FunctionErrors:
+    records: list[FunctionErrorRecord]
+    fragments: list[FunctionErrorFragment]
+    truncated: bool
+
 class RefreshMaterializedViewResult:
     @staticmethod
     def from_json(value: str) -> RefreshMaterializedViewResult: ...

python/python/lancedb/embeddings/open_clip.py

@@ -7,6 +7,7 @@ import io
 import os
 import urllib.parse as urlparse
 from typing import TYPE_CHECKING, List, Union
+from urllib.request import url2pathname
 
 import numpy as np
 import pyarrow as pa
@@ -154,7 +155,7 @@ class OpenClipEmbeddings(EmbeddingFunction):
             parsed = urlparse.urlparse(image)
             # TODO handle drive letter on windows.
             if parsed.scheme == "file":
-                return PIL_Image.open(parsed.path)
+                return PIL_Image.open(url2pathname(parsed.path))
             elif parsed.scheme == "":
                 return PIL_Image.open(image if os.name == "nt" else parsed.path)
             elif parsed.scheme.startswith("http"):

python/python/lancedb/materialized_view.py

@@ -7,7 +7,7 @@ maintained by refresh. See ``DBConnection.create_materialized_view``."""
 from __future__ import annotations
 
 import json
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, Dict, List, Optional, Sequence, Tuple, Union
 
 from .background_loop import LOOP
@@ -29,22 +29,24 @@ SelectArg = Union[
 ]
 
 
+DEFINITION_FORMAT = 1
+"""The stored layout this version reads: ``{"format": 1, "query": "<SQL>"}``.
+A ``kind`` key beside it is for readers older than the format number."""
+
+
 @dataclass
 class MaterializedViewDefinition:
-    """The query that defines a materialized view."""
+    """The query that defines a materialized view, as stored::
 
-    source_table: str
-    """Name of the source table, in the same database as the view."""
-    projections: List[Tuple[str, str]]
-    """``(output column, SQL expression)`` pairs, in view schema order."""
-    filter: Optional[str] = None
-    """SQL predicate selecting the source rows the view holds."""
-    limit: Optional[int] = None
-    """Cap on the number of rows the view holds."""
-    inputs: List[str] = field(default_factory=list)
-    """Source columns the projections and filter read."""
-    source_namespace: List[str] = field(default_factory=list)
-    """Namespace holding the source table; empty is the root namespace."""
+        SELECT columns
+        FROM [ns.]table [, function(args) AS alias | , UNNEST(column) AS alias]
+        [WHERE predicate] [LIMIT n]
+
+    A Function in ``FROM`` position yields one row per element it returns.
+    """
+
+    query: str
+    """The defining query, in the canonical spelling the server stores."""
 
 
 def _definition_from_schema(
@@ -54,38 +56,64 @@ def _definition_from_schema(
     raw = metadata.get(DEFINITION_META_KEY)
     if raw is None:
         raise ValueError(f"Table '{name}' is not a materialized view")
-    value = json.loads(raw)
+    return _definition_from_value(json.loads(raw), name)
+
+
+def _definition_from_json(raw: str, name: str = "") -> MaterializedViewDefinition:
+    """Parse the definition native code hands over, in its stored layout."""
+    return _definition_from_value(json.loads(raw), name)
+
+
+def _definition_from_value(value: dict, name: str) -> MaterializedViewDefinition:
+    fmt = value.get("format")
+    if fmt is not None:
+        # A newer writer's layout is reported, never guessed at.
+        if not isinstance(fmt, int) or fmt > DEFINITION_FORMAT:
+            raise NotImplementedError(
+                f"materialized view '{name}' is stored in format {fmt}, which "
+                "this version of lancedb cannot refresh"
+            )
+        return MaterializedViewDefinition(query=value["query"])
+    # The structured layout written before the format number.
     kind = value.get("kind")
-    # "namespaced_select" keeps older readers from resolving the source at root.
     if kind not in ("select", "namespaced_select"):
         raise NotImplementedError(
-            f"materialized view '{name}' is defined by '{kind}', which this "
-            "version of lancedb cannot refresh"
+            f"materialized view '{name}' is stored in format kind '{kind}', "
+            "which this version of lancedb cannot refresh"
         )
-    return MaterializedViewDefinition(
-        source_table=value["source_table"],
-        projections=[
-            (p["output"], p["expression"]) for p in value.get("projections", [])
-        ],
-        filter=value.get("filter"),
-        limit=value.get("limit"),
-        inputs=value.get("inputs", []),
-        source_namespace=value.get("source_namespace", []),
-    )
+    return MaterializedViewDefinition(query=_legacy_query(value))
 
 
-def _definition_from_json(raw: str) -> MaterializedViewDefinition:
-    value = json.loads(raw)
-    return MaterializedViewDefinition(
-        source_table=value["source_table"],
-        projections=[
-            (p["output"], p["expression"]) for p in value.get("projections", [])
-        ],
-        filter=value.get("filter"),
-        limit=value.get("limit"),
-        inputs=value.get("inputs", []),
-        source_namespace=value.get("source_namespace", []),
+def _legacy_ident(name: str) -> str:
+    if name and all(c == "_" or c.islower() or c.isdigit() for c in name):
+        return name
+    return _quote_identifier(name)
+
+
+def _legacy_query(value: dict) -> str:
+    """Render the pre-format structured layout as the query it described."""
+    projections = value.get("projections", [])
+    if projections:
+        items = []
+        for p in projections:
+            output, expression = p["output"], p["expression"]
+            if expression in (output, _quote_identifier(output)):
+                items.append(expression)
+            else:
+                items.append(f"{expression} AS {_legacy_ident(output)}")
+        columns = ", ".join(items)
+    else:
+        columns = "*"
+    table = ".".join(
+        _legacy_ident(part)
+        for part in [*value.get("source_namespace", []), value["source_table"]]
     )
+    query = f"SELECT {columns} FROM {table}"
+    if value.get("filter") is not None:
+        query += f" WHERE {value['filter']}"
+    if value.get("limit") is not None:
+        query += f" LIMIT {value['limit']}"
+    return query
 
 
 def _quote_identifier(name: str) -> str:

python/python/lancedb/remote/table.py

@@ -996,6 +996,16 @@ class RemoteTable(Table):
     def refresh_column_async(self, column: str) -> Job[RefreshColumnResult]:
         return Job(LOOP.run(self._table.refresh_column_async(column)))
 
+    def function_errors(
+        self,
+        job_id: Optional[str] = None,
+        column: Optional[str] = None,
+        limit: Optional[int] = None,
+    ):
+        return LOOP.run(
+            self._table.function_errors(job_id=job_id, column=column, limit=limit)
+        )
+
     def alter_columns(
         self, *alterations: Iterable[Dict[str, str]]
     ) -> AlterColumnsResult:

python/python/lancedb/rerankers/__init__.py

@@ -11,6 +11,7 @@ from .jinaai import JinaReranker
 from .rrf import RRFReranker
 from .mrr import MRRReranker
 from .answerdotai import AnswerdotaiRerankers
+from .typesafe import TypeSafeReranker
 from .voyageai import VoyageAIReranker
 from .watsonx import WatsonxReranker
 
@@ -27,6 +28,7 @@ __all__ = [
     "JinaReranker",
     "RRFReranker",
     "AnswerdotaiRerankers",
+    "TypeSafeReranker",
     "VoyageAIReranker",
     "MRRReranker",
     "WatsonxReranker",

python/python/lancedb/rerankers/typesafe.py

@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+
+from concurrent.futures import ThreadPoolExecutor
+from functools import cached_property
+from typing import Any, Dict, Mapping, Optional
+
+import pyarrow as pa
+
+from ..util import attempt_import_or_raise
+from .base import Reranker
+
+DEFAULT_INSTRUCTIONS = (
+    "Does the document contain information that answers or directly addresses "
+    "the query?"
+)
+DEFAULT_CRITERIA = {
+    "true": "The document answers the query or states facts the query asks about.",
+    "false": "The document is off-topic, or only shares keywords or a general "
+    "subject with the query without addressing it.",
+}
+# The key TypeSafe returns the answer under. It is not sent to the model.
+_QUESTION_ID = "relevance"
+
+
+class TypeSafeReranker(Reranker):
+    """
+    Reranks the results using the TypeSafe System One API.
+    https://docs.typesafe.ai/cookbooks/rerank_typesafe
+
+    Each result is scored independently: TypeSafe reads the query together with
+    the result's ``column`` value and answers a yes/no ("noul") question about
+    whether the document is relevant. The probability of "yes", between 0 and 1,
+    becomes the ``_relevance_score``. Because every score is an absolute
+    probability rather than a position in the list, scores are comparable
+    across queries and can be thresholded. They are model estimates, though,
+    and can vary slightly between identical calls, so results with close scores
+    may swap places when the same search is repeated.
+
+    One request is sent per result, up to ``max_concurrency`` at a time.
+
+    Parameters
+    ----------
+    model_name : str, default "jev-latest"
+        The TypeSafe model to use.
+    column : str, default "text"
+        The name of the column holding the document text to score.
+    instructions : str, optional
+        The yes/no question asked about each query and document pair. The state
+        TypeSafe reads is ``{"query": <query>, "document": <column value>}``.
+        Defaults to a generic relevance question.
+    criteria : Mapping[str, str], optional
+        What a "yes" and a "no" mean, as a mapping with the keys ``"true"`` and
+        ``"false"``. Domain-specific criteria usually rank better than the
+        generic default. Pass an empty mapping to send no criteria.
+    return_score : str, default "relevance"
+        Options are "relevance" or "all". If "all", keeps the vector and FTS
+        scores alongside the relevance score.
+    api_key : str, optional
+        The API key to use. If None, the TypeSafe SDK reads the
+        ``TYPESAFE_API_KEY`` environment variable.
+    max_concurrency : int, default 8
+        The maximum number of TypeSafe requests in flight for one rerank call.
+    """
+
+    def __init__(
+        self,
+        model_name: str = "jev-latest",
+        column: str = "text",
+        instructions: Optional[str] = None,
+        criteria: Optional[Mapping[str, str]] = None,
+        return_score: str = "relevance",
+        api_key: Optional[str] = None,
+        max_concurrency: int = 8,
+    ):
+        super().__init__(return_score)
+        if max_concurrency < 1:
+            raise ValueError("max_concurrency must be at least 1")
+        criteria = DEFAULT_CRITERIA if criteria is None else dict(criteria)
+        unknown = set(criteria) - {"true", "false"}
+        if unknown:
+            raise ValueError(
+                f"criteria keys must be 'true' or 'false', got {sorted(unknown)}"
+            )
+        self.model_name = model_name
+        self.column = column
+        self.instructions = instructions or DEFAULT_INSTRUCTIONS
+        self.criteria = criteria
+        self.api_key = api_key
+        self.max_concurrency = max_concurrency
+
+    def __str__(self):
+        return f"TypeSafeReranker(model_name={self.model_name})"
+
+    @cached_property
+    def _client(self):
+        typesafe_sdk = attempt_import_or_raise("typesafe_sdk", "typesafe-sdk")
+        return typesafe_sdk.TypeSafeClient(api_key=self.api_key)
+
+    @cached_property
+    def _question(self) -> Dict[str, Any]:
+        question: Dict[str, Any] = {"type": "noul", "instructions": self.instructions}
+        if self.criteria:
+            question["criteria"] = self.criteria
+        return question
+
+    def _score(self, query: str, document: Optional[str]) -> float:
+        if document is None:
+            return 0.0
+        response = self._client.system_one(
+            state={"query": query, "document": document},
+            questions={_QUESTION_ID: self._question},
+            model=self.model_name,
+        )
+        return response.answers[_QUESTION_ID].noul
+
+    def _rerank(self, result_set: pa.Table, query: str) -> pa.Table:
+        result_set = self._handle_empty_results(result_set)
+        if len(result_set) == 0:
+            return result_set
+        docs = result_set[self.column].to_pylist()
+        # Rerankers are also called synchronously from inside the async query
+        # APIs, so the requests run on threads rather than on an event loop.
+        with ThreadPoolExecutor(
+            max_workers=min(self.max_concurrency, len(docs))
+        ) as pool:
+            scores = list(pool.map(lambda doc: self._score(query, doc), docs))
+        result_set = result_set.append_column(
+            "_relevance_score", pa.array(scores, type=pa.float32())
+        )
+        return result_set.sort_by([("_relevance_score", "descending")])
+
+    def rerank_hybrid(
+        self,
+        query: str,
+        vector_results: pa.Table,
+        fts_results: pa.Table,
+    ):
+        if self.score == "all":
+            combined_results = self._merge_and_keep_scores(vector_results, fts_results)
+        else:
+            combined_results = self.merge_results(vector_results, fts_results)
+        combined_results = self._rerank(combined_results, query)
+        if self.score == "relevance":
+            combined_results = self._keep_relevance_score(combined_results)
+        return combined_results
+
+    def rerank_vector(self, query: str, vector_results: pa.Table):
+        vector_results = self._rerank(vector_results, query)
+        if self.score == "relevance":
+            vector_results = vector_results.drop_columns(["_distance"])
+        return vector_results
+
+    def rerank_fts(self, query: str, fts_results: pa.Table):
+        fts_results = self._rerank(fts_results, query)
+        if self.score == "relevance":
+            fts_results = fts_results.drop_columns(["_score"])
+        return fts_results

python/python/lancedb/table.py

@@ -187,6 +187,7 @@ if TYPE_CHECKING:
         CompactionStats,
         Tag,
         AddColumnsResult,
+        FunctionErrors,
         RefreshColumnResult,
         AddResult,
         AlterColumnsResult,
@@ -2400,6 +2401,47 @@ class Table(ABC):
         'finished'
         """
 
+    @abstractmethod
+    def function_errors(
+        self,
+        job_id: Optional[str] = None,
+        column: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> "FunctionErrors":
+        """
+        The per-row errors Function refreshes recorded on this table.
+
+        A refresh running under a skip policy records each row it skipped
+        with the input that failed and the error. This lists those records,
+        newest job first, plus a summary for any fragment whose per-row
+        detail was capped. LanceDB Cloud and Enterprise only; reading errors
+        needs read access to the table, since a message carries the value
+        that failed.
+
+        Parameters
+        ----------
+        job_id: str, optional
+            Only errors recorded by this job.
+        column: str, optional
+            Only errors on this column.
+        limit: int, optional
+            At most this many records (server default 10000, cap 100000).
+
+        Returns
+        -------
+        FunctionErrors
+            ``records``, ``fragments`` and ``truncated``, the last saying
+            whether the listing stopped at its limit.
+
+        Examples
+        --------
+        >>> errors = table.function_errors(column="embedding")  # doctest: +SKIP
+        >>> for record in errors.records:  # doctest: +SKIP
+        ...     print(record.job_id, record.row_offset, record.error_message)
+        >>> if errors.truncated:  # doctest: +SKIP
+        ...     print("listing stopped at the limit")
+        """
+
     @abstractmethod
     def alter_columns(self, *alterations: Iterable[Dict[str, str]]):
         """
@@ -4461,6 +4503,18 @@ class LanceTable(Table):
         """
         return Job(LOOP.run(self._table.refresh_column_async(column)))
 
+    def function_errors(
+        self,
+        job_id: Optional[str] = None,
+        column: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> "FunctionErrors":
+        """The per-row errors Function refreshes recorded on this table. See
+        [`Table.function_errors`][lancedb.table.Table.function_errors]."""
+        return LOOP.run(
+            self._table.function_errors(job_id=job_id, column=column, limit=limit)
+        )
+
     def alter_columns(
         self, *alterations: Iterable[Dict[str, str]]
     ) -> AlterColumnsResult:
@@ -6527,6 +6581,49 @@ class AsyncTable:
         """
         return await self._inner.refresh_column(column)
 
+    async def function_errors(
+        self,
+        job_id: Optional[str] = None,
+        column: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> "FunctionErrors":
+        """
+        The per-row errors Function refreshes recorded on this table.
+
+        A refresh running under a skip policy records each row it skipped
+        with the input that failed and the error. This lists those records,
+        newest job first, plus a summary for any fragment whose per-row
+        detail was capped. LanceDB Cloud and Enterprise only; reading errors
+        needs read access to the table, since a message carries the value
+        that failed.
+
+        Parameters
+        ----------
+        job_id: str, optional
+            Only errors recorded by this job.
+        column: str, optional
+            Only errors on this column.
+        limit: int, optional
+            At most this many records (server default 10000, cap 100000).
+
+        Returns
+        -------
+        FunctionErrors
+            ``records``, ``fragments`` and ``truncated``, the last saying
+            whether the listing stopped at its limit.
+
+        Examples
+        --------
+        >>> errors = await table.function_errors(column="embedding")  # doctest: +SKIP
+        >>> for record in errors.records:  # doctest: +SKIP
+        ...     print(record.job_id, record.row_offset, record.error_message)
+        >>> if errors.truncated:  # doctest: +SKIP
+        ...     print("listing stopped at the limit")
+        """
+        return await self._inner.function_errors(
+            job_id=job_id, column=column, limit=limit
+        )
+
     async def refresh_column_async(
         self, column: str
     ) -> AsyncJob[RefreshColumnJobResult]:

python/python/tests/test_embeddings.py

@@ -633,6 +633,18 @@ def test_url_retrieve_downloads_image():
     assert img.size[0] > 0 and img.size[1] > 0
 
 
+def test_open_clip_opens_percent_encoded_file_uri(tmp_path):
+    """OpenCLIP should decode local file URIs before opening them."""
+    Image = pytest.importorskip("PIL.Image")
+    from lancedb.embeddings.open_clip import OpenClipEmbeddings
+
+    image_path = tmp_path / "test image.png"
+    Image.new("RGB", (4, 4), color="red").save(image_path, format="PNG")
+
+    with OpenClipEmbeddings._to_pil(None, image_path.as_uri()) as image:
+        assert image.size == (4, 4)
+
+
 def test_jina_generate_image_input_dict_local_path(tmp_path):
     """
     JinaEmbeddings._generate_image_input_dict must accept a local image path

python/python/tests/test_materialized_views.py

@@ -217,10 +217,7 @@ def test_definition_round_trips(tmp_path):
 
     view = db.open_materialized_view("adults")
     assert view.definition == MaterializedViewDefinition(
-        source_table="people",
-        projections=[("name", "`name`"), ("age", "`age`")],
-        filter="age >= 18",
-        inputs=["age", "name"],
+        query="SELECT name, age FROM people WHERE age >= 18"
     )
 
 
@@ -305,7 +302,7 @@ async def test_async_create_refresh_and_open(tmp_path):
 
     reopened = await db.open_materialized_view("shouts")
     definition = await reopened.definition()
-    assert definition.projections == [("shout", "upper(name)")]
+    assert definition.query == "SELECT upper(name) AS shout FROM people"
     assert await db.list_materialized_views() == ["shouts"]
 
 
@@ -423,7 +420,7 @@ def test_namespace_connection_materialized_views(tmp_path):
     assert db.list_materialized_views() == ["adults"]
 
     reopened = db.open_materialized_view("adults")
-    assert reopened.definition.source_table == "people"
+    assert reopened.definition.query.startswith("SELECT name, age FROM ")
     with pytest.raises(ValueError, match="not a materialized view"):
         db.open_materialized_view("people")
 
@@ -458,7 +455,7 @@ async def test_async_namespace_connection_materialized_views(tmp_path):
     assert await db.list_materialized_views() == ["adults"]
 
     reopened = await db.open_materialized_view("adults")
-    assert (await reopened.definition()).source_table == "people"
+    assert (await reopened.definition()).query.startswith("SELECT name, age FROM ")
 
     # The view's table came through the namespace, not straight from the
     # inner connection: a bare inner table carries no namespace context, so
@@ -484,36 +481,49 @@ async def test_async_namespace_connection_materialized_views(tmp_path):
     assert await db.list_materialized_views() == []
 
 
-def test_namespaced_select_kind_is_read_and_unknown_kinds_are_refused():
+def test_stored_queries_and_legacy_layouts_are_read():
     import json
 
     import pyarrow as pa
 
     from lancedb.materialized_view import _definition_from_schema
 
-    def schema_with(definition: dict) -> pa.Schema:
-        return pa.schema([pa.field("id", pa.int32())]).with_metadata(
+    def read(definition: dict) -> MaterializedViewDefinition:
+        schema = pa.schema([pa.field("id", pa.int32())]).with_metadata(
             {b"mv.definition": json.dumps(definition).encode()}
         )
+        return _definition_from_schema(schema, "v")
 
-    # "namespaced_select" is the namespaced form of "select": same shape,
-    # a separate kind so readers that predate it refuse instead of
-    # resolving the source at the root.
-    definition = _definition_from_schema(
-        schema_with(
+    query = "SELECT id, c.chunk FROM ns.docs, UNNEST(chunks) AS c WHERE id > 1"
+    assert read({"format": 1, "query": query}).query == query
+
+    # The structured layout written before the format number reads as the
+    # query it described, under either of its kind tags.
+    assert (
+        read(
             {
                 "kind": "namespaced_select",
                 "source_table": "people",
                 "source_namespace": ["ns"],
-                "projections": [{"output": "name", "expression": "name"}],
+                "projections": [
+                    {"output": "name", "expression": "`name`"},
+                    {"output": "Shout", "expression": "upper(name)"},
+                ],
+                "filter": "age >= 18",
+                "limit": 10,
             }
-        ),
-        "v",
+        ).query
+        == "SELECT `name`, upper(name) AS `Shout` FROM ns.people "
+        "WHERE age >= 18 LIMIT 10"
+    )
+    assert read({"kind": "select", "source_table": "people"}).query == (
+        "SELECT * FROM people"
     )
-    assert definition.source_table == "people"
-    assert definition.source_namespace == ["ns"]
 
-    with pytest.raises(NotImplementedError, match="cannot refresh"):
-        _definition_from_schema(
-            schema_with({"kind": "select_v3", "source_table": "people"}), "v"
-        )
+    # A newer writer's layout is reported, never guessed at.
+    for newer in (
+        {"format": 2, "query": query},
+        {"kind": "select_v3", "source_table": "people"},
+    ):
+        with pytest.raises(NotImplementedError, match="cannot refresh"):
+            read(newer)

python/python/tests/test_remote_db.py

@@ -982,6 +982,71 @@ def test_remote_refresh_async_returns_typed_terminal_result():
     assert result.version == 8
 
 
+def test_remote_function_errors_lists_the_rows_a_refresh_skipped():
+    listing = {
+        "records": [
+            {
+                "job_id": "j-7",
+                "fragment_id": 3,
+                "row_offset": 9,
+                "column": "embedding",
+                "function": "embed",
+                "function_version": "2",
+                "table_version": 11,
+                "error_type": "ValueError",
+                "error_message": "bad input 'x'",
+                "created_at_millis": 1700000000000,
+            }
+        ],
+        "fragments": [
+            {
+                "job_id": "j-7",
+                "fragment_id": 4,
+                "rows_skipped": 500,
+                "rows_recorded": 100,
+            }
+        ],
+        "truncated": True,
+    }
+    bodies = []
+
+    def handler(request):
+        content_len = int(request.headers.get("Content-Length", 0))
+        body = request.rfile.read(content_len) if content_len > 0 else b""
+        if request.path == "/v1/table/test/errors":
+            bodies.append(json.loads(body))
+            request.send_response(200)
+            request.send_header("Content-Type", "application/json")
+            request.end_headers()
+            request.wfile.write(json.dumps(listing).encode())
+        elif request.path == "/v1/table/test/describe/":
+            request.send_response(200)
+            request.send_header("Content-Type", "application/json")
+            request.end_headers()
+            request.wfile.write(
+                json.dumps({"version": 1, "schema": {"fields": []}}).encode()
+            )
+        else:
+            request.send_response(404)
+            request.end_headers()
+
+    with mock_lancedb_connection(handler) as db:
+        table = db.open_table("test")
+        errors = table.function_errors(job_id="j-7", column="embedding", limit=2)
+        everything = table.function_errors()
+
+    assert bodies == [{"job_id": "j-7", "column": "embedding", "limit": 2}, {}]
+    assert errors.truncated is True
+    assert [r.error_message for r in errors.records] == ["bad input 'x'"]
+    assert errors.records[0].row_offset == 9
+    assert errors.records[0].function_version == "2"
+    assert (errors.fragments[0].rows_skipped, errors.fragments[0].rows_recorded) == (
+        500,
+        100,
+    )
+    assert everything.truncated is True
+
+
 def test_remote_job_wait_raises_on_failure():
     from lancedb.exceptions import JobFailedError
     from lancedb.index import BTree

python/python/tests/test_rerankers.py

@@ -21,6 +21,7 @@ from lancedb.rerankers import (
     OpenaiReranker,
     JinaReranker,
     AnswerdotaiRerankers,
+    TypeSafeReranker,
     VoyageAIReranker,
     MRRReranker,
     WatsonxReranker,
@@ -101,7 +102,15 @@ def get_test_table(tmp_path):
     return table, MyTable
 
 
-def _run_test_reranker(reranker, table, query, query_vector, schema):
+def _run_test_reranker(
+    reranker, table, query, query_vector, schema, deterministic=True
+):
+    """Exercise a reranker across search types.
+
+    Set ``deterministic=False`` for rerankers whose scores can vary between
+    identical calls, such as remote model APIs; repeated searches are then not
+    expected to return the same order.
+    """
     # Hybrid search setting
     result1 = (
         table.search(query, query_type="hybrid", vector_column_name="vector")
@@ -113,7 +122,8 @@ def _run_test_reranker(reranker, table, query, query_vector, schema):
         .rerank(reranker=reranker)
         .to_pydantic(schema)
     )
-    assert result1 == result2
+    if deterministic:
+        assert result1 == result2
 
     query_vector = table.to_pandas()["vector"][0]
     result = (
@@ -203,7 +213,9 @@ def _run_test_reranker(reranker, table, query, query_vector, schema):
     )
     assert len(result_deduped) <= 20
     result_arrow = reranker.rerank_multivector([rs1.to_arrow(), rs2.to_arrow()], query)
-    assert len(result) == 20 and result == result_arrow
+    assert len(result) == 20 and len(result_arrow) == 20
+    if deterministic:
+        assert result == result_arrow
 
 
 def _run_test_hybrid_reranker(reranker, tmp_path):
@@ -515,6 +527,95 @@ def test_voyageai_reranker(tmp_path):
     _run_test_reranker(reranker, table, "single player experience", None, schema)
 
 
+class _FakeTypeSafeClient:
+    """Stands in for ``typesafe_sdk.TypeSafeClient``; scores by word overlap."""
+
+    def __init__(self):
+        self.requests = []
+
+    def system_one(self, state, questions, model):
+        self.requests.append((state, questions, model))
+        query_words = set(state["query"].lower().split())
+        doc_words = set(state["document"].lower().split())
+        noul = len(query_words & doc_words) / len(query_words)
+        answers = {key: type("NoulAnswer", (), {"noul": noul})() for key in questions}
+        return type("SystemOneResponse", (), {"answers": answers})()
+
+
+def test_typesafe_reranker_with_fake_client(tmp_path):
+    reranker = TypeSafeReranker(max_concurrency=4)
+    reranker._client = _FakeTypeSafeClient()
+    table, schema = get_test_table(tmp_path)
+    _run_test_reranker(reranker, table, "single player experience", None, schema)
+
+    state, questions, model = reranker._client.requests[0]
+    assert model == "jev-latest"
+    assert set(state) == {"query", "document"}
+    assert questions == {
+        "relevance": {
+            "type": "noul",
+            "instructions": reranker.instructions,
+            "criteria": reranker.criteria,
+        }
+    }
+
+
+def test_typesafe_reranker_scores_each_row():
+    reranker = TypeSafeReranker(
+        column="body",
+        instructions="Is this about cats?",
+        criteria={},
+        return_score="all",
+    )
+    reranker._client = _FakeTypeSafeClient()
+    results = pa.table(
+        {
+            "body": ["dogs bark", "cats purr and cats nap", None, "cats"],
+            "_distance": [0.1, 0.2, 0.3, 0.4],
+        }
+    )
+
+    reranked = reranker.rerank_vector("cats nap", results)
+
+    assert reranked["body"].to_pylist() == [
+        "cats purr and cats nap",
+        "cats",
+        "dogs bark",
+        None,
+    ]
+    assert reranked["_relevance_score"].to_pylist() == [1.0, 0.5, 0.0, 0.0]
+    assert reranked["_distance"].to_pylist() == [0.2, 0.4, 0.1, 0.3]
+    # Null documents are scored 0 without a request.
+    assert len(reranker._client.requests) == 3
+    assert reranker._client.requests[0][1] == {
+        "relevance": {"type": "noul", "instructions": "Is this about cats?"}
+    }
+
+
+def test_typesafe_reranker_rejects_invalid_arguments():
+    with pytest.raises(ValueError, match="criteria keys"):
+        TypeSafeReranker(criteria={"yes": "relevant"})
+    with pytest.raises(ValueError, match="max_concurrency"):
+        TypeSafeReranker(max_concurrency=0)
+
+
+@pytest.mark.skipif(
+    os.environ.get("TYPESAFE_API_KEY") is None, reason="TYPESAFE_API_KEY not set"
+)
+def test_typesafe_reranker(tmp_path):
+    pytest.importorskip("typesafe_sdk")
+    reranker = TypeSafeReranker()
+    table, schema = get_test_table(tmp_path)
+    _run_test_reranker(
+        reranker,
+        table,
+        "single player experience",
+        None,
+        schema,
+        deterministic=False,
+    )
+
+
 def test_empty_result_reranker():
     pytest.importorskip("sentence_transformers")
     db = lancedb.connect("memory://")

python/python/tests/test_table.py

@@ -4449,6 +4449,13 @@ async def test_computed_column_async(tmp_path):
     assert (await table.to_arrow())["tripled"].to_pylist() == [9]
 
 
+def test_function_errors_are_remote_only(tmp_path):
+    db = lancedb.connect(tmp_path)
+    table = db.create_table("t", [{"x": 1}])
+    with pytest.raises(NotImplementedError, match="LanceDB Cloud and Enterprise"):
+        table.function_errors()
+
+
 def test_refresh_column_async_returns_job(tmp_path):
     db = lancedb.connect(tmp_path)
     table = db.create_table("computed_job", [{"x": 1}, {"x": 2}])

python/src/lib.rs

@@ -16,8 +16,9 @@ use query::{FTSQuery, HybridQuery, Query, VectorQuery};
 use session::Session;
 use table::{
     AddColumnsResult, AddResult, AlterColumnsResult, DeleteResult, DropColumnsResult, FtsToken,
-    LsmWriteSpec, MergeResult, PyBlobFile, RefreshColumnResult, RefreshMaterializedViewResult,
-    Table, UpdateFieldMetadataResult, UpdateResult,
+    FunctionErrorFragment, FunctionErrorRecord, FunctionErrors, LsmWriteSpec, MergeResult,
+    PyBlobFile, RefreshColumnResult, RefreshMaterializedViewResult, Table,
+    UpdateFieldMetadataResult, UpdateResult,
 };
 
 pub mod arrow;
@@ -84,6 +85,9 @@ pub fn _lancedb(py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<RecordBatchStream>()?;
     m.add_class::<AddColumnsResult>()?;
     m.add_class::<RefreshColumnResult>()?;
+    m.add_class::<FunctionErrors>()?;
+    m.add_class::<FunctionErrorRecord>()?;
+    m.add_class::<FunctionErrorFragment>()?;
     m.add_class::<RefreshMaterializedViewResult>()?;
     m.add_class::<AlterColumnsResult>()?;
     m.add_class::<UpdateFieldMetadataResult>()?;

python/src/table.rs

@@ -573,6 +573,117 @@ impl From<lancedb::table::RefreshColumnResult> for RefreshColumnResult {
     }
 }
 
+/// One row a Function refresh skipped, as the server recorded it.
+#[pyclass(module = "lancedb._lancedb", get_all, from_py_object)]
+#[derive(Clone, Debug)]
+pub struct FunctionErrorRecord {
+    pub job_id: String,
+    pub fragment_id: u64,
+    pub row_offset: Option<u32>,
+    pub column: String,
+    pub function: String,
+    pub function_version: String,
+    pub table_version: u64,
+    pub error_type: String,
+    pub error_message: String,
+    pub created_at_millis: i64,
+}
+
+#[pymethods]
+impl FunctionErrorRecord {
+    pub fn __repr__(&self) -> String {
+        format!(
+            "FunctionErrorRecord(job_id={:?}, fragment_id={}, row_offset={:?}, column={:?}, \
+             error_type={:?}, error_message={:?})",
+            self.job_id,
+            self.fragment_id,
+            self.row_offset,
+            self.column,
+            self.error_type,
+            self.error_message
+        )
+    }
+}
+
+impl From<lancedb::function::FunctionErrorRecord> for FunctionErrorRecord {
+    fn from(record: lancedb::function::FunctionErrorRecord) -> Self {
+        Self {
+            job_id: record.job_id,
+            fragment_id: record.fragment_id,
+            row_offset: record.row_offset,
+            column: record.column,
+            function: record.function,
+            function_version: record.function_version,
+            table_version: record.table_version,
+            error_type: record.error_type,
+            error_message: record.error_message,
+            created_at_millis: record.created_at_millis,
+        }
+    }
+}
+
+/// A fragment whose per-row error detail was capped.
+#[pyclass(module = "lancedb._lancedb", get_all, from_py_object)]
+#[derive(Clone, Debug)]
+pub struct FunctionErrorFragment {
+    pub job_id: String,
+    pub fragment_id: u64,
+    pub rows_skipped: u64,
+    pub rows_recorded: u64,
+}
+
+#[pymethods]
+impl FunctionErrorFragment {
+    pub fn __repr__(&self) -> String {
+        format!(
+            "FunctionErrorFragment(job_id={:?}, fragment_id={}, rows_skipped={}, rows_recorded={})",
+            self.job_id, self.fragment_id, self.rows_skipped, self.rows_recorded
+        )
+    }
+}
+
+impl From<lancedb::function::FunctionErrorFragment> for FunctionErrorFragment {
+    fn from(fragment: lancedb::function::FunctionErrorFragment) -> Self {
+        Self {
+            job_id: fragment.job_id,
+            fragment_id: fragment.fragment_id,
+            rows_skipped: fragment.rows_skipped,
+            rows_recorded: fragment.rows_recorded,
+        }
+    }
+}
+
+/// A table's per-row Function errors.
+#[pyclass(module = "lancedb._lancedb", get_all, from_py_object)]
+#[derive(Clone, Debug)]
+pub struct FunctionErrors {
+    pub records: Vec<FunctionErrorRecord>,
+    pub fragments: Vec<FunctionErrorFragment>,
+    pub truncated: bool,
+}
+
+#[pymethods]
+impl FunctionErrors {
+    pub fn __repr__(&self) -> String {
+        format!(
+            "FunctionErrors(records={}, fragments={}, truncated={})",
+            self.records.len(),
+            self.fragments.len(),
+            self.truncated
+        )
+    }
+}
+
+impl From<lancedb::function::FunctionErrors> for FunctionErrors {
+    fn from(errors: lancedb::function::FunctionErrors) -> Self {
+        Self {
+            records: errors.records.into_iter().map(Into::into).collect(),
+            fragments: errors.fragments.into_iter().map(Into::into).collect(),
+            truncated: errors.truncated,
+        }
+    }
+}
+
 #[pyclass(get_all, from_py_object)]
 #[derive(Clone, Debug)]
 pub struct RefreshMaterializedViewResult {
@@ -1772,6 +1883,25 @@ impl Table {
         })
     }
 
+    #[pyo3(signature = (job_id=None, column=None, limit=None))]
+    pub fn function_errors(
+        self_: PyRef<'_, Self>,
+        job_id: Option<String>,
+        column: Option<String>,
+        limit: Option<usize>,
+    ) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.inner_ref()?.clone();
+        let request = lancedb::function::FunctionErrorsRequest {
+            job_id,
+            column,
+            limit,
+        };
+        future_into_py(self_.py(), async move {
+            let errors = inner.function_errors(request).await.infer_error()?;
+            Ok(FunctionErrors::from(errors))
+        })
+    }
+
     #[pyo3(signature = (full=false, source_version=None))]
     pub fn refresh_materialized_view(
         self_: PyRef<'_, Self>,
@@ -1818,7 +1948,7 @@ impl Table {
             let view = lancedb::MaterializedView::from_table(inner)
                 .await
                 .infer_error()?;
-            serde_json::to_string(view.definition()).map_err(|err| {
+            view.definition().to_json().map_err(|err| {
                 PyRuntimeError::new_err(format!(
                     "failed to serialize materialized-view definition: {err}"
                 ))