Skip to content

Commit 1c0508f

Browse files
committed
docs: trim the 0.10.0 changelog entry
The entry ran 46 lines for a single added method, against neighbouring entries of 3-10. Keep what a reader scanning the changelog needs -- what the method is, that it polls the build job because the submit call hides failure, and the planner caveat -- and drop the rest, which is already in the docstring, CONTRACT.md, and the PR description.
1 parent c3374f9 commit 1c0508f

1 file changed

Lines changed: 8 additions & 50 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 8 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -12,56 +12,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1212

1313
### Added
1414

15-
- `create_index(database, table, columns=..., index_type=...)` builds an index on a
16-
managed table, bringing the framework client to parity with `hotdata indexes
17-
create` in the CLI. It covers all three index kinds the API accepts: `"bm25"` for
18-
full-text search, `"vector"` for nearest-neighbour search, and `"sorted"`.
19-
Previously the framework had no index API at all and callers had to drop to the raw
20-
`hotdata.IndexesApi`, which left a managed database's data loaded but not
21-
searchable: full-text queries error without an index, and vector queries run at
22-
full-scan speed. Like the other managed-table operations, `database` accepts a
23-
name/id or an already-resolved `ManagedDatabase`. Indexing a table on a plain
24-
(non-managed) connection is not covered — the CLI's `--catalog` handles that.
25-
26-
`index_name` is optional and defaults to `{table}_{columns}_{index_type}`, the same
27-
derivation the CLI uses when `--name` is omitted, so both surfaces name the same
28-
index identically. `index_type` is required, unlike the API's `"sorted"` default,
29-
because the wrong kind only fails at query time.
30-
31-
The server builds the index as a background job whose submit call reports success
32-
even when the build later fails, so `create_index` polls the job to a terminal
33-
state and raises `RuntimeError` carrying the job's `error_message`. Pass
34-
`wait=False` to return once the job is accepted (`status="pending"` plus a
35-
`job_id`) and own the outcome check yourself, as the CLI's `--async` does;
36-
`timeout_s` and `poll_interval_s` tune the wait.
37-
38-
Both vector-index modes are supported. Omitting `embedding_provider_id` indexes an
39-
existing vector column, queried with a literal vector — and there `metric` must
40-
match the distance function the query uses (`cosine`→`cosine_distance`,
41-
`l2`→`l2_distance`, `dot`→`negative_dot_product`), since a mismatch silently
42-
reverts to a full table scan rather than erroring. Setting
43-
`embedding_provider_id` indexes a *text* column instead: the provider embeds it
44-
into `output_column`, queries pass text via `vector_distance(source_col, 'query')`,
45-
and the server resolves the distance function itself.
46-
47-
Argument combinations that the server would silently ignore raise `ValueError`
48-
before any request is sent: an unknown `index_type` or `metric`, a vector index
49-
with more than one column (the engine indexes only the first), and
50-
`metric`/`dimensions`/`embedding_provider_id`/`output_column`/`description` on a
51-
non-vector index.
52-
53-
Verified against `api.hotdata.dev` when this version was released: BM25 and vector
54-
indexes both build and report `ready`, and a BM25 index is used by full-text
55-
search. A *vector* index on a managed database was **not** picked up by the query
56-
planner at that time — a matching `cosine_distance(...) ORDER BY ... LIMIT k` still
57-
planned as a full scan. That reproduces with an index created by `hotdata indexes
58-
create`, so it is an engine-side issue rather than a client one, but it means a
59-
vector index built through this method may not yet accelerate queries.
60-
61-
- `CreateIndexResult`, the frozen dataclass `create_index` returns, is exported from
62-
`hotdata_framework` and added to the public contract surface. Its `source_column`
63-
names the text column to query for a provider-backed vector index, and is `None`
64-
for BM25, sorted, and plain vector indexes.
15+
- `create_index(database, table, columns=..., index_type=...)` builds a `bm25`,
16+
`vector`, or `sorted` index on a managed table, matching `hotdata indexes create`
17+
in the CLI. The build is a background job whose submit call reports success even
18+
when the build later fails, so this polls the job and raises `RuntimeError` with
19+
its error message; `wait=False` returns as soon as the job is accepted. Returns
20+
`CreateIndexResult`, also exported.
21+
- Known issue: a vector index is not yet used by the query planner on a managed
22+
database. Reproduces via the CLI, so it is engine-side; BM25 is unaffected.
6523

6624
## [0.9.0] - 2026-07-23
6725

0 commit comments

Comments
 (0)