@@ -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