about summary refs log tree commit diff
path: root/src/search/mod.rs
blob: 3e2611e29fa8d5f2ad33d743dc0ff639ca13ef65 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
//! Search engine seam: the boundary between gn4's `/search` API surface
//! (parameter validation, envelope, error contract) and whatever
//! backend actually resolves a query.
//!
//! `/search` is currently a proxy: the [`Engine`] implementation in
//! [`gn3`] forwards to GeneNetwork3's xapian-backed `/api/search/`.
//! This module defines the seam so a native engine can be dropped in
//! behind it later without touching the route's contract.
//!
//! # Query grammar
//!
//! The query language below is the xapian query language as configured
//! by gn3 (`gn3/gn3/api/search.py`), reconstructed from source in
//! Stage A (see the phase-0 grammar spec). gn4 forwards `q` verbatim;
//! it does not clean or rewrite it. Any native engine must accept this
//! same grammar.
//!
//! Parser setup: English stemming (`xapian.Stem("en")`, `STEM_ALL_Z`),
//! so free-text terms match stemmed and case-insensitively; species
//! index prefix `XS`, chromosome index prefix `XC`.
//!
//! Boolean prefixes (exact terms, value lowercased before matching - the
//! index holds only lowercase boolean terms, so `dataset:BXDPublish` and
//! `dataset:bxdpublish` are the same query; see `LowercaseProcessor`):
//!
//! | Prefix | Field | Term |
//! |---|---|---|
//! | `author` | authors | `A` + value |
//! | `species` | species | `XS` + value |
//! | `group` | group | `XG` + value |
//! | `tissue` | tissue | `XI` + value |
//! | `dataset` | dataset | `XDS` + value |
//! | `symbol` | gene symbol | `XY` + value |
//! | `chr` | chromosome | `XC` + value |
//! | `peakchr` | peak chromosome | `XPC` + value |
//!
//! Probabilistic (free-text-weighted, BM25-scored) prefixes
//! (`add_prefix`), freely mixable with free text:
//! `description`, `rif` / `RIF`, `wiki` / `WIKI`.
//!
//! Numeric range prefixes (`NumberRangeProcessor`): `mean`, `peak`,
//! `position` / `pos`, `peakmb`, `additive`, `year`. Values are
//! `<num>` or `<num>..<num>`, either end open (`mean:..5`). `position`
//! additionally accepts SI suffixes (`k`/`m`/`g`) on base-pair
//! coordinates and expands a point location to ±50 kb; `Hs:<chr>:<pos>`
//! and `Mm:<chr>:<pos>` are species-location shorthands (human/mouse)
//! that AND species + chromosome + position, with `Hs` also trying a
//! human→mouse liftover.
//!
//! Operators: `AND`, `OR`, `NOT`, `XOR`, `NEAR`, `ADJ` (uppercase
//! only; lowercase forms are plain terms). There is no `&&` operator --
//! it is malformed and surfaces as a parser error from the backend.
//!
//! Default `type` values: `/search` defaults to `"phenotype"` (gn3's
//! own endpoint defaults to `"gene"`); gn4 accepts only `"phenotype"`
//! or `"gene"`. `limit` defaults to 20, capped at 100, and is sent to
//! the backend as `per_page`. An empty `q` is rejected by gn4's
//! validation (400 `invalid_parameter`) before the engine is reached.
//!
//! # Error contract
//!
//! The engine reports failures as [`SearchError`]; the route maps them
//! onto the shared `ApiError` shapes, one variant per existing code:
//! [`SearchError::InvalidQuery`] → 422 `invalid_query`,
//! [`SearchError::Unreachable`] → 502 `backend_unreachable`,
//! [`SearchError::Misbehaving`] → 502 `backend_misbehaving`,
//! [`SearchError::Backend`] → 502 `backend_error`, and
//! [`SearchError::Internal`] → 500 `internal_error`. The 400
//! `invalid_parameter` case is parameter validation and stays in the
//! route, before the engine is called.
//!
//! # Enrichment note
//!
//! [`SearchHit`]'s computed fields (`mean`, `additive`, `lrs`,
//! `geno_chr`/`geno_mb`) are NOT in the xapian index: gn3 fills them
//! from the database at query time. Any native engine must port those
//! enrichment queries -- that is the bulk of the real work of the port.
//! The seam deliberately keeps the shape `(q, type, limit) ->
//! Vec<SearchHit>`; how a native engine splits retrieval from
//! enrichment is its own private design, noted here only so the effort
//! estimate prices the enrichment in.
//!
//! # Trait now, two impls
//!
//! The phase-2 plan originally said "no trait yet" (a trait with one
//! impl is speculation). The overnight schedule overrides that: the
//! [`Engine`] trait is defined so the native engine can land behind
//! it. The gn3-forwarding implementation ([`gn3::Gn3`]) remains the
//! default backend; the in-process engine is opt-in via `SEARCH_ENGINE`
//! (see [`search`]).

use std::future::Future;

pub mod gn3;
pub mod gnindex;

/// Run a search through the configured engine: the gn3 forwarder by
/// default, the native xapian engine when `SEARCH_ENGINE=native`
/// (PORT-DESIGN §6 wiring). Selecting the engine is a config change,
/// so flipping back never needs a rebuild or a redeploy.
pub async fn search(
    q: &str,
    type_: &str,
    limit: u64,
    page: u64,
) -> Result<Vec<SearchHit>, SearchError> {
    match crate::config::Config::load().search_engine.as_str() {
        // The in-process engine, in the crate; `native` is its former name.
        "crate" | "native" => {
            gnindex::CrateEngine::from_config()
                .search(q, type_, limit, page)
                .await
        }
        // The gn3 proxy, asked over HTTP. Deleted together with gn3.
        "forward" => gn3::Gn3.search(q, type_, limit, page).await,
        // No default arm: an unrecognised value is a misconfiguration, and a
        // silent fall-through would hide it behind whichever engine happened to
        // be last in the match.
        other => Err(SearchError::Internal(format!(
            "SEARCH_ENGINE={other:?} is not an engine: expected \"crate\", \"native\" or \"forward\""
        ))),
    }
}

/// One search hit, in gn3's shape.
///
/// Every field is optional because gn3 omits computed values (`lrs`,
/// `geno_chr`/`geno_mb`) for traits that don't have them. Fields gn3
/// adds in future pass through via `extra`, keeping the proxy
/// transparent without freezing the schema to today's gn3.
pub use gn_search_engine::SearchHit;

/// A search-engine failure, in the vocabulary of the `/search` error
/// contract (see the module doc comment). Each variant carries the
/// detail text the route forwards in the `ApiError` body; the route
/// supplies the HTTP status, `code`, and title for each.
pub use gn_search_engine::SearchError;

/// A search backend: resolves a validated `(q, type, limit)` into hits.
///
/// One implementation today ([`gn3::Gn3`]); a native engine will be a
/// second. The route owns parameter validation before calling this, and
/// maps the returned [`SearchError`] onto the shared `ApiError` shapes.
pub trait Engine {
    /// Search for hits matching `q`. `type_` is one of `"phenotype"` or
    /// `"gene"` (already validated); `limit` is already capped. Returns
    /// the hits in gn3's shape, or a [`SearchError`] the route maps onto
    /// the `/search` error contract.
    fn search(
        &self,
        q: &str,
        type_: &str,
        limit: u64,
        page: u64,
    ) -> impl Future<Output = Result<Vec<SearchHit>, SearchError>> + Send;
}