about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorAlexander_Kabui <alexanderkabua@gmail.com>2026-10-08 07:28:20 +0300
committerAlexander_Kabui <alexanderkabua@gmail.com>2026-10-08 07:28:20 +0300
commit1a03e984c2e37ad0c8ec50efe6353548af7d222d (patch)
tree12fe38c2040e62f4f41d7152041c4f1c73858fc0 /docs
parent3c759f2e28b4dec1561b91900a7100975a74ccc5 (diff)
downloadgenenetwork4-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.md61
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).