feat: add asynchronous remote SQL queries (#4070)

## Summary

Add SQL execution to remote LanceDB connections. On the standard
synchronous connection, `execute_query` waits for the initial result
stream and returns its Arrow reader. `execute_query_async` is called
without Python `await` and immediately returns a query handle for status
inspection, streaming, or cancellation. Local databases report that SQL
is not supported.

The transport and query lifecycle live in Rust. Python exposes
native-backed synchronous and asynchronous connection methods and query
wrappers; it does not use PyArrow's Flight client.

## User experience

The standard synchronous connection supports both direct reads and
background query execution:

```python
db = lancedb.connect(
    "db://analytics",
    api_key="ldb_...",
    sql_host_override="grpc+tls://sql.example.com:10026",
)

# Direct execution waits only until the initial result stream is available.
# Later batches continue streaming as the query progresses.
reader = db.execute_query(
    "SELECT * FROM events",
    default_namespace_path=["production"],
)
for batch in reader:
    print(batch.num_rows)

# Background execution returns a query handle immediately. Despite the
# `_async` suffix, no Python `await` is needed on a synchronous connection.
query = db.execute_query_async("SELECT * FROM events")
print(query.id)

description = db.describe_query(query.id)
print(description.status)
print(description.progress)
print(description.expires_at)

# Start reading as soon as the service advertises partial results. The reader
# continues polling and yields newly available record batches until the query
# and all result endpoints are complete.
reader = query.reader()
for batch in reader:
    print(batch.num_rows)

# Or cancel a different still-running query. Its status becomes "cancelling"
# while the server is still working, then "cancelled" once confirmed.
cancelled_query = db.execute_query_async("SELECT * FROM large_events")
cancelled_query.cancel()
```

The less commonly used asynchronous connection exposes the same
operations as coroutines:

```python
async_db = await lancedb.connect_async(
    "db://analytics",
    api_key="ldb_...",
    sql_host_override="grpc+tls://sql.example.com:10026",
)
query = await async_db.execute_query_async("SELECT * FROM events")
async for batch in await query.reader():
    print(batch.num_rows)
```

The UUIDv7 query id is scoped to the connection that submitted it. The
connection retains lightweight shared query state used by
`query.describe()` and `db.describe_query(query.id)`; the id does not
encode SQL or a Flight continuation token and is not a cross-connection
resume token. Abandoned state has bounded retention, and terminal state
remains available briefly.

Unqualified table names use the connected database and the `public`
namespace by default. `default_namespace_path` accepts a list such as
`["production", "events"]`. SQL can still use qualified names to
reference other databases and namespaces available to the deployment.

## Design

- Uses Arrow Flight `PollFlightInfo` for submission and long polling,
`DoGet` for results, and `CancelFlightInfo` for cancellation. Each
`PollInfo.info` is treated as the cumulative set of currently available
endpoints, so advertised tickets are consumed once and batches can be
delivered before execution is complete.
- Serializes result completion and cancellation into one lifecycle. A
server-accepted request reports `cancelling` and wakes blocked
status/result work; a later retry can confirm `cancelled`. Result
retrieval is rejected after cancellation is accepted, while cancellation
after a result was already delivered is a no-op.
- Assigns a time-ordered UUIDv7 connection-scoped query id and retains
only shared evolving lifecycle state, keeping SQL, Flight continuation
tokens, and Arrow result data out of public ids and the registry.
- Leaves admission control to the server while honoring server
expiration and a local fallback retention window for abandoned entries.
- Retains terminal ids for five minutes so they remain available for
connection-level description.
- Keeps one lazily initialized SQL client on each remote database
connection and attaches fresh authentication, routing, namespace, and
request metadata to every operation.
- Applies the configured overall timeout to each execution, description,
reader, and cancellation operation. A result reader carries one absolute
deadline from `reader()` through the end of streaming; connect and read
timeouts continue to bound their individual phases.
- Returns a bounded, backpressured, single-consumer Arrow stream rather
than collecting the full result in memory. Dropping the reader stops
downloading but does not implicitly cancel the server query.
- Preserves typed schemas for empty result sets through the stream
schema.
- Accepts Flight result messages up to 1 GiB so a valid row containing a
large blob, string, or vector is not rejected by tonic's 4 MiB default
receive limit.
- Supports the Python client first while keeping the authoritative
implementation in the Rust core.

python/Cargo.toml

@@ -28,7 +28,7 @@ env_logger.workspace = true
 log.workspace = true
 # Maturin enables extension-module mode for Python builds. Keeping it out of
 # Cargo features lets Rust unit tests link against libpython.
-pyo3 = { version = "0.28", features = ["abi3-py310", "chrono"] }
+pyo3 = { version = "0.28", features = ["abi3-py310", "chrono", "uuid"] }
 chrono.workspace = true
 pyo3-async-runtimes = { version = "0.28", features = [
     "attributes",
@@ -40,6 +40,7 @@ serde.workspace = true
 serde_json.workspace = true
 snafu.workspace = true
 tokio.workspace = true
+uuid.workspace = true
 libc = "0.2"
 
 [build-dependencies]

python/pyproject.toml

@@ -139,6 +139,7 @@ include = [
     "python/lancedb/exceptions.py",
     "python/lancedb/background_loop.py",
     "python/lancedb/schema.py",
+    "python/lancedb/sql.py",
     "python/lancedb/remote/__init__.py",
     "python/lancedb/remote/errors.py",
     "python/lancedb/embeddings/__init__.py",

python/python/lancedb/__init__.py

@@ -22,6 +22,9 @@ from .remote.db import RemoteDBConnection
 from .expr import Expr, col, lit, func
 from .schema import blob, vector
 from .job import AsyncJob, Job
+from .sql import AsyncQuery as AsyncSqlQuery
+from .sql import Query as SqlQuery
+from .sql import QueryDescription
 from .functions import (
     FunctionArtifactRequest as FunctionArtifactRequest,
     FunctionApplication as FunctionApplication,
@@ -101,6 +104,7 @@ def connect(
     api_key: Optional[str] = None,
     region: str = "us-east-1",
     host_override: Optional[str] = None,
+    sql_host_override: Optional[str] = None,
     read_consistency_interval: Optional[timedelta] = None,
     request_thread_pool: Optional[Union[int, ThreadPoolExecutor]] = None,
     client_config: Union[ClientConfig, Dict[str, Any], None] = None,
@@ -129,6 +133,9 @@ def connect(
         The region to use for LanceDB Cloud.
     host_override: str, optional
         The override url for LanceDB Cloud.
+    sql_host_override: str, optional
+        The remote SQL service endpoint override. The client connects lazily when SQL
+        is first executed and retains that connection.
     read_consistency_interval: timedelta, default None
         The interval at which to check for updates to the table from other
         processes. If None, then consistency is not checked. For performance
@@ -270,6 +277,7 @@ def connect(
             api_key,
             region,
             host_override,
+            sql_host_override=sql_host_override,
             # TODO: remove this (deprecation warning downstream)
             request_thread_pool=request_thread_pool,
             client_config=client_config,
@@ -412,6 +420,7 @@ def deserialize_conn(
             parsed["api_key"],
             parsed.get("region", "us-east-1"),
             host_override=parsed.get("host_override"),
+            sql_host_override=parsed.get("sql_host_override"),
             client_config=parsed.get("client_config"),
             storage_options=storage_options,
         )
@@ -425,6 +434,7 @@ async def connect_async(
     api_key: Optional[str] = None,
     region: str = "us-east-1",
     host_override: Optional[str] = None,
+    sql_host_override: Optional[str] = None,
     read_consistency_interval: Optional[timedelta] = None,
     client_config: Optional[Union[ClientConfig, Dict[str, Any]]] = None,
     storage_options: Optional[Dict[str, str]] = None,
@@ -447,6 +457,9 @@ async def connect_async(
         The region to use for LanceDB Cloud.
     host_override: str, optional
         The override url for LanceDB Cloud.
+    sql_host_override: str, optional
+        The remote SQL service endpoint override. The client connects lazily when SQL
+        is first executed and retains that connection.
     read_consistency_interval: timedelta, default None
         The interval at which to check for updates to the table from other
         processes. If None, then consistency is not checked. For performance
@@ -534,6 +547,7 @@ async def connect_async(
             api_key,
             region,
             host_override,
+            sql_host_override,
             read_consistency_interval_secs,
             client_config,
             storage_options,
@@ -556,6 +570,7 @@ __all__ = [
     "connect_namespace_async",
     "AsyncConnection",
     "AsyncJob",
+    "AsyncSqlQuery",
     "AsyncLanceNamespaceDBConnection",
     "AsyncTable",
     "FtsToken",
@@ -570,6 +585,8 @@ __all__ = [
     "vector",
     "DBConnection",
     "Job",
+    "QueryDescription",
+    "SqlQuery",
     "LanceDBConnection",
     "LanceNamespaceDBConnection",
     "LsmWriteSpec",

python/python/lancedb/_lancedb.pyi

@@ -1,6 +1,7 @@
 from datetime import date, datetime, timedelta
 from decimal import Decimal
 from typing import Dict, List, Optional, Tuple, Any, TypedDict, Union, Literal
+from uuid import UUID
 
 import pyarrow as pa
 
@@ -158,6 +159,13 @@ class Connection(object):
     async def job_history(
         self, job_id: Optional[str] = None
     ) -> List[pa.RecordBatch]: ...
+    async def execute_query_async(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> SqlQuery: ...
+    async def describe_query(self, query_id: UUID) -> QueryDescription: ...
     async def create_table(
         self,
         name: str,
@@ -274,6 +282,23 @@ class JobDescription:
     @property
     def failure(self) -> Optional[JobFailureInfo]: ...
 
+class SqlQuery:
+    @property
+    def id(self) -> UUID: ...
+    async def describe(self) -> QueryDescription: ...
+    async def reader(self) -> RecordBatchStream: ...
+    async def cancel(self) -> None: ...
+
+class QueryDescription:
+    @property
+    def id(self) -> UUID: ...
+    @property
+    def status(self) -> str: ...
+    @property
+    def progress(self) -> Optional[float]: ...
+    @property
+    def expires_at(self) -> Optional[datetime]: ...
+
 class Table:
     def name(self) -> str: ...
     def __repr__(self) -> str: ...
@@ -452,6 +477,7 @@ async def connect(
     api_key: Optional[str],
     region: Optional[str],
     host_override: Optional[str],
+    sql_host_override: Optional[str],
     read_consistency_interval: Optional[float],
     client_config: Optional[Union[ClientConfig, Dict[str, Any]]],
     storage_options: Optional[Dict[str, str]],

python/python/lancedb/db.py

@@ -19,6 +19,7 @@ from typing import (
     Optional,
     Union,
 )
+from uuid import UUID
 
 if sys.version_info >= (3, 12):
     from typing import override
@@ -47,6 +48,9 @@ from . import __version__
 from ._lancedb import connect as lancedb_connect  # type: ignore
 from .functions import FunctionVersion, UdfDefinition
 from .job import AsyncJob, Job, _typed_job
+from .sql import AsyncQuery as AsyncSqlQuery
+from .sql import Query as SqlQuery
+from .sql import QueryDescription
 from .materialized_view import (
     AsyncMaterializedView,
     MaterializedView,
@@ -68,6 +72,7 @@ import deprecation
 
 if TYPE_CHECKING:
     import pyarrow as pa
+    from .arrow import AsyncRecordBatchReader
     from .pydantic import LanceModel
 
     from ._lancedb import Connection as LanceDbConnection
@@ -780,6 +785,39 @@ class DBConnection(EnforceOverrides):
             "job_history is not supported for this connection type"
         )
 
+    def execute_query(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> pa.RecordBatchReader:
+        """Execute SQL and return a blocking Arrow reader.
+
+        This submits through :meth:`execute_query_async` and waits until the
+        initial result stream is readable. It does not wait for the full query
+        to finish.
+        """
+        return self.execute_query_async(
+            query,
+            default_namespace_path=default_namespace_path,
+        ).reader()
+
+    def execute_query_async(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> SqlQuery:
+        """Start executing SQL and return its query handle.
+
+        Local connections do not support SQL.
+        """
+        raise NotImplementedError("SQL is not supported for this connection type")
+
+    def describe_query(self, query_id: UUID) -> QueryDescription:
+        """Describe a submitted SQL query by its connection-scoped id."""
+        raise NotImplementedError("SQL is not supported for this connection type")
+
 
 class LanceDBConnection(DBConnection):
     """
@@ -875,6 +913,7 @@ class LanceDBConnection(DBConnection):
                 None,
                 None,
                 None,
+                None,
                 read_consistency_interval_secs,
                 None,
                 storage_options,
@@ -2321,6 +2360,47 @@ class AsyncConnection(object):
         """
         return await self._inner.job_history(job_id)
 
+    async def execute_query(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> AsyncRecordBatchReader:
+        """Execute SQL and return an asynchronous Arrow reader.
+
+        This submits through :meth:`execute_query_async` and waits until the
+        initial result stream is readable. It does not wait for the full query
+        to finish.
+        """
+        submitted = await self.execute_query_async(
+            query,
+            default_namespace_path=default_namespace_path,
+        )
+        return await submitted.reader()
+
+    async def execute_query_async(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> AsyncSqlQuery:
+        """Start executing SQL and return its query handle.
+
+        The database from ``connect_async`` is used for unqualified database
+        references. The namespace defaults to ``["public"]``. Local
+        connections raise ``NotImplementedError``.
+        """
+        return AsyncSqlQuery(
+            await self._inner.execute_query_async(
+                query,
+                default_namespace_path=default_namespace_path,
+            )
+        )
+
+    async def describe_query(self, query_id: UUID) -> QueryDescription:
+        """Describe a submitted SQL query by its connection-scoped id."""
+        return await self._inner.describe_query(query_id)
+
     async def namespace_client(self) -> LanceNamespace:
         """Get the equivalent namespace client for this connection.
 

python/python/lancedb/namespace.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 
 import sys
 from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Optional, Union
+from uuid import UUID
 
 if sys.version_info >= (3, 12):
     from typing import override
@@ -48,8 +49,11 @@ from lancedb._lancedb import (
     connect_namespace_client as _connect_namespace_client,
 )
 from lancedb.background_loop import LOOP
+from lancedb.arrow import AsyncRecordBatchReader
 from lancedb.db import AsyncConnection, DBConnection
 from lancedb.job import AsyncJob, Job
+from lancedb.sql import AsyncQuery as AsyncSqlQuery
+from lancedb.sql import QueryDescription
 from lance_namespace import (
     LanceNamespace,
     connect as namespace_connect,
@@ -1447,6 +1451,37 @@ class AsyncLanceNamespaceDBConnection:
             namespace_path=namespace_path, page_token=page_token, limit=limit
         )
 
+    async def execute_query(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> AsyncRecordBatchReader:
+        """Execute SQL when supported by the underlying connection."""
+        return await self._inner.execute_query(
+            query,
+            default_namespace_path=default_namespace_path,
+        )
+
+    async def execute_query_async(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> AsyncSqlQuery:
+        """Start executing SQL when supported by the underlying connection.
+
+        Namespace-backed local connections do not support SQL.
+        """
+        return await self._inner.execute_query_async(
+            query,
+            default_namespace_path=default_namespace_path,
+        )
+
+    async def describe_query(self, query_id: UUID) -> QueryDescription:
+        """Describe a submitted SQL query when supported."""
+        return await self._inner.describe_query(query_id)
+
     async def namespace_client(self) -> LanceNamespace:
         """Get the namespace client for this connection.
 

python/python/lancedb/remote/db.py

@@ -9,6 +9,7 @@ from concurrent.futures import ThreadPoolExecutor
 import sys
 from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Optional, Union
 from urllib.parse import urlparse
+from uuid import UUID
 import warnings
 
 if sys.version_info >= (3, 12):
@@ -25,6 +26,8 @@ from ..common import DATA
 from ..db import DBConnection, LOOP
 from ..functions import FunctionVersion, UdfDefinition
 from ..job import AsyncJob, Job
+from ..sql import Query as SqlQuery
+from ..sql import QueryDescription
 from ..materialized_view import MaterializedView, SelectArg
 
 if TYPE_CHECKING:
@@ -116,6 +119,7 @@ class RemoteDBConnection(DBConnection):
         read_timeout: Optional[float] = None,
         storage_options: Optional[Dict[str, str]] = None,
         read_consistency_interval: Optional[timedelta] = None,
+        sql_host_override: Optional[str] = None,
     ):
         """Connect to a remote LanceDB database."""
         if isinstance(client_config, dict):
@@ -161,6 +165,7 @@ class RemoteDBConnection(DBConnection):
         self.api_key = api_key
         self.region = region
         self.host_override = host_override
+        self.sql_host_override = sql_host_override
         self.storage_options = storage_options
         self.db_name = parsed.netloc
 
@@ -175,6 +180,7 @@ class RemoteDBConnection(DBConnection):
                 api_key=api_key,
                 region=region,
                 host_override=host_override,
+                sql_host_override=sql_host_override,
                 client_config=client_config,
                 storage_options=storage_options,
                 read_consistency_interval=read_consistency_interval,
@@ -193,6 +199,7 @@ class RemoteDBConnection(DBConnection):
                 "api_key": self.api_key,
                 "region": self.region,
                 "host_override": self.host_override,
+                "sql_host_override": self.sql_host_override,
                 "client_config": _client_config_to_dict(self.client_config),
                 "storage_options": self.storage_options,
             }
@@ -788,6 +795,37 @@ class RemoteDBConnection(DBConnection):
         """
         return LOOP.run(self._conn.job_history(job_id))
 
+    @override
+    def execute_query_async(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> SqlQuery:
+        """Start executing SQL through this remote connection.
+
+        Unqualified tables use this connection's database and the
+        ``["public"]`` namespace by default. Fully qualified table names may
+        reference other databases available to the same deployment.
+        """
+        return SqlQuery(
+            LOOP.run(
+                self._conn.execute_query_async(
+                    query,
+                    default_namespace_path=default_namespace_path,
+                )
+            )
+        )
+
+    @override
+    def describe_query(self, query_id: UUID) -> QueryDescription:
+        """Describe a submitted SQL query by its connection-scoped id."""
+        return LOOP.run(
+            self._conn.describe_query(
+                query_id,
+            )
+        )
+
     @override
     def namespace_client(self) -> LanceNamespace:
         """Get the equivalent namespace client for this connection.

python/python/lancedb/remote/header.py

@@ -177,4 +177,7 @@ class OAuthProvider(HeaderProvider):
         if not self._current_token:
             raise RuntimeError("Failed to obtain OAuth token")
 
-        return {"Authorization": f"Bearer {self._current_token}"}
+        return {
+            "Authorization": f"Bearer {self._current_token}",
+            "x-lancedb-credential-type": "oidc",
+        }

python/python/lancedb/sql.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+"""Handles to SQL queries running on a remote database."""
+
+from uuid import UUID
+
+import pyarrow as pa
+
+from lancedb.background_loop import LOOP
+
+from . import _lancedb
+from .arrow import AsyncRecordBatchReader
+
+QueryDescription = _lancedb.QueryDescription
+
+
+class AsyncQuery:
+    """A handle to a submitted SQL query on an asynchronous connection."""
+
+    def __init__(self, inner: "_lancedb.SqlQuery"):
+        self._inner = inner
+
+    @property
+    def id(self) -> UUID:
+        """The stable identifier scoped to the connection that submitted it."""
+        return self._inner.id
+
+    async def describe(self) -> QueryDescription:
+        """Get a point-in-time description of the query."""
+        return await self._inner.describe()
+
+    async def reader(self) -> AsyncRecordBatchReader:
+        """Wait for the initial result stream and return its Arrow reader.
+
+        Results are single-consumer. Calling this method more than once on the
+        same query raises an error. Later batches are streamed as they become
+        available without waiting for the full query to finish.
+        """
+        return AsyncRecordBatchReader(await self._inner.reader())
+
+    async def cancel(self) -> None:
+        """Request cancellation of the query."""
+        await self._inner.cancel()
+
+
+class Query:
+    """Synchronous counterpart of :class:`AsyncQuery`."""
+
+    def __init__(self, inner: AsyncQuery):
+        self._inner = inner
+
+    @property
+    def id(self) -> UUID:
+        """The stable identifier scoped to the connection that submitted it."""
+        return self._inner.id
+
+    def describe(self) -> QueryDescription:
+        """Get a point-in-time description of the query."""
+        return LOOP.run(self._inner.describe())
+
+    def reader(self) -> pa.RecordBatchReader:
+        """Wait for the initial result stream and return a blocking reader.
+
+        Results are single-consumer. Calling this method more than once on the
+        same query raises an error. Later batches block only until they become
+        available, without waiting for the full query to finish.
+        """
+        reader = LOOP.run(self._inner.reader())
+
+        def next_batch():
+            try:
+                return LOOP.run(reader.__anext__())
+            except StopAsyncIteration:
+                return None
+
+        def batches():
+            while (batch := next_batch()) is not None:
+                yield batch
+
+        return pa.RecordBatchReader.from_batches(reader.schema, batches())
+
+    def cancel(self) -> None:
+        """Request cancellation of the query."""
+        LOOP.run(self._inner.cancel())
+
+
+__all__ = ["AsyncQuery", "Query", "QueryDescription"]

python/python/tests/test_header_provider.py

@@ -54,7 +54,10 @@ class TestOAuthProvider:
         provider = OAuthProvider(fetcher)
         headers = provider.get_headers()
 
-        assert headers == {"Authorization": "Bearer token123"}
+        assert headers == {
+            "Authorization": "Bearer token123",
+            "x-lancedb-credential-type": "oidc",
+        }
         assert provider._current_token == "token123"
         assert provider._token_expires_at is not None
 
@@ -73,14 +76,20 @@ class TestOAuthProvider:
 
         # First call
         headers1 = provider.get_headers()
-        assert headers1 == {"Authorization": "Bearer token1"}
+        assert headers1 == {
+            "Authorization": "Bearer token1",
+            "x-lancedb-credential-type": "oidc",
+        }
 
         # Wait for token to expire
         time.sleep(1.1)
 
         # Second call should refresh
         headers2 = provider.get_headers()
-        assert headers2 == {"Authorization": "Bearer token2"}
+        assert headers2 == {
+            "Authorization": "Bearer token2",
+            "x-lancedb-credential-type": "oidc",
+        }
         assert call_count == 2
 
     def test_no_expiry_info(self):
@@ -92,12 +101,18 @@ class TestOAuthProvider:
         provider = OAuthProvider(fetcher)
         headers = provider.get_headers()
 
-        assert headers == {"Authorization": "Bearer permanent_token"}
+        assert headers == {
+            "Authorization": "Bearer permanent_token",
+            "x-lancedb-credential-type": "oidc",
+        }
         assert provider._token_expires_at is None
 
         # Should not refresh on second call
         headers2 = provider.get_headers()
-        assert headers2 == {"Authorization": "Bearer permanent_token"}
+        assert headers2 == {
+            "Authorization": "Bearer permanent_token",
+            "x-lancedb-credential-type": "oidc",
+        }
 
     def test_missing_access_token(self):
         """Test error handling when access_token is missing."""
@@ -121,7 +136,10 @@ class TestOAuthProvider:
         provider = OAuthProvider(fetcher)
         headers = provider.get_headers()
 
-        assert headers == {"Authorization": "Bearer sync_token"}
+        assert headers == {
+            "Authorization": "Bearer sync_token",
+            "x-lancedb-credential-type": "oidc",
+        }
 
 
 class TestClientConfigIntegration:

python/python/tests/test_sql.py

@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+from uuid import UUID
+
+import pytest
+import pyarrow as pa
+
+import lancedb
+from lancedb import _lancedb
+from lancedb.arrow import AsyncRecordBatchReader
+from lancedb.db import AsyncConnection
+from lancedb.remote.db import RemoteDBConnection
+from lancedb.sql import AsyncQuery, Query
+
+NIL_QUERY_ID = UUID(int=0)
+
+
+class FakeNativeQuery:
+    id = UUID("0198f1b2-c3d4-7e5f-8123-456789abcdef")
+
+    async def reader(self):
+        return pa.table({"value": [1, 2]})
+
+
+class FakeNativeConnection:
+    async def execute_query_async(self, query, *, default_namespace_path=None):
+        return FakeNativeQuery()
+
+
+class FakeAsyncConnection:
+    async def execute_query_async(self, query, *, default_namespace_path=None):
+        return AsyncQuery(FakeNativeQuery())
+
+
+def remote_connection(sql_host_override=None):
+    return lancedb.connect(
+        "db://analytics",
+        api_key="test-key",
+        host_override="http://localhost:10024",
+        sql_host_override=sql_host_override,
+    )
+
+
+def test_sql_is_connection_scoped():
+    assert hasattr(lancedb, "sql")
+    assert not callable(lancedb.sql)
+    assert not hasattr(_lancedb, "sql")
+    assert not hasattr(remote_connection(), "sql")
+    assert hasattr(remote_connection(), "execute_query")
+    assert hasattr(remote_connection(), "execute_query_async")
+    assert hasattr(remote_connection(), "describe_query")
+
+
+def test_query_id_is_uuid():
+    query = AsyncQuery(FakeNativeQuery())
+    assert isinstance(query.id, UUID)
+    assert Query(query).id == query.id
+
+
+def test_connection_serializes_sql_host_override():
+    endpoint = "grpc+tls://sql.example.com:10026"
+    restored = lancedb.deserialize_conn(
+        remote_connection(sql_host_override=endpoint).serialize()
+    )
+    assert restored.sql_host_override == endpoint
+
+
+@pytest.mark.asyncio
+async def test_async_sql_reader_is_record_batch_stream():
+    reader = await AsyncQuery(FakeNativeQuery()).reader()
+    assert isinstance(reader, AsyncRecordBatchReader)
+    assert (await reader.read_all())[0].column(0).to_pylist() == [1, 2]
+
+
+def test_sync_sql_reader_is_record_batch_reader():
+    reader = Query(AsyncQuery(FakeNativeQuery())).reader()
+    assert isinstance(reader, pa.RecordBatchReader)
+    assert reader.read_all().column(0).to_pylist() == [1, 2]
+
+
+def test_execute_query_returns_blocking_reader():
+    connection = RemoteDBConnection.__new__(RemoteDBConnection)
+    connection._conn = FakeAsyncConnection()
+    reader = connection.execute_query("SELECT 1")
+    assert isinstance(reader, pa.RecordBatchReader)
+    assert reader.read_all().column(0).to_pylist() == [1, 2]
+
+
+@pytest.mark.asyncio
+async def test_async_execute_query_returns_async_reader():
+    connection = AsyncConnection(FakeNativeConnection())
+    reader = await connection.execute_query("SELECT 1")
+    assert isinstance(reader, AsyncRecordBatchReader)
+    assert (await reader.read_all())[0].column(0).to_pylist() == [1, 2]
+
+
+def test_local_connection_rejects_sql(tmp_path):
+    connection = lancedb.connect(tmp_path)
+    with pytest.raises(NotImplementedError, match="SQL"):
+        connection.execute_query("SELECT 1")
+    with pytest.raises(NotImplementedError, match="SQL"):
+        connection.execute_query_async("SELECT 1")
+    with pytest.raises(NotImplementedError, match="SQL"):
+        connection.describe_query(NIL_QUERY_ID)
+
+
+@pytest.mark.asyncio
+async def test_local_async_connection_rejects_sql(tmp_path):
+    connection = await lancedb.connect_async(tmp_path)
+    with pytest.raises(NotImplementedError, match="SQL"):
+        await connection.execute_query("SELECT 1")
+    with pytest.raises(NotImplementedError, match="SQL"):
+        await connection.execute_query_async("SELECT 1")
+    with pytest.raises(NotImplementedError, match="SQL"):
+        await connection.describe_query(NIL_QUERY_ID)
+
+
+@pytest.mark.asyncio
+async def test_async_namespace_connection_rejects_sql(tmp_path):
+    connection = lancedb.connect_namespace_async("dir", {"root": str(tmp_path)})
+    with pytest.raises(NotImplementedError, match="SQL"):
+        await connection.execute_query("SELECT 1")
+    with pytest.raises(NotImplementedError, match="SQL"):
+        await connection.execute_query_async("SELECT 1")
+    with pytest.raises(NotImplementedError, match="SQL"):
+        await connection.describe_query(NIL_QUERY_ID)
+
+
+def test_describe_query_requires_uuid():
+    with pytest.raises(TypeError, match="UUID"):
+        remote_connection().describe_query(str(NIL_QUERY_ID))
+
+
+@pytest.mark.parametrize(
+    "default_namespace_path",
+    ["public", ("public",), [1]],
+)
+def test_execute_query_async_requires_namespace_path_list(default_namespace_path):
+    with pytest.raises(ValueError, match="default_namespace_path"):
+        remote_connection().execute_query_async(
+            "SELECT 1", default_namespace_path=default_namespace_path
+        )
+
+
+def test_execute_query_async_rejects_invalid_endpoint():
+    connection = remote_connection(sql_host_override="invalid://localhost")
+    with pytest.raises(ValueError, match="sql_host_override"):
+        connection.execute_query_async("SELECT 1")
+
+
+@pytest.mark.parametrize(
+    "default_namespace_path",
+    [[""], ["café"], ["pub\tlic"], ["events$raw"]],
+)
+def test_execute_query_async_rejects_invalid_namespace_components(
+    default_namespace_path,
+):
+    with pytest.raises(ValueError, match="default_namespace_path"):
+        remote_connection().execute_query_async(
+            "SELECT 1", default_namespace_path=default_namespace_path
+        )

python/src/connection.rs

@@ -28,7 +28,7 @@ use pyo3::{
     Bound, FromPyObject, Py, PyAny, PyRef, PyResult, Python,
     exceptions::{PyRuntimeError, PyValueError},
     pyclass, pyfunction, pymethods,
-    types::{PyDict, PyDictMethods, PyList, PyListMethods},
+    types::{PyAnyMethods, PyDict, PyDictMethods, PyList, PyListMethods},
 };
 
 #[pyclass]
@@ -86,6 +86,24 @@ impl Connection {
     }
 }
 
+fn parse_default_namespace_path(path: Option<Bound<'_, PyAny>>) -> PyResult<Vec<String>> {
+    match path {
+        Some(path) => {
+            if !path.is_instance_of::<PyList>() {
+                return Err(PyValueError::new_err(
+                    "Connection.execute_query_async default_namespace_path must be a list",
+                ));
+            }
+            path.extract::<Vec<String>>().map_err(|_| {
+                PyValueError::new_err(
+                    "Connection.execute_query_async default_namespace_path components must be strings",
+                )
+            })
+        }
+        None => Ok(vec!["public".to_string()]),
+    }
+}
+
 #[pymethods]
 impl Connection {
     fn __repr__(&self) -> String {
@@ -108,6 +126,40 @@ impl Connection {
         self.get_inner().map(|inner| inner.uri().to_string())
     }
 
+    #[pyo3(signature = (query, *, default_namespace_path=None))]
+    pub fn execute_query_async<'a>(
+        self_: PyRef<'a, Self>,
+        query: String,
+        default_namespace_path: Option<Bound<'_, PyAny>>,
+    ) -> PyResult<Bound<'a, PyAny>> {
+        let inner = self_.get_inner()?.clone();
+        let default_namespace_path = parse_default_namespace_path(default_namespace_path)?;
+        future_into_py(self_.py(), async move {
+            let operation = inner
+                .execute_query_async(query)
+                .default_namespace_path(default_namespace_path);
+            operation
+                .execute()
+                .await
+                .map(crate::sql::Query::new)
+                .infer_error()
+        })
+    }
+
+    pub fn describe_query<'a>(
+        self_: PyRef<'a, Self>,
+        query_id: uuid::Uuid,
+    ) -> PyResult<Bound<'a, PyAny>> {
+        let inner = self_.get_inner()?.clone();
+        future_into_py(self_.py(), async move {
+            inner
+                .describe_query(query_id)
+                .await
+                .map(crate::sql::QueryDescription::from)
+                .infer_error()
+        })
+    }
+
     #[pyo3(signature = ())]
     pub fn get_read_consistency_interval(self_: PyRef<'_, Self>) -> PyResult<Bound<'_, PyAny>> {
         let inner = self_.get_inner()?.clone();
@@ -699,7 +751,7 @@ impl Connection {
 }
 
 #[pyfunction]
-#[pyo3(signature = (uri, api_key=None, region=None, host_override=None, read_consistency_interval=None, client_config=None, storage_options=None, session=None, manifest_enabled=false, namespace_client_properties=None, oauth_config=None))]
+#[pyo3(signature = (uri, api_key=None, region=None, host_override=None, sql_host_override=None, read_consistency_interval=None, client_config=None, storage_options=None, session=None, manifest_enabled=false, namespace_client_properties=None, oauth_config=None))]
 #[allow(clippy::too_many_arguments)]
 pub fn connect(
     py: Python<'_>,
@@ -707,6 +759,7 @@ pub fn connect(
     api_key: Option<String>,
     region: Option<String>,
     host_override: Option<String>,
+    sql_host_override: Option<String>,
     read_consistency_interval: Option<f64>,
     client_config: Option<PyClientConfig>,
     storage_options: Option<HashMap<String, String>>,
@@ -726,6 +779,12 @@ pub fn connect(
         if let Some(host_override) = host_override {
             builder = builder.host_override(&host_override);
         }
+        #[cfg(feature = "remote")]
+        if let Some(sql_host_override) = sql_host_override {
+            builder = builder.sql_host_override(&sql_host_override);
+        }
+        #[cfg(not(feature = "remote"))]
+        let _ = sql_host_override;
         if let Some(read_consistency_interval) = read_consistency_interval {
             let read_consistency_interval = Duration::from_secs_f64(read_consistency_interval);
             builder = builder.read_consistency_interval(read_consistency_interval);

python/src/lib.rs

@@ -34,6 +34,7 @@ pub mod permutation;
 pub mod query;
 pub mod runtime;
 pub mod session;
+pub mod sql;
 pub mod table;
 pub mod util;
 
@@ -50,6 +51,8 @@ pub fn _lancedb(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<crate::job::JobInfo>()?;
     m.add_class::<crate::job::JobDescription>()?;
     m.add_class::<crate::job::JobFailureInfo>()?;
+    m.add_class::<crate::sql::Query>()?;
+    m.add_class::<crate::sql::QueryDescription>()?;
     m.add_class::<PyBlobFile>()?;
     m.add_class::<IndexConfig>()?;
     m.add_class::<Query>()?;

python/src/sql.rs

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+use std::sync::Arc;
+
+use chrono::{DateTime, Utc};
+use pyo3::{Bound, PyAny, PyRef, PyResult, pyclass, pymethods};
+use uuid::Uuid;
+
+use crate::arrow::RecordBatchStream;
+use crate::error::PythonErrorExt;
+use crate::runtime::future_into_py;
+
+#[pyclass(name = "SqlQuery")]
+pub struct Query {
+    inner: Arc<lancedb::sql::Query>,
+}
+
+impl Query {
+    pub(crate) fn new(inner: lancedb::sql::Query) -> Self {
+        Self {
+            inner: Arc::new(inner),
+        }
+    }
+}
+
+#[pymethods]
+impl Query {
+    #[getter]
+    pub fn id(&self) -> Uuid {
+        self.inner.id()
+    }
+
+    pub fn describe(self_: PyRef<'_, Self>) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.inner.clone();
+        future_into_py(self_.py(), async move {
+            inner
+                .describe()
+                .await
+                .map(QueryDescription::from)
+                .infer_error()
+        })
+    }
+
+    pub fn reader(self_: PyRef<'_, Self>) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.inner.clone();
+        future_into_py(self_.py(), async move {
+            let stream = inner.reader().await.infer_error()?;
+            Ok(RecordBatchStream::new(stream))
+        })
+    }
+
+    pub fn cancel(self_: PyRef<'_, Self>) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.inner.clone();
+        future_into_py(self_.py(), async move {
+            inner.cancel().await.infer_error()?;
+            Ok(())
+        })
+    }
+}
+
+#[pyclass(get_all, skip_from_py_object)]
+#[derive(Clone)]
+pub struct QueryDescription {
+    id: Uuid,
+    status: String,
+    progress: Option<f64>,
+    expires_at: Option<DateTime<Utc>>,
+}
+
+#[pymethods]
+impl QueryDescription {
+    fn __repr__(&self) -> String {
+        format!(
+            "QueryDescription(id={:?}, status={:?}, progress={:?}, expires_at={:?})",
+            self.id, self.status, self.progress, self.expires_at
+        )
+    }
+}
+
+impl From<lancedb::sql::QueryDescription> for QueryDescription {
+    fn from(description: lancedb::sql::QueryDescription) -> Self {
+        Self {
+            id: description.id,
+            status: description.status.to_string(),
+            progress: description.progress,
+            expires_at: description.expires_at,
+        }
+    }
+}