danvics/haiku.rag
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Record what the multi-database work changes, and what it measured

Browse source 
`--db-name` selects one database, not a subset: it is not repeatable.

The reranker recommendation was one-sided. It reports both measured effects now:
stronger aggregate retrieval across shards, and weaker attribution between
near-identical documents, where fusion keeps twins apart because each database
contributes its own top-ranked result.

Image queries are vector-only and skip the reranker.

The changelog described components of the new feature as fixes to the last
release. They are one Added entry, and the changes a user upgrading does see —
`settings` printing YAML, the document filter paging and searching, `list`
printing only the fields a document has — are listed.
This commit is contained in:
Yiorgis Gozadinos 2026-08-27 17:30:29 +03:00
parent 0dec3d4e63
commit 4d7fdd2d26
No known key found for this signature in database
2 changed files with 45 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
CHANGELOG.md
View file

@ -4,25 +4,30 @@
### Added
- `lancedb.databases` configures a named set of local or remote databases. `search`,
`ask` and `analyze` accept a `sources` subset; results, documents and citations
include the originating database in `source`. Search results are combined with
the configured reranker, or reciprocal rank fusion when reranking is disabled.
- `haiku-rag search`, `ask`, `analyze` and `chat` can cover a configured database
set. Commands that access one database select it with `--db-name NAME` or
- `lancedb.databases` configures a named set of local or remote databases.
`search`, `ask` and `analyze` accept a `sources` subset; results, documents and
citations carry the originating database in `source`, and model context names
it as `Collection:` when a search spans more than one. Candidates are combined
with the configured reranker, or reciprocal rank fusion when reranking is
disabled. Operations that need one database raise `AmbiguousDatabaseError`, an
unknown name raises `UnknownDatabaseError`, and a cited chunk ID retrieved from
or previously cited from more than one selected database raises
`AmbiguousCitationError`.
- `haiku-rag search`, `ask`, `analyze` and `chat` cover a configured set.
Commands that access one database select it with `--db-name NAME` or
`--db PATH`.
- Citation resolution rejects a chunk ID retrieved from, or previously cited
from, more than one selected database with `AmbiguousCitationError`.
- `HaikuRAG.aclose()` releases a client whatever it covers. `close()` remains
limited to clients covering one database.
### Fixed
- `client.chunk()` and `client.embedder` work when the client covers multiple
databases. Operations that require one database raise `AmbiguousDatabaseError`.
- The chat document filter selects by document ID and shows each document's
database.
- `haiku-rag settings` prints YAML instead of Python dict reprs.
- The chat document filter pages results, searches the database for the rest, and
lists the selected separately, instead of mounting a checkbox per document.
Selection is by document ID.
- `haiku-rag list` prints only the fields a document has.
- `haiku-rag` prints the message and exits when the configured embedder does not match the database, instead of raising a traceback.
- Capabilities created without a client now honor `lancedb.uri` and
`lancedb.databases`.
- Capabilities created without a client honor `lancedb.uri`.
- A `lancedb.uri` without a scheme is treated as a local path. `--db PATH`
overrides it.
- Inspector search results mark truncated previews with an ellipsis.

36
docs/configuration/storage.md
View file

@ -278,22 +278,38 @@ document in each of them.
#### Ranking
Configure a reranker when searching multiple databases. Reciprocal rank fusion
compares positions rather than scores, so each database contributes top-ranked
results even when another database has stronger matches. A reranker scores the
combined candidate set directly.
Reciprocal rank fusion compares positions rather than scores, so each database
contributes top-ranked results even when another database has stronger matches. A
reranker scores the combined candidate set directly, which has been measured to
help aggregate retrieval and to hurt attribution between near-identical
documents.
In a 3,045-query evaluation over a corpus split across three databases,
reranking produced retrieval MAP 0.9914, compared with 0.9918 for the same corpus
in one database. Without a reranker, MAP was 0.6044, compared with 0.9798 in one
database. Reranking cost grows with the number of databases because each
contributes candidates.
Aggregate retrieval is stronger with a reranker. In a 3,045-query evaluation over
a corpus split across three databases, reranking produced retrieval MAP 0.9914,
compared with 0.9918 for the same corpus in one database. Without a reranker, MAP
was 0.6044, compared with 0.9798 in one database. Reranking cost grows with the
number of databases because each contributes candidates.
A reranker scores the combined candidates with no notion of which database each
came from, so on near-identical text it can pick the wrong database's chunk,
where fusion keeps them apart because each database contributes its own
top-ranked result. In two nine-case acceptance runs over a synthetic corpus
holding one station in two databases under near-identical names, attribution was
weaker with reranking: citing the right database succeeded 5 of 9 and 6 of 9
times with a reranker, against 8 of 9 and 9 of 9 without.
Configure a reranker where retrieval breadth matters, and measure it where
answers have to attribute between documents that read alike.
Without a reranker, consider increasing `search.limit` with the number of
databases. With three complete rankings and a limit of 5, a database may
contribute only one or two results. A higher limit also sends more results to
the caller and model.
Image queries are vector-only and skip the reranker: there is no query text to
score a document against, so candidates keep their vector ranking and fusion
ranks by position.
If any selected database fails to open, the operation fails and identifies that
database.
@ -319,7 +335,7 @@ available on a multi-database client.
Commands use database sets as follows:
- **Set-capable**: `search`, `ask`, `analyze`, and `chat` use the full
configured set, or the subset named by `--db-name`.
configured set, or the single database selected by `--db-name`.
- **Config-only**: `settings`, `init-config`, and `download-models` do not open
a database.
- **Single-database**: everything else — document writes, `rebuild`, `vacuum`,