hotdata-framework 0.8.0__tar.gz → 0.10.0__tar.gz

hotdata_framework-0.10.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @hotdata-dev/engineers

{hotdata_framework-0.8.0 → hotdata_framework-0.10.0}/CHANGELOG.md

@@ -8,6 +8,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [0.10.0] - 2026-08-07
+
+### Added
+
+- `create_index(database, table, columns=..., index_type=...)` builds an index on a
+  managed table, bringing the framework client to parity with `hotdata indexes
+  create` in the CLI. It covers all three index kinds the API accepts: `"bm25"` for
+  full-text search, `"vector"` for nearest-neighbour search, and `"sorted"`.
+  Previously the framework had no index API at all and callers had to drop to the raw
+  `hotdata.IndexesApi`, which left a managed database's data loaded but not
+  searchable: full-text queries error without an index, and vector queries run at
+  full-scan speed. Like the other managed-table operations, `database` accepts a
+  name/id or an already-resolved `ManagedDatabase`. Indexing a table on a plain
+  (non-managed) connection is not covered — the CLI's `--catalog` handles that.
+
+  `index_name` is optional and defaults to `{table}_{columns}_{index_type}`, the same
+  derivation the CLI uses when `--name` is omitted, so both surfaces name the same
+  index identically. `index_type` is required, unlike the API's `"sorted"` default,
+  because the wrong kind only fails at query time.
+
+  The server builds the index as a background job whose submit call reports success
+  even when the build later fails, so `create_index` polls the job to a terminal
+  state and raises `RuntimeError` carrying the job's `error_message`. Pass
+  `wait=False` to return once the job is accepted (`status="pending"` plus a
+  `job_id`) and own the outcome check yourself, as the CLI's `--async` does;
+  `timeout_s` and `poll_interval_s` tune the wait.
+
+  Both vector-index modes are supported. Omitting `embedding_provider_id` indexes an
+  existing vector column, queried with a literal vector — and there `metric` must
+  match the distance function the query uses (`cosine`→`cosine_distance`,
+  `l2`→`l2_distance`, `dot`→`negative_dot_product`), since a mismatch silently
+  reverts to a full table scan rather than erroring. Setting
+  `embedding_provider_id` indexes a *text* column instead: the provider embeds it
+  into `output_column`, queries pass text via `vector_distance(source_col, 'query')`,
+  and the server resolves the distance function itself.
+
+  Argument combinations that the server would silently ignore raise `ValueError`
+  before any request is sent: an unknown `index_type` or `metric`, a vector index
+  with more than one column (the engine indexes only the first), and
+  `metric`/`dimensions`/`embedding_provider_id`/`output_column`/`description` on a
+  non-vector index.
+
+  Verified against `api.hotdata.dev` when this version was released: BM25 and vector
+  indexes both build and report `ready`, and a BM25 index is used by full-text
+  search. A *vector* index on a managed database was **not** picked up by the query
+  planner at that time — a matching `cosine_distance(...) ORDER BY ... LIMIT k` still
+  planned as a full scan. That reproduces with an index created by `hotdata indexes
+  create`, so it is an engine-side issue rather than a client one, but it means a
+  vector index built through this method may not yet accelerate queries.
+
+- `CreateIndexResult`, the frozen dataclass `create_index` returns, is exported from
+  `hotdata_framework` and added to the public contract surface. Its `source_column`
+  names the text column to query for a provider-backed vector index, and is `None`
+  for BM25, sorted, and plain vector indexes.
+
+## [0.9.0] - 2026-07-23
+
+### Added
+
+- `list_managed_tables`, `load_managed_table`, `add_managed_table`,
+  `delete_managed_table`, `delete_managed_database`, and `execute_sql` accept an
+  already-resolved `ManagedDatabase` (as returned by `create_managed_database`)
+  in place of a name/id. When passed one, they skip the `get_database` /
+  `list_databases` read probe. This lets an API key scoped to create + load but
+  not read `/databases` bootstrap a managed database and load into it within a
+  single run: the caller holds the `ManagedDatabase` from `create` and drives
+  the load/add/query ops with zero reads. The name/id string path is unchanged.
+
 ## [0.8.0] - 2026-07-20
 
 ### Changed

{hotdata_framework-0.8.0 → hotdata_framework-0.10.0}/CONTRACT.md

@@ -33,6 +33,7 @@ The supported import surface is:
 - `ManagedDatabase`
 - `ManagedTable`
 - `LoadManagedTableResult`
+- `CreateIndexResult`
 - `DEFAULT_SCHEMA`
 - `is_parquet_path`
 
@@ -56,13 +57,15 @@ Adapters should import from `hotdata_framework` and treat this surface as the st
   adapters should pass `connection_id` when known.
 - `uploads()` returns the uploads API wrapper for parquet staging.
 - `list_managed_databases()` returns all databases via the `/databases` API.
-- `resolve_managed_database(name_or_id)` resolves a database by id (direct lookup) or description (list scan).
-- `create_managed_database(description=..., schema=..., tables=..., expires_at=...)` creates a database via the `/databases` API and optionally declares tables up front.
+- `resolve_managed_database(name_or_id)` resolves a database by id (direct lookup) or description (list scan). A `403` from `/databases` surfaces as `RuntimeError` (forbidden, not absent), preserving the underlying `ApiException` as `__cause__`.
+- `create_managed_database(description=..., schema=..., tables=..., expires_at=...)` creates a database via the `/databases` API and optionally declares tables up front. Returns a `ManagedDatabase` (id + `default_connection_id`) sufficient to load without a further read.
 - `delete_managed_database(name_or_id)` deletes a database via the `/databases` API.
 - `list_managed_tables(database, schema=...)` lists tables in a managed database.
 - `upload_parquet(path)` uploads a local parquet file and returns an upload id.
 - `load_managed_table(database, table, schema=..., upload_id=..., file=...)` publishes parquet data into a declared managed table.
 - `delete_managed_table(database, table, schema=...)` deletes a managed table.
+- `create_index(database, table, schema=..., columns=..., index_type=..., index_name=...)` builds a `"sorted"`, `"bm25"`, or `"vector"` index on a managed table and returns a `CreateIndexResult`. It is the framework-side equivalent of the CLI's `hotdata indexes create`; indexing a table on a plain (non-managed) connection is out of scope. `index_name` defaults to `{table}_{columns}_{index_type}`, matching the CLI's derivation when `--name` is omitted. `index_type` is required rather than defaulting to the API's `"sorted"`. The build runs as a background job; the call polls it to a terminal state and raises `RuntimeError` with the job's `error_message` when it fails, because the submit call reports success regardless. `wait=False` returns as soon as the job is accepted, with `status="pending"` and a `job_id` for the caller to poll. For `index_type="vector"`, omitting `embedding_provider_id` indexes an existing vector column and `metric` (`"l2"`, `"cosine"`, `"dot"`) selects the distance function the index accelerates — a query using a different function silently falls back to a full scan; setting `embedding_provider_id` indexes a source *text* column instead, and the returned `source_column` names the column to pass to `vector_distance`. Argument combinations the server would silently ignore raise `ValueError` before any request is sent.
+- The `database` argument of `list_managed_tables`, `load_managed_table`, `add_managed_table`, `delete_managed_table`, `delete_managed_database`, `create_index`, and `execute_sql` accepts a name/id **or** an already-resolved `ManagedDatabase`. Passing a `ManagedDatabase` skips the name/id read probe, so a create-scoped key that cannot read `/databases` can load into a database it just created.
 
 ### `QueryResult`
 

{hotdata_framework-0.8.0 → hotdata_framework-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hotdata-framework
-Version: 0.8.0
+Version: 0.10.0
 Summary: Python framework for building Hotdata integrations: workspace/session runtime, query execution, and managed databases
 Project-URL: Homepage, https://www.hotdata.dev
 Project-URL: Documentation, https://www.hotdata.dev/docs
@@ -44,6 +44,7 @@ Runtime boundary and guarantees are defined in `CONTRACT.md`.
 - **Result utilities** — convert query results to records, pandas DataFrames, or metadata dictionaries for adapter display layers.
 - **History helpers** — list recent results and query run history with normalized dataclasses.
 - **Managed databases** — create Hotdata-owned catalogs, declare tables, upload parquet, and load managed tables (mirrors `hotdata databases` in the CLI).
+- **Indexes** — build BM25, vector, or sorted indexes on managed tables, mirroring `hotdata indexes create` (managed databases only). Waits on the background build job and surfaces its failure, instead of reporting the phantom success the submit call returns.
 - **Health helpers** — build compact API/workspace health summaries for UI integrations.
 
 Install:

{hotdata_framework-0.8.0 → hotdata_framework-0.10.0}/README.md

@@ -16,6 +16,7 @@ Runtime boundary and guarantees are defined in `CONTRACT.md`.
 - **Result utilities** — convert query results to records, pandas DataFrames, or metadata dictionaries for adapter display layers.
 - **History helpers** — list recent results and query run history with normalized dataclasses.
 - **Managed databases** — create Hotdata-owned catalogs, declare tables, upload parquet, and load managed tables (mirrors `hotdata databases` in the CLI).
+- **Indexes** — build BM25, vector, or sorted indexes on managed tables, mirroring `hotdata indexes create` (managed databases only). Waits on the background build job and surfaces its failure, instead of reporting the phantom success the submit call returns.
 - **Health helpers** — build compact API/workspace health summaries for UI integrations.
 
 Install:

{hotdata_framework-0.8.0 → hotdata_framework-0.10.0}/hotdata_framework/__init__.py

@@ -10,6 +10,7 @@ from hotdata_framework.client import (
 )
 from hotdata_framework.databases import (
     DEFAULT_SCHEMA,
+    CreateIndexResult,
     LoadManagedTableResult,
     ManagedDatabase,
     ManagedTable,
@@ -43,6 +44,7 @@ except PackageNotFoundError:
 
 __all__ = [
     "DEFAULT_SCHEMA",
+    "CreateIndexResult",
     "HotdataClient",
     "HotdataError",
     "HotdataTerminalError",

{hotdata_framework-0.8.0 → hotdata_framework-0.10.0}/hotdata_framework/client.py

@@ -4,12 +4,14 @@ import functools
 import time
 from collections.abc import Iterator
 from dataclasses import asdict, dataclass
-from typing import Any, Literal
+from typing import Any, Literal, get_args
 
 from hotdata import ApiClient, Configuration
 from hotdata.api.connections_api import ConnectionsApi
 from hotdata.api.databases_api import DatabasesApi
+from hotdata.api.indexes_api import IndexesApi
 from hotdata.api.information_schema_api import InformationSchemaApi
+from hotdata.api.jobs_api import JobsApi
 from hotdata.api.query_api import QueryApi
 from hotdata.api.query_runs_api import QueryRunsApi
 from hotdata.api.results_api import ResultsApi
@@ -20,21 +22,27 @@ from hotdata.exceptions import ApiException
 from hotdata.models.add_managed_table_request import AddManagedTableRequest
 from hotdata.models.async_query_response import AsyncQueryResponse
 from hotdata.models.create_database_request import CreateDatabaseRequest
+from hotdata.models.create_index_request import CreateIndexRequest
 from hotdata.models.database_default_schema_decl import DatabaseDefaultSchemaDecl
 from hotdata.models.database_default_table_decl import DatabaseDefaultTableDecl
+from hotdata.models.index_info_response import IndexInfoResponse
+from hotdata.models.job_status_response import JobStatusResponse
 from hotdata.models.load_managed_table_request import LoadManagedTableRequest
 from hotdata.models.query_request import QueryRequest
 from hotdata.models.query_response import QueryResponse
+from hotdata.models.submit_job_response import SubmitJobResponse
 from hotdata.models.table_info import TableInfo
 from urllib3.exceptions import HTTPError as Urllib3HTTPError
 from urllib3.exceptions import ProtocolError
 
 from hotdata_framework.databases import (
     DEFAULT_SCHEMA,
+    CreateIndexResult,
     LoadManagedTableResult,
     ManagedDatabase,
     ManagedTable,
     api_error_message,
+    enum_value,
     is_parquet_path,
     managed_database_from_detail,
 )
@@ -52,8 +60,24 @@ from hotdata_framework.result import QueryResult
 # rows, delete/update/upsert match by the table's declared key.
 ManagedLoadMode = Literal["replace", "append", "delete", "update", "upsert"]
 
+# Index kinds the indexes endpoint accepts. "sorted" is the server-side default;
+# "bm25" backs full-text search and "vector" backs nearest-neighbour search.
+IndexType = Literal["sorted", "bm25", "vector"]
+
+# Distance metrics a vector index can be built with. Each one accelerates
+# exactly one query function: cosine -> cosine_distance, l2 -> l2_distance,
+# dot -> negative_dot_product. A hand-written query naming a different function
+# falls back to a full scan; the provider-backed vector_distance path resolves
+# the function from the index instead, so it cannot mismatch.
+VectorMetric = Literal["l2", "cosine", "dot"]
+
+_INDEX_TYPES = frozenset(get_args(IndexType))
+_VECTOR_METRICS = frozenset(get_args(VectorMetric))
+
 _TERMINAL = frozenset({"succeeded", "failed", "cancelled"})
 _RESULT_FAILURE = frozenset({"failed", "cancelled"})
+# Jobs have no "cancelled" state; "partially_succeeded" carries an error_message.
+_JOB_TERMINAL = frozenset({"succeeded", "partially_succeeded", "failed"})
 
 
 @dataclass(frozen=True)
@@ -188,6 +212,12 @@ class HotdataClient:
     def _information_schema(self) -> InformationSchemaApi:
         return InformationSchemaApi(self._api)
 
+    def _indexes_api(self) -> IndexesApi:
+        return IndexesApi(self._api)
+
+    def _jobs_api(self) -> JobsApi:
+        return JobsApi(self._api)
+
     def _query_api(self) -> QueryApi:
         return QueryApi(self._api)
 
@@ -241,6 +271,19 @@ class HotdataClient:
             raise RuntimeError(api_error_message(e)) from e
         return managed_database_from_detail(detail)
 
+    def _as_managed_database(self, database: str | ManagedDatabase) -> ManagedDatabase:
+        """Return ``database`` as-is if it is already a resolved ``ManagedDatabase``,
+        otherwise resolve it by name or id.
+
+        Passing an already-resolved ``ManagedDatabase`` (e.g. the value returned by
+        :meth:`create_managed_database`) skips the id/name read probe, so callers
+        whose API key may create but not read ``/databases`` can drive loads without
+        a forbidden read.
+        """
+        if isinstance(database, ManagedDatabase):
+            return database
+        return self.resolve_managed_database(database)
+
     def create_managed_database(
         self,
         description: str | None = None,
@@ -275,8 +318,8 @@ class HotdataClient:
             raise RuntimeError(api_error_message(e)) from e
         return managed_database_from_detail(created)
 
-    def delete_managed_database(self, name_or_id: str) -> None:
-        db = self.resolve_managed_database(name_or_id)
+    def delete_managed_database(self, name_or_id: str | ManagedDatabase) -> None:
+        db = self._as_managed_database(name_or_id)
         try:
             self._databases_api().delete_database(db.id)
         except ApiException as e:
@@ -284,11 +327,11 @@ class HotdataClient:
 
     def list_managed_tables(
         self,
-        database: str,
+        database: str | ManagedDatabase,
         *,
         schema: str | None = None,
     ) -> list[ManagedTable]:
-        db = self.resolve_managed_database(database)
+        db = self._as_managed_database(database)
         rows: list[ManagedTable] = []
         for t in self.iter_tables(connection_id=db.default_connection_id):
             if schema is not None and t.var_schema != schema:
@@ -333,7 +376,7 @@ class HotdataClient:
 
     def load_managed_table(
         self,
-        database: str,
+        database: str | ManagedDatabase,
         table: str,
         *,
         schema: str = DEFAULT_SCHEMA,
@@ -344,7 +387,7 @@ class HotdataClient:
     ) -> LoadManagedTableResult:
         if (upload_id is None) == (file is None):
             raise ValueError("Exactly one of upload_id or file is required")
-        db = self.resolve_managed_database(database)
+        db = self._as_managed_database(database)
         if upload_id is not None:
             resolved_upload_id = upload_id
         else:
@@ -374,7 +417,7 @@ class HotdataClient:
 
     def add_managed_table(
         self,
-        database: str,
+        database: str | ManagedDatabase,
         table: str,
         *,
         schema: str = DEFAULT_SCHEMA,
@@ -387,7 +430,7 @@ class HotdataClient:
         schema after creation without recreating it. ``key`` sets the
         row-identity columns for delete/update/upsert; omit for keyless.
         """
-        db = self.resolve_managed_database(database)
+        db = self._as_managed_database(database)
         request = AddManagedTableRequest(name=table, key=list(key or []))
         try:
             self._databases_api().add_database_table(db.id, schema, request)
@@ -403,17 +446,210 @@ class HotdataClient:
 
     def delete_managed_table(
         self,
-        database: str,
+        database: str | ManagedDatabase,
         table: str,
         *,
         schema: str = DEFAULT_SCHEMA,
     ) -> None:
-        db = self.resolve_managed_database(database)
+        db = self._as_managed_database(database)
         try:
             self.connections().delete_managed_table(db.default_connection_id, schema, table)
         except ApiException as e:
             raise RuntimeError(api_error_message(e)) from e
 
+    def create_index(
+        self,
+        database: str | ManagedDatabase,
+        table: str,
+        *,
+        schema: str = DEFAULT_SCHEMA,
+        index_name: str | None = None,
+        columns: list[str],
+        index_type: IndexType,
+        metric: VectorMetric | None = None,
+        dimensions: int | None = None,
+        embedding_provider_id: str | None = None,
+        output_column: str | None = None,
+        description: str | None = None,
+        wait: bool = True,
+        timeout_s: float = 300.0,
+        poll_interval_s: float = 2.0,
+    ) -> CreateIndexResult:
+        """Build an index on a managed table and wait for it to be ready.
+
+        The Python equivalent of ``hotdata indexes create``, scoped to managed
+        databases. Indexing a table on a plain (non-managed) connection is not
+        supported here; the CLI's ``--catalog`` flag covers that case.
+
+        ``index_type`` selects the index kind and is required: ``"bm25"`` for
+        full-text search (queries error outright without one), ``"vector"`` for
+        nearest-neighbour search (queries work without one, but only at
+        full-scan speed), or ``"sorted"``. The API defaults an unspecified kind
+        to ``"sorted"``; this method makes the choice explicit instead, because
+        the wrong kind fails at query time rather than here.
+
+        ``index_name`` defaults to ``{table}_{columns}_{index_type}``, the same
+        derivation the CLI uses when ``--name`` is omitted, so both surfaces
+        name the same index identically.
+
+        There are two kinds of vector index, and they are queried differently:
+
+        * **Plain** — omit ``embedding_provider_id``. ``columns`` is the existing
+          vector column (a float list), and a query passes a literal vector:
+          ``cosine_distance(col, ARRAY[...])``. Here ``metric`` must match the
+          distance function the caller writes — ``cosine`` serves
+          ``cosine_distance``, ``l2`` serves ``l2_distance``, ``dot`` serves
+          ``negative_dot_product``. A mismatch is not an error: the query
+          silently reverts to a full table scan. Omitting ``metric`` lets the
+          server choose (``l2`` for float-array columns), so pass it explicitly
+          whenever the query function is known.
+        * **Provider-backed** — set ``embedding_provider_id`` (e.g. the system
+          provider ``sys_emb_openai``). ``columns`` is then the *source text*
+          column; the provider embeds it into ``output_column`` (default
+          ``{column}_embedding``) and the index is built over that. A query
+          passes text, not a vector — ``vector_distance(source_col, 'query')`` —
+          and the server resolves the matching distance function from the index
+          itself, so the metric-mismatch trap above does not apply. The returned
+          ``source_column`` names the column to query.
+
+        ``dimensions`` picks the output width for providers that support several;
+        it does not apply when indexing an existing vector column, whose width is
+        read from the data. ``description`` is a user-facing label for the
+        embedding (e.g. ``"product descriptions"``), stored alongside it. A vector
+        index takes exactly one column, and every option in this paragraph — plus
+        ``metric`` — is rejected for a non-vector ``index_type``, matching the CLI.
+
+        The server builds the index as a background job. This method polls that
+        job to a terminal state and raises ``RuntimeError`` if it failed, because
+        the submit call itself reports success for builds that later fail. Pass
+        ``wait=False`` to return as soon as the job is accepted — the result then
+        carries ``status="pending"`` and a ``job_id``, and the caller owns
+        checking the outcome (the CLI's ``--async`` plus ``hotdata jobs``).
+
+        Raises ``ValueError`` for an unusable argument combination,
+        ``RuntimeError`` if the API rejects the request or the build fails, and
+        ``TimeoutError`` if the build is still running after ``timeout_s``.
+        """
+        if not columns:
+            raise ValueError("create_index requires at least one column")
+        if index_type not in _INDEX_TYPES:
+            allowed = ", ".join(sorted(_INDEX_TYPES))
+            raise ValueError(f"index_type must be one of {allowed} (got {index_type!r})")
+        if index_type != "vector":
+            vector_only = {
+                "metric": metric,
+                "dimensions": dimensions,
+                "embedding_provider_id": embedding_provider_id,
+                "output_column": output_column,
+                "description": description,
+            }
+            supplied = sorted(k for k, v in vector_only.items() if v is not None)
+            if supplied:
+                raise ValueError(
+                    f"{', '.join(supplied)} appl{'ies' if len(supplied) == 1 else 'y'} to "
+                    f"vector indexes only (index_type={index_type!r})"
+                )
+        else:
+            if len(columns) != 1:
+                raise ValueError(
+                    f"a vector index takes exactly one column (got {len(columns)}); "
+                    "the engine indexes only the first"
+                )
+            if metric is not None and metric not in _VECTOR_METRICS:
+                allowed = ", ".join(sorted(_VECTOR_METRICS))
+                raise ValueError(f"metric must be one of {allowed} (got {metric!r})")
+
+        # Matches the CLI's derivation so both surfaces name the same index
+        # identically: `hotdata indexes create` without --name.
+        resolved_name = index_name or f"{table}_{'_'.join(columns)}_{index_type}"
+
+        db = self._as_managed_database(database)
+        request = CreateIndexRequest(
+            index_name=resolved_name,
+            columns=list(columns),
+            index_type=index_type,
+            metric=metric,
+            dimensions=dimensions,
+            embedding_provider_id=embedding_provider_id,
+            output_column=output_column,
+            description=description,
+            var_async=True,
+        )
+        try:
+            submitted = self._indexes_api().create_index(
+                db.default_connection_id,
+                schema,
+                table,
+                request,
+            )
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+
+        full_name = f"{db.id}.{schema}.{table}"
+
+        # A build the server finished inline answers 201 with the index itself;
+        # the async path answers 202 with a job to poll.
+        if isinstance(submitted, IndexInfoResponse):
+            return self._index_result(submitted, full_name, schema, table, job_id=None)
+
+        if not isinstance(submitted, SubmitJobResponse):
+            raise RuntimeError(f"Unexpected create_index response type: {type(submitted)!r}")
+
+        job_id = submitted.id
+
+        def requested_result(status: str) -> CreateIndexResult:
+            """Echo the requested values, for the paths where the server hands
+            back a job rather than the built index."""
+            return CreateIndexResult(
+                full_name=full_name,
+                schema_name=schema,
+                table_name=table,
+                index_name=resolved_name,
+                index_type=index_type,
+                columns=list(columns),
+                metric=metric,
+                source_column=columns[0] if embedding_provider_id else None,
+                status=status,
+                job_id=job_id,
+            )
+
+        if not wait:
+            return requested_result(enum_value(submitted.status))
+
+        job = self._poll_job(job_id, timeout_s=timeout_s, interval_s=poll_interval_s)
+        status = enum_value(job.status)
+        if status != "succeeded":
+            detail = job.error_message or f"Index build {status}"
+            raise RuntimeError(f"Index {resolved_name!r} on {full_name}: {detail}")
+
+        # `result` is a oneOf wrapper today; tolerate the model arriving directly.
+        built = getattr(job.result, "actual_instance", job.result)
+        if isinstance(built, IndexInfoResponse):
+            return self._index_result(built, full_name, schema, table, job_id=job_id)
+        return requested_result("ready")
+
+    @staticmethod
+    def _index_result(
+        info: IndexInfoResponse,
+        full_name: str,
+        schema: str,
+        table: str,
+        *,
+        job_id: str | None,
+    ) -> CreateIndexResult:
+        return CreateIndexResult(
+            full_name=full_name,
+            schema_name=schema,
+            table_name=table,
+            index_name=info.index_name,
+            index_type=info.index_type,
+            columns=list(info.columns),
+            metric=info.metric,
+            source_column=info.source_column,
+            status=enum_value(info.status),
+            job_id=job_id,
+        )
+
     def list_recent_results(
         self,
         *,
@@ -547,6 +783,29 @@ class HotdataClient:
             f"(last status: {getattr(last, 'status', None)})"
         )
 
+    def _poll_job(
+        self,
+        job_id: str,
+        *,
+        timeout_s: float = 300.0,
+        interval_s: float = 2.0,
+    ) -> JobStatusResponse:
+        jobs = self._jobs_api()
+        deadline = time.monotonic() + timeout_s
+        last: JobStatusResponse | None = None
+        while time.monotonic() < deadline:
+            try:
+                last = jobs.get_job(job_id)
+            except ApiException as e:
+                raise RuntimeError(api_error_message(e)) from e
+            if last.status in _JOB_TERMINAL:
+                return last
+            time.sleep(interval_s)
+        last_status = enum_value(last.status) if last is not None else None
+        raise TimeoutError(
+            f"Job {job_id} did not finish within {timeout_s}s (last status: {last_status})"
+        )
+
     def _wait_result_ready(
         self,
         result_id: str,
@@ -569,16 +828,19 @@ class HotdataClient:
             f"(last status: {getattr(last, 'status', None)})"
         )
 
-    def execute_sql(self, sql: str, *, database: str | None = None) -> QueryResult:
+    def execute_sql(
+        self, sql: str, *, database: str | ManagedDatabase | None = None
+    ) -> QueryResult:
         """Execute SQL and return a :class:`QueryResult`.
 
-        Pass ``database`` to scope the query to a managed database.  The name
-        is resolved to a database ID once before the retry loop, and the
+        Pass ``database`` to scope the query to a managed database.  A name or
+        id is resolved to a database ID once before the retry loop; an
+        already-resolved ``ManagedDatabase`` is used as-is (no read probe).  The
         ``X-Database-Id`` header is sent with every attempt.  Inside a managed
         database the built-in catalog is always ``"default"``, so table
         references should use ``"default"."<schema>"."<table>"``.
         """
-        database_id = self.resolve_managed_database(database).id if database else None
+        database_id = self._as_managed_database(database).id if database else None
         last_err: BaseException | None = None
         for attempt in range(3):
             try: