diff options
| author | Alexander_Kabui <alexanderkabua@gmail.com> | 2026-10-08 07:28:20 +0300 |
|---|---|---|
| committer | Alexander_Kabui <alexanderkabua@gmail.com> | 2026-10-08 07:28:20 +0300 |
| commit | 1a03e984c2e37ad0c8ec50efe6353548af7d222d (patch) | |
| tree | 12fe38c2040e62f4f41d7152041c4f1c73858fc0 /docs | |
| parent | 3c759f2e28b4dec1561b91900a7100975a74ccc5 (diff) | |
| download | genenetwork4-1a03e984c2e37ad0c8ec50efe6353548af7d222d.tar.gz | |
docs/search-engines.md: how to select and run a search engine (the
gn3 proxy by default, the native xapian engine on SEARCH_ENGINE=native + XAPIAN_DB_PATH); README.md (search): point to it. House style: scope line, takeaway headings, code pointers, known quirks (locus null reason, sort tail difference, no runtime indicator).
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/search-engines.md | 61 |
1 files changed, 61 insertions, 0 deletions
diff --git a/docs/search-engines.md b/docs/search-engines.md new file mode 100644 index 0000000..cdb58c5 --- /dev/null +++ b/docs/search-engines.md @@ -0,0 +1,61 @@ +# Search engines: proxy and native + +Everything below is about **how to select and run a search engine**, +not how either engine is built. Two engines implement the same +`Engine` seam (`src/search/mod.rs`): a forwarder that calls gn3's +`/api/search` (the default), and a native engine that searches a +xapian index directly from Rust. + +## One config key selects the engine + +`SEARCH_ENGINE` (config field `search_engine`, `src/config.rs`): + +- unset or `forward`: the gn3 forwarder — the default, and the + parity oracle while the native engine is being verified +- `native`: the native engine + +Selecting the engine is a config change; flipping back needs no +rebuild or redeploy. The native engine also needs `XAPIAN_DB_PATH` +pointing at a xapian index. On production that is `/var/lib/xapian`; +locally, an index built with the existing indexer: + + create-xapian-index <index-dir> <sql-uri> <sparql-uri> + +Index building stays with the existing indexer +(`index-genenetwork`); only searching moved into gn4. + +## The native engine reads the index, not the database + +Search itself never touches MariaDB — the engine opens the index +and parses the query (the grammar is gn3's: operators, boolean and +probabilistic prefixes, SI position ranges, `Hs`/`Mm` locations; +see `genenetwork3/api/search.py`). The database is used only to +enrich each hit with `locus`, the peak marker (`PublishXRef`), and +a database failure leaves `locus` null rather than failing the +search. An instance with no usable `SQL_URI` serves complete search +results with null loci. + +## Malformed queries: 422 with a typed body + +The native engine checks the parse and returns 422 `invalid_query` +with a machine-readable body instead of gn3's 500s: + +```json +{"error": {"type": "invalid_query", "message": "...", + "param": "query", + "detail": {"xapian_error_type": "QueryParserError"}}} +``` + +A client can read `type`/`param`/`message`, fix the query, and retry +— the committed `tests/search_selfcorrection.rs` pins that loop. + +## Known quirks + +- `locus: null` does not say whether the marker is absent or the + database was unreachable; carrying that reason is future work + (the response-format proposal). +- With `sort`, the forwarder ranks gn3's first 1000 matches; the + native engine retrieves the full match set before ranking, so + sorted results can differ in the tail. +- There is no runtime indicator of which engine is serving; the + config is the source of truth (a startup log line would fix this). |
