feat(remote): add RemoteTable fetch_blobs HTTP client (#3684)

Remote half of the blob read path. #3578 did local Python. This makes
`RemoteTable` hit the server.

- `fetch_blobs(column, row_ids or hits)` → bytes over `POST
/v1/table/{id}/fetch_blobs/`
- `blob_columns()` from the cached schema (describe already has the
metadata, no extra route)
- search then `fetch_blobs` works. row identity rides inside the blob
descriptor so you do not need a public `_rowid`
- `fetch_blob_files` still `NotSupported` on remote. use `fetch_blobs`
for full bytes for now. Range is a follow up

Accepts Binary / LargeBinary / BinaryView on the way back. Empty
`row_ids` short-circuits. Version + branch go in the request body same
as other read calls.

### Example

```python
db = lancedb.connect(uri="db://my-project", api_key=...)
table = db.open_table("clips")

hits = table.search(query_vec).select(["id", "video"]).limit(10).to_arrow()
# hits is just id + video. row ids are stashed on the descriptor
blobs = table.fetch_blobs("video", hits)  # null-aligned, same length as hits
```

Or pass ids yourself:

```python
blobs = table.fetch_blobs("video", [10, 20, 30])
```

### Testing

- `cargo test -p lancedb --features remote --lib`
- `cargo test -p lancedb --features remote --test blob_integration`
- `pytest python/tests/test_remote_db.py -k remote_blob`
- live e2e against a local 0.5.0 remote server (search → fetch, nulls,
nested path, old server gate)

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

python/python/lancedb/_blob.py

@@ -14,14 +14,10 @@ import pyarrow as pa
 from .expr import Expr
 from .schema import blob_v2_column_paths
 from .types import BlobMode, QueryProjection, QueryProjectionSpec
-from .util import get_uri_scheme
 
 if TYPE_CHECKING:
     from _typeshed import WriteableBuffer
 
-    from .remote.table import RemoteTable
-    from .table import AsyncTable, Table
-
 BLOB_MODE_TO_HANDLING = {
     "lazy": "blobs_descriptions",
     "bytes": "all_binary",
@@ -104,22 +100,6 @@ def validate_blob_mode(blob_mode: BlobMode) -> None:
         raise ValueError(f"blob_mode must be one of {modes}, got {blob_mode!r}")
 
 
-def supports_blob_auto_row_id(table: Table | AsyncTable | RemoteTable) -> bool:
-    """Blob auto row-id applies to native tables, not LanceDB Cloud."""
-    from .remote.table import RemoteTable
-
-    if isinstance(table, RemoteTable):
-        return False
-
-    inner = getattr(table, "_inner", None)
-    if inner is not None:
-        uri = inner.database().uri
-        if isinstance(uri, str) and get_uri_scheme(uri) == "db":
-            return False
-
-    return True
-
-
 def projection_includes_blob_column(
     projection: QueryProjection,
     blob_columns: Iterable[str],
@@ -164,16 +144,14 @@ def v2_projection_needs_row_id(
 
 
 def blob_auto_row_id_for_scan(
-    table: Table | AsyncTable | RemoteTable,
     schema: pa.Schema,
     projection: QueryProjection,
     *,
     with_row_id: bool | None,
 ) -> bool:
+    """Auto row-id only applies when the caller said nothing about row ids."""
     if with_row_id is not None:
         return False
-    if not supports_blob_auto_row_id(table):
-        return False
     return v2_projection_needs_row_id(schema, projection, with_row_id=False)
 
 
@@ -186,6 +164,11 @@ def finalize_blob_query_table(
 ) -> pa.Table:
     if user_requested_row_id or not blob_auto_row_id:
         return tbl
+    if "_rowid" not in tbl.column_names:
+        # A backend that ignores the row-id request leaves nothing to stash. Hand
+        # back the projection as-is so fetch_blobs raises the error that names the
+        # ways to supply row ids, rather than failing here about a hidden column.
+        return tbl
     return stash_auto_row_ids(tbl, blob_paths)
 
 

python/python/lancedb/query.py

@@ -52,7 +52,6 @@ from ._blob import (
     finalize_blob_query_table,
     replace_v2_blob_columns_with_bytes,
     replace_v2_blob_columns_with_bytes_sync,
-    supports_blob_auto_row_id,
     validate_blob_mode,
 )
 from .types import BlobMode, QueryProjection
@@ -1277,10 +1276,7 @@ class LanceQueryBuilder(ABC):
         return self._with_row_id is True
 
     def _blob_auto_row_id_enabled(self) -> bool:
-        if not supports_blob_auto_row_id(self._table):
-            return False
         return blob_auto_row_id_for_scan(
-            self._table,
             self._table.schema,
             self._columns,
             with_row_id=self._with_row_id,
@@ -2771,7 +2767,7 @@ class AsyncQueryBase(object):
         )
 
     async def _maybe_add_blob_row_id(self) -> None:
-        if self._table is None or not supports_blob_auto_row_id(self._table):
+        if self._table is None:
             self._blob_auto_row_id = False
             self._blob_paths = ()
             return
@@ -2779,7 +2775,6 @@ class AsyncQueryBase(object):
         req = self._inner.to_query_request()
         schema = await self._table.schema()
         self._blob_auto_row_id = blob_auto_row_id_for_scan(
-            self._table,
             schema,
             req.select,
             with_row_id=self._with_row_id,
@@ -3031,7 +3026,6 @@ class AsyncQueryBase(object):
 
         schema = await self._table.schema()
         blob_auto_row_id = blob_auto_row_id_for_scan(
-            self._table,
             schema,
             query.columns,
             with_row_id=self._with_row_id,
@@ -3875,10 +3869,9 @@ class AsyncHybridQuery(AsyncStandardQuery, AsyncVectorQueryBase):
         req = fts_query._inner.to_query_request()
         blob_auto_row_id = False
         blob_paths: tuple[str, ...] = ()
-        if self._table is not None and supports_blob_auto_row_id(self._table):
+        if self._table is not None:
             schema = await self._table.schema()
             blob_auto_row_id = blob_auto_row_id_for_scan(
-                self._table,
                 schema,
                 req.select,
                 with_row_id=self._with_row_id,

python/python/lancedb/remote/table.py

@@ -20,6 +20,7 @@ from typing import (
 import warnings
 
 from lancedb import __version__
+from lancedb._blob import BlobFile
 
 from lancedb._lancedb import (
     AddColumnsResult,
@@ -1037,22 +1038,22 @@ class RemoteTable(Table):
         )
 
     def blob_columns(self) -> list[str]:
-        raise NotImplementedError(
-            "blob_columns() is not yet supported on the LanceDB Cloud"
-        )
+        return LOOP.run(self._table.blob_columns())
 
-    def fetch_blobs(self, column: str, row_ids) -> pa.LargeBinaryArray:
-        raise NotImplementedError("fetch_blobs() is not supported on LanceDB Cloud")
+    def fetch_blobs(
+        self, column: str, row_ids: Union[list[int], pa.Table]
+    ) -> pa.LargeBinaryArray:
+        return LOOP.run(self._table.fetch_blobs(column, row_ids))
 
     def fetch_blob_ranges(self, column: str, requests) -> pa.LargeBinaryArray:
         raise NotImplementedError(
             "fetch_blob_ranges() is not supported on LanceDB Cloud"
         )
 
-    def fetch_blob_files(self, column: str, row_ids):
-        raise NotImplementedError(
-            "fetch_blob_files() is not supported on LanceDB Cloud"
-        )
+    def fetch_blob_files(
+        self, column: str, row_ids: Union[list[int], pa.Table]
+    ) -> "list[Optional[BlobFile]]":
+        return LOOP.run(self._table.fetch_blob_files(column, row_ids))
 
     def head(self, n=5) -> pa.Table:
         """

python/python/lancedb/table.py

@@ -1574,8 +1574,10 @@ class Table(ABC):
         """Open lazy, seekable :class:`~lancedb._blob.BlobFile` handles.
 
         Prefer this over :meth:`fetch_blobs` for large payloads. ``row_ids`` is
-        a ``list[int]`` or query ``pyarrow.Table`` with ``_rowid`` (or stashed
-        row-id metadata). Null rows are ``None``. Local tables only.
+        a ``list[int]`` or a query ``pyarrow.Table`` carrying row identity via
+        ``_rowid`` or a ``_lance_row_id`` field on the blob descriptor. Null
+        rows are ``None``. Unsupported on LanceDB Cloud, where
+        :meth:`fetch_blobs` returns full bytes instead.
         """
 
     @abstractmethod

python/python/tests/test_remote_db.py

@@ -1020,7 +1020,7 @@ def query_test_table(query_handler, *, server_version=Version("0.1.0")):
             request.send_header("Content-Type", "application/json")
             request.send_header("phalanx-version", str(server_version))
             request.end_headers()
-            request.wfile.write(b"{}")
+            request.wfile.write(b'{"version": 1, "schema": {"fields": []}}')
         elif request.path == "/v1/table/test/query/":
             content_len = int(request.headers.get("Content-Length"))
             body = request.rfile.read(content_len)
@@ -1858,3 +1858,183 @@ def test_inherited_remote_table_reopens_after_fork():
     finally:
         server.shutdown()
         server_thread.join()
+
+
+BLOB_DESCRIBE_RESPONSE = {
+    "table": "test",
+    "version": 1,
+    "schema": {
+        "fields": [
+            {"name": "id", "type": {"type": "int64"}, "nullable": False},
+            {
+                "name": "image",
+                "type": {
+                    "type": "struct",
+                    "fields": [
+                        {
+                            "name": "data",
+                            "type": {"type": "large_binary"},
+                            "nullable": True,
+                        },
+                        {"name": "uri", "type": {"type": "string"}, "nullable": True},
+                    ],
+                },
+                "nullable": True,
+                "metadata": {
+                    "ARROW:extension:name": "lance.blob.v2",
+                    "ARROW:extension:metadata": "",
+                },
+            },
+        ]
+    },
+}
+
+
+def blob_query_response_table():
+    image_field = pa.field(
+        "image",
+        pa.struct(
+            [
+                pa.field("kind", pa.uint8(), nullable=False),
+                pa.field("position", pa.uint64(), nullable=False),
+                pa.field("size", pa.uint64(), nullable=False),
+                pa.field("blob_id", pa.uint32(), nullable=False),
+                pa.field("blob_uri", pa.string(), nullable=False),
+            ]
+        ),
+        metadata={"lance-encoding:blob": "true"},
+    )
+    images = pa.StructArray.from_arrays(
+        [
+            pa.array([1, 0, 0], type=pa.uint8()),
+            pa.array([0, 0, 0], type=pa.uint64()),
+            pa.array([5, 0, 5], type=pa.uint64()),
+            pa.array([1, 0, 2], type=pa.uint32()),
+            pa.array(["", "", ""], type=pa.string()),
+        ],
+        fields=image_field.type,
+        mask=pa.array([False, True, False]),
+    )
+    return pa.Table.from_arrays(
+        [
+            pa.array([1, 2, 3], type=pa.int64()),
+            images,
+            pa.array([10, 20, 30], type=pa.uint64()),
+        ],
+        schema=pa.schema(
+            [
+                pa.field("id", pa.int64(), nullable=False),
+                image_field,
+                pa.field("_rowid", pa.uint64()),
+            ]
+        ),
+    )
+
+
+@contextlib.contextmanager
+def blob_remote_table(*, server_version=Version("0.5.0")):
+    def handler(request):
+        if request.path == "/v1/table/test/describe/":
+            request.send_response(200)
+            request.send_header("Content-Type", "application/json")
+            request.send_header("phalanx-version", str(server_version))
+            request.end_headers()
+            request.wfile.write(json.dumps(BLOB_DESCRIBE_RESPONSE).encode())
+        elif request.path == "/v1/table/test/query/":
+            content_len = int(request.headers.get("Content-Length", 0))
+            body = json.loads(request.rfile.read(content_len))
+            assert body["columns"] == ["id", "image"]
+            assert body["with_row_id"] is True
+            response_table = blob_query_response_table()
+            request.send_response(200)
+            request.send_header("Content-Type", "application/vnd.apache.arrow.file")
+            request.end_headers()
+            with pa.ipc.new_file(request.wfile, response_table.schema) as writer:
+                writer.write_table(response_table)
+        elif request.path == "/v1/table/test/fetch_blobs/":
+            content_len = int(request.headers.get("Content-Length", 0))
+            body = json.loads(request.rfile.read(content_len))
+            assert body["column"] == "image"
+            assert body["row_ids"] == [10, 20, 30]
+            response_table = pa.table(
+                {"image": pa.array([b"alpha", None, b"gamma"], type=pa.large_binary())}
+            )
+            request.send_response(200)
+            request.send_header("Content-Type", "application/vnd.apache.arrow.stream")
+            request.end_headers()
+            with pa.ipc.new_stream(request.wfile, response_table.schema) as writer:
+                writer.write_table(response_table)
+        else:
+            request.send_response(404)
+            request.end_headers()
+
+    with mock_lancedb_connection(handler) as db:
+        yield db.open_table("test")
+
+
+def test_remote_blob_columns_and_fetch():
+    with blob_remote_table() as table:
+        assert table.blob_columns() == ["image"]
+        blobs = table.fetch_blobs("image", [10, 20, 30])
+        assert blobs.to_pylist() == [b"alpha", None, b"gamma"]
+        with pytest.raises(NotImplementedError, match="Use fetch_blobs for full bytes"):
+            table.fetch_blob_files("image", [10, 20, 30])
+
+
+def test_remote_blob_fetch_accepts_query_table():
+    hits = pa.table({"_rowid": pa.array([10, 20, 30], type=pa.uint64())})
+
+    with blob_remote_table() as table:
+        blobs = table.fetch_blobs("image", hits)
+
+    assert blobs.to_pylist() == [b"alpha", None, b"gamma"]
+
+
+def test_remote_blob_query_stashes_row_ids_for_fetch():
+    with blob_remote_table() as table:
+        hits = table.search().select(["id", "image"]).limit(3).to_arrow()
+        assert "_rowid" not in hits.column_names
+        assert "_lance_row_id" in hits.schema.field("image").type.names
+        blobs = table.fetch_blobs("image", hits)
+
+    assert blobs.to_pylist() == [b"alpha", None, b"gamma"]
+
+
+def test_remote_blob_query_survives_a_server_that_ignores_the_row_id_request():
+    def handler(request):
+        if request.path == "/v1/table/test/describe/":
+            request.send_response(200)
+            request.send_header("Content-Type", "application/json")
+            request.send_header("phalanx-version", "0.5.0")
+            request.end_headers()
+            request.wfile.write(json.dumps(BLOB_DESCRIBE_RESPONSE).encode())
+        elif request.path == "/v1/table/test/query/":
+            content_len = int(request.headers.get("Content-Length", 0))
+            assert json.loads(request.rfile.read(content_len))["with_row_id"] is True
+            response_table = blob_query_response_table().drop_columns(["_rowid"])
+            request.send_response(200)
+            request.send_header("Content-Type", "application/vnd.apache.arrow.file")
+            request.end_headers()
+            with pa.ipc.new_file(request.wfile, response_table.schema) as writer:
+                writer.write_table(response_table)
+        else:
+            request.send_response(404)
+            request.end_headers()
+
+    with mock_lancedb_connection(handler) as db:
+        table = db.open_table("test")
+        hits = table.search().select(["id", "image"]).limit(3).to_arrow()
+
+        assert hits.column_names == ["id", "image"]
+        assert "_lance_row_id" not in hits.schema.field("image").type.names
+        with pytest.raises(ValueError, match="pass a list of row ids"):
+            table.fetch_blobs("image", hits)
+
+
+def test_remote_blob_byte_apis_not_supported_on_old_server():
+    with blob_remote_table(server_version=Version("0.1.0")) as table:
+        assert table.blob_columns() == ["image"]
+        with pytest.raises(NotImplementedError, match="not supported"):
+            table.fetch_blobs("image", [1])
+        with pytest.raises(NotImplementedError, match="not supported"):
+            table.fetch_blob_files("image", [1])