about summary refs log tree commit diff
path: root/src
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-10 13:17:05 +0000
committerPjotr <wrk@bosa.lan>2026-11-10 13:17:05 +0000
commitde4f3601732e47f54b7e1a6423eb98a86ce55efb (patch)
tree0965c9ddde97fb141dc4248780875a4588314ee2 /src
parent7fa899b66f484593e36b175dc6daa5be1d03f2fd (diff)
downloadgenenetwork4-de4f3601732e47f54b7e1a6423eb98a86ce55efb.tar.gz
genes: Wikidata aliases, cached in gene-aliases.lmdb for seven days
A GeneNetwork trait page shows the gene's aliases next to the symbol,
and GN4 had no way to ask for them: gn-guile has a Wikidata lookup
(gn/db/sources/wikidata.scm) and nothing in GN4 did. This is that
lookup with the caching Wikidata deserves -- it is a shared public
service and an alias list is not news.

  * GET /genes/{symbol}/aliases: two SPARQL queries against
    WIKIDATA_ENDPOINT (the entity: a gene wdt:P31 wd:Q7187 in human,
    mouse or rat, labelled with the symbol; then its skos:altLabel s in
    English), cached in WIKIDATA_CACHE_DIR/gene-aliases.lmdb, an LMDB
    file (NO_SUB_DIR, 0600, so one file and LMDB's -lock companion
    rather than a directory of two).
  * TTL WIKIDATA_TTL_SECONDS, seven days by default. Past it the value
    is refetched; ?refresh=true forces that.
  * The label is matched case-insensitively, which the gn-guile query
    did not: human genes are labelled SHH and mouse ones Shh, so an
    exact match finds only one species. ?species=human now returns the
    ortholog's labels -- HLP3, HPE3 and the rest -- which are the ones a
    mouse trait page shows. With no species named the pick is
    deterministic (mouse, rat, human), so a repeated request cannot
    change entity.
  * A failed refresh keeps the last value: the answer says stale: true,
    the envelope is partial, and a note explains it. Nothing cached at
    all is a 502 that says so. An empty alias list and an unreachable
    upstream are different facts, and only one of them is about the
    gene.

Seven unit tests (key scoping, TTL including a clock that went backwards,
the query shape and quote-escaping, SPARQL flattening, an LMDB
round-trip that asserts the file is gene-aliases.lmdb, and
stale-on-failure with and without a cache) and two route tests (the
second call is served from the cache -- same fetched_at -- and the
species switch), which skip with a 502 assertion when there is no
network.
Diffstat (limited to 'src')
-rw-r--r--src/config.rs34
-rw-r--r--src/lib.rs2
-rw-r--r--src/routes/probesets.rs120
-rw-r--r--src/wikidata.rs486
4 files changed, 641 insertions, 1 deletions
diff --git a/src/config.rs b/src/config.rs
index b9f46dc..e744075 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -133,6 +133,16 @@ pub struct Config {
     /// output into (see src/rqtl.rs). Defaults to a "gn4-rqtl"
     /// directory under the system temp dir.
     pub rqtl_cache_dir: String,
+    /// LMDB directory holding Wikidata gene aliases (see src/wikidata.rs),
+    /// keyed by species and symbol. `WIKIDATA_CACHE_DIR`.
+    pub wikidata_cache_dir: String,
+    /// The SPARQL endpoint those aliases come from, `WIKIDATA_ENDPOINT`.
+    pub wikidata_endpoint: String,
+    /// How long a cached answer is trusted, in seconds
+    /// (`WIKIDATA_TTL_SECONDS`, default seven days). Past it the value is
+    /// refetched; if Wikidata is unreachable the old value is served and
+    /// marked stale.
+    pub wikidata_ttl: i64,
     /// Directory holding the genotype files (`GENOTYPE_FILES`): GN2's
     /// layout -- `genotype/<Group>.json` for the version list,
     /// `genotype/<stem>.geno`, `genotype/bimbam/<stem>_geno.txt` and
@@ -281,6 +291,21 @@ impl Config {
                 .to_string_lossy()
                 .into_owned(),
         );
+        // Wikidata aliases (src/wikidata.rs): an LMDB cache and the SPARQL
+        // endpoint it refreshes from. Seven days, because an alias list is
+        // not news.
+        values.insert(
+            "WIKIDATA_CACHE_DIR".to_string(),
+            std::env::temp_dir()
+                .join("gn4-wikidata")
+                .to_string_lossy()
+                .into_owned(),
+        );
+        values.insert(
+            "WIKIDATA_ENDPOINT".to_string(),
+            "https://query.wikidata.org/sparql".to_string(),
+        );
+        values.insert("WIKIDATA_TTL_SECONDS".to_string(), "604800".to_string());
 
         // Layers 2 and 3: config files, in increasing priority.
         for env_key in ["GN4_CONF", "GN4_SECRETS"] {
@@ -331,6 +356,9 @@ impl Config {
             "QTL2_SCRIPT_PATH",
             "QTL2_CACHE_DIR",
             "RQTL_CACHE_DIR",
+            "WIKIDATA_CACHE_DIR",
+            "WIKIDATA_ENDPOINT",
+            "WIKIDATA_TTL_SECONDS",
         ] {
             if let Ok(value) = std::env::var(key) {
                 values.insert(key.to_string(), value);
@@ -372,6 +400,9 @@ impl Config {
             qtl2_script_path: values["QTL2_SCRIPT_PATH"].clone(),
             qtl2_cache_dir: values["QTL2_CACHE_DIR"].clone(),
             rqtl_cache_dir: values["RQTL_CACHE_DIR"].clone(),
+            wikidata_cache_dir: values["WIKIDATA_CACHE_DIR"].clone(),
+            wikidata_endpoint: values["WIKIDATA_ENDPOINT"].clone(),
+            wikidata_ttl: values["WIKIDATA_TTL_SECONDS"].parse().unwrap_or(604800),
             genotype_files_dir: values["GENOTYPE_FILES"].clone(),
             sql_check_health: parse_switch(&values["SQL_CHECK_HEALTH"]),
             rqtl_max_concurrent: values["RQTL_MAX_CONCURRENT"]
@@ -616,6 +647,9 @@ mod tests {
             "RAVANAN_SCRATCH",
             "RQTL_WRAPPER_PATH",
             "RQTL_CACHE_DIR",
+            "WIKIDATA_CACHE_DIR",
+            "WIKIDATA_ENDPOINT",
+            "WIKIDATA_TTL_SECONDS",
         ] {
             if std::env::var(key).is_ok() {
                 eprintln!("skipping: {key} is set in the environment");
diff --git a/src/lib.rs b/src/lib.rs
index e573c92..caefdbf 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -27,6 +27,7 @@ mod rqtl;
 pub mod search;
 mod streaming;
 pub mod suggest;
+pub mod wikidata;
 
 use error::ApiError;
 use response::{Ctx, Envelope};
@@ -122,6 +123,7 @@ pub fn app() -> Router {
         .routes(routes!(routes::correlation::correlation))
         .routes(routes!(routes::probesets::probeset_by_name))
         .routes(routes!(routes::probesets::gene_traits))
+        .routes(routes!(routes::probesets::gene_aliases))
         .routes(routes!(routes::plot::plot_rqtl))
         .routes(routes!(routes::plot::plot_gemma))
         .routes(routes!(routes::phewas::group_phewas))
diff --git a/src/routes/probesets.rs b/src/routes/probesets.rs
index 42d341c..ce573b8 100644
--- a/src/routes/probesets.rs
+++ b/src/routes/probesets.rs
@@ -9,7 +9,12 @@
 //! are the indexed lookups: `ProbeSet.Name` and `ProbeSet.Symbol` both have
 //! one, and the answer carries the panel and the mapping statistics.
 //!
-//! What this returns is **metadata**: which datasets carry a probeset, and
+//! `/genes/{symbol}/aliases` is the annotation lookup beside them: Wikidata's
+//! `skos:altLabel`s for a gene, cached in LMDB for seven days (see
+//! src/wikidata.rs) and served stale rather than dropped when Wikidata is
+//! unreachable.
+//!
+//! What these return is **metadata**: which datasets carry a probeset, and
 //! what its QTL scan found in each. It deliberately does not return trait
 //! values -- those are per-dataset and authorized per dataset, and the `next`
 //! link goes to the endpoint that checks. So a token buys the index; the
@@ -24,9 +29,11 @@ use gnauth_macros::gnauth;
 
 use crate::auth::AuthToken;
 use crate::db::{self, ProbesetHit};
+use crate::config::Config;
 use crate::error::{ApiError, Unauthorized};
 use crate::response::{Ctx, Envelope, path_segment};
 use crate::suggest::{self, Link};
+use crate::wikidata::{self, GeneAliases, WikidataError};
 
 #[derive(Deserialize, utoipa::IntoParams)]
 pub struct ProbesetParams {
@@ -380,3 +387,114 @@ fn internal(message: String, rid: crate::response::RequestInfo) -> ApiError {
     )
     .with_request_id(rid)
 }
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct AliasParams {
+    /// Restrict the lookup to one species: human, mouse or rat. Without it
+    /// the first entity Wikidata finds in those taxa is used.
+    pub species: Option<String>,
+    /// Ask Wikidata again even if the cached answer is inside its seven-day
+    /// TTL. An operator's switch, not a caller's.
+    pub refresh: Option<bool>,
+}
+
+#[utoipa::path(get, path = "/genes/{symbol}/aliases",
+    summary = "A gene symbol's aliases from Wikidata, cached for seven days",
+    description = "The `skos:altLabel`s Wikidata records for the gene, in English: the alias \
+list a trait page shows next to the symbol. Two SPARQL queries (the entity, then its labels) \
+against WIKIDATA_ENDPOINT, kept in an LMDB cache (WIKIDATA_CACHE_DIR) for WIKIDATA_TTL_SECONDS \
+(seven days by default). When Wikidata cannot be reached the cached answer is served and marked \
+`stale` rather than reported as \"no aliases\" -- an empty list and an unreachable upstream mean \
+different things.",
+    params(("symbol" = String, Path, description = "Gene symbol, e.g. Shh"), AliasParams),
+    responses(
+        (status = 200, description = "The aliases, with where and when they came from", body = Envelope<GeneAliases>),
+        Unauthorized,
+        (status = 502, description = "Wikidata could not be reached and nothing was cached", body = ApiError)
+    )
+)]
+#[gnauth(token_only)]
+pub async fn gene_aliases(
+    ctx: Ctx,
+    Path(symbol): Path<String>,
+    Query(params): Query<AliasParams>,
+    _token: AuthToken,
+) -> Result<Json<Envelope<GeneAliases>>, ApiError> {
+    let rid = ctx.request_info();
+    let config = Config::load();
+    let file = wikidata::cache_file(&config.wikidata_cache_dir)
+        .to_string_lossy()
+        .into_owned();
+    let endpoint = config.wikidata_endpoint.clone();
+    let ttl = config.wikidata_ttl;
+    let wanted = symbol.clone();
+    let species = params.species.clone();
+    let refresh = params.refresh.unwrap_or(false);
+    let answer = tokio::task::spawn_blocking(move || {
+        wikidata::lookup(
+            std::path::Path::new(&file),
+            &endpoint,
+            ttl,
+            &wanted,
+            species.as_deref(),
+            refresh,
+        )
+    })
+    .await
+    .map_err(|error| internal(error.to_string(), rid.clone()))?
+    .map_err(|error| match error {
+        WikidataError::Unavailable(detail) => ApiError::new(
+            StatusCode::BAD_GATEWAY,
+            "wikidata_unavailable",
+            "Wikidata could not be reached",
+            format!("{detail}; nothing was cached for '{symbol}' to fall back on."),
+            "gene_aliases",
+        )
+        .with_request_id(rid.clone()),
+        WikidataError::Cache(detail) => ApiError::new(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "wikidata_cache_error",
+            "The alias cache could not be read",
+            detail,
+            "gene_aliases",
+        )
+        .with_request_id(rid.clone()),
+    })?;
+    let age_hours = (chrono_now() - answer.fetched_at).max(0) as f64 / 3600.0;
+    let mut envelope = ctx
+        .envelope(answer.clone())
+        .with_note(&format!(
+            "Wikidata's English `skos:altLabel`s for {} {}; the symbol itself is not repeated in \
+             `aliases`.",
+            answer.symbol,
+            match &answer.wikidata_id {
+                Some(id) => format!("({id})"),
+                None => "(no matching gene entity)".to_string(),
+            }
+        ))
+        .with_note(&format!(
+            "Cached in gene-aliases.lmdb for {} day(s); this answer was fetched {age_hours:.1} h \
+ago (add ?refresh=true to ask Wikidata again).",
+            ttl / 86_400
+        ));
+    if answer.stale {
+        envelope = envelope.partial(
+            "Wikidata could not be refreshed, so this is the last value that was fetched -- \
+             still the gene's aliases, but not today's.",
+        );
+    }
+    envelope = envelope.with_next(
+        &format!("/genes/{}/traits", path_segment(&symbol)),
+        "This gene's expression traits across datasets",
+    );
+    envelope = envelope.with_links(suggest::root_links());
+    Ok(Json(envelope))
+}
+
+/// Seconds since the epoch, for a reply's "fetched N hours ago".
+fn chrono_now() -> i64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|elapsed| elapsed.as_secs() as i64)
+        .unwrap_or(0)
+}
diff --git a/src/wikidata.rs b/src/wikidata.rs
new file mode 100644
index 0000000..2a69ddb
--- /dev/null
+++ b/src/wikidata.rs
@@ -0,0 +1,486 @@
+//! Gene aliases from Wikidata, cached locally in LMDB.
+//!
+//! GeneNetwork2/3 get a gene's aliases from Wikidata by two SPARQL queries:
+//! first the entity (a gene, `wdt:P31 wd:Q7187`, in human/mouse/rat, labelled
+//! with the symbol), then its `skos:altLabel`s. gn-guile does the same
+//! (`gn/db/sources/wikidata.scm`), which is where these queries come from.
+//!
+//! Wikidata is queried only when the cache is older than [`DEFAULT_TTL`]
+//! (seven days) -- it is a shared public service, and an alias list is not
+//! news -- and the answer is kept in LMDB so a restart, or a Wikidata outage,
+//! does not cost the caller the data. **A failed refresh keeps the last
+//! value**: the reply says it is stale rather than pretending the gene has no
+//! aliases, because an empty list and an unreachable upstream mean different
+//! things and only one of them is about the gene.
+//!
+//! The cache is a single LMDB file, `WIKIDATA_CACHE_DIR/gene-aliases.lmdb`
+//! (LMDB's no-subdir layout, so it is one file and its `-lock` companion
+//! rather than a directory of two): key = `"<species or any>:<symbol>"`,
+//! value = the [`Stored`] JSON.
+
+use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use lmdb::Transaction;
+use serde::{Deserialize, Serialize};
+
+/// Seven days, in seconds.
+pub const DEFAULT_TTL: i64 = 7 * 24 * 60 * 60;
+
+/// The cache file inside `WIKIDATA_CACHE_DIR`.
+pub const CACHE_FILE: &str = "gene-aliases.lmdb";
+
+/// The taxa the gene lookup accepts, and the QIDs they are.
+const TAXA: [(&str, &str); 3] = [
+    ("human", "Q15978631"),
+    ("mouse", "Q83310"),
+    ("rat", "Q184224"),
+];
+
+/// What the endpoint answers with.
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct GeneAliases {
+    /// The symbol as asked for.
+    pub symbol: String,
+    /// The Wikidata entity that matched, e.g. "Q24420953". Absent when
+    /// Wikidata knows no gene with this symbol in the accepted taxa.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub wikidata_id: Option<String>,
+    /// Which of human/mouse/rat it matched, when the request did not say.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub species: Option<String>,
+    /// `skos:altLabel`s, sorted, the symbol itself removed.
+    pub aliases: Vec<String>,
+    /// When Wikidata last answered, in Unix seconds.
+    pub fetched_at: i64,
+    /// True when Wikidata could not be reached and this is the cached answer.
+    pub stale: bool,
+}
+
+/// What is stored in LMDB: the answer without the per-request flags.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Stored {
+    pub symbol: String,
+    pub wikidata_id: Option<String>,
+    pub species: Option<String>,
+    pub aliases: Vec<String>,
+    pub fetched_at: i64,
+}
+
+/// Why aliases could not be produced at all.
+#[derive(Debug)]
+pub enum WikidataError {
+    /// Neither Wikidata nor the cache had anything.
+    Unavailable(String),
+    /// The cache could not be read or written.
+    Cache(String),
+}
+
+impl std::fmt::Display for WikidataError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            WikidataError::Unavailable(what) | WikidataError::Cache(what) => write!(f, "{what}"),
+        }
+    }
+}
+
+fn now() -> i64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|elapsed| elapsed.as_secs() as i64)
+        .unwrap_or(0)
+}
+
+/// The cache key: species-scoped when the request named one, so `?species=rat`
+/// and `?species=mouse` do not overwrite each other.
+pub fn key(symbol: &str, species: Option<&str>) -> String {
+    format!(
+        "{}:{}",
+        species.unwrap_or("any").to_lowercase(),
+        symbol.to_lowercase()
+    )
+}
+
+/// Whether a stored answer is still inside the TTL.
+pub fn is_fresh(stored: &Stored, ttl: i64, now: i64) -> bool {
+    now.saturating_sub(stored.fetched_at) < ttl
+}
+
+/// The gene entity query: a gene in one of the accepted taxa, labelled with
+/// the symbol. Binds `?species` when the caller named one.
+pub fn gene_id_query(symbol: &str, species: Option<&str>) -> String {
+    let taxa: Vec<&str> = match species {
+        Some(wanted) => TAXA
+            .iter()
+            .filter(|(name, _)| name.eq_ignore_ascii_case(wanted))
+            .map(|(_, qid)| *qid)
+            .collect(),
+        None => TAXA.iter().map(|(_, qid)| *qid).collect(),
+    };
+    let values: Vec<String> = taxa.iter().map(|qid| format!("(wd:{qid})")).collect();
+    format!(
+        "SELECT DISTINCT ?wikidata_id ?species WHERE {{\n  \
+           ?wikidata_id wdt:P31 wd:Q7187 ;\n               wdt:P703 ?species ;\n               \
+           rdfs:label ?label .\n  \
+           VALUES (?species) {{ {} }}\n  \
+           FILTER(LCASE(STR(?label)) = LCASE(\"{}\"))\n  \
+           FILTER(LANG(?label) = \"en\")\n}}",
+        values.join(" "),
+        symbol.replace('"', "")
+    )
+}
+
+/// The aliases query for one entity.
+pub fn aliases_query(wikidata_id: &str) -> String {
+    let id = wikidata_id.trim_start_matches("wd:").trim();
+    format!(
+        "SELECT DISTINCT ?alias WHERE {{\n  \
+           wd:{id} rdfs:label ?name ;\n            skos:altLabel ?alias .\n  \
+           FILTER(LANG(?name) = \"en\" && LANG(?alias) = \"en\")\n}}"
+    )
+}
+
+/// One row of a SPARQL JSON reply, reduced to its `value` strings.
+fn binding_values(body: &serde_json::Value, field: &str) -> Vec<String> {
+    body.get("results")
+        .and_then(|results| results.get("bindings"))
+        .and_then(|bindings| bindings.as_array())
+        .map(|rows| {
+            rows.iter()
+                .filter_map(|row| row.get(field)?.get("value")?.as_str())
+                .map(str::to_string)
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+/// The local QID from a Wikidata entity URL.
+fn qid_of(url: &str) -> String {
+    url.rsplit('/').next().unwrap_or(url).to_string()
+}
+
+/// The species a taxon QID names.
+fn species_of(qid: &str) -> Option<String> {
+    TAXA
+        .iter()
+        .find(|(_, taxon)| *taxon == qid)
+        .map(|(name, _)| (*name).to_string())
+}
+
+/// Fetch a gene's aliases from Wikidata: two SPARQL queries.
+fn fetch(
+    endpoint: &str,
+    symbol: &str,
+    species: Option<&str>,
+) -> Result<Stored, WikidataError> {
+    let ids = sparql(endpoint, &gene_id_query(symbol, species))?;
+    let rows: Vec<(String, Option<String>)> = binding_values(&ids, "wikidata_id")
+        .into_iter()
+        .map(|url| {
+            let qid = qid_of(&url);
+            (qid.clone(), None)
+        })
+        .collect();
+    let species_rows = binding_values(&ids, "species");
+    let mut entities: Vec<(String, Option<String>)> = rows
+        .into_iter()
+        .enumerate()
+        .map(|(index, (qid, _))| {
+            (qid, species_rows.get(index).and_then(|url| species_of(&qid_of(url))))
+        })
+        .collect();
+    // Deterministic: the species the caller named first, then mouse, rat,
+    // human -- the same gene in three species is three entities, and a reply
+    // that changes which one it picked would be worse than one that picks a
+    // fixed order.
+    let priority = |found: &Option<String>| -> u8 {
+        match found.as_deref() {
+            Some(name) if species.is_some_and(|wanted| name.eq_ignore_ascii_case(wanted)) => 0,
+            Some("mouse") => 1,
+            Some("rat") => 2,
+            Some("human") => 3,
+            _ => 4,
+        }
+    };
+    entities.sort_by_key(|(qid, found)| (priority(found), qid.clone()));
+    let Some((wikidata_id, found_species)) = entities.into_iter().next() else {
+        return Ok(Stored {
+            symbol: symbol.to_string(),
+            wikidata_id: None,
+            species: species.map(str::to_string),
+            aliases: Vec::new(),
+            fetched_at: now(),
+        });
+    };
+    let alias_body = sparql(endpoint, &aliases_query(&wikidata_id))?;
+    let mut aliases: Vec<String> = binding_values(&alias_body, "alias");
+    aliases.retain(|alias| !alias.eq_ignore_ascii_case(symbol) && !alias.trim().is_empty());
+    aliases.sort_by_key(|alias| alias.to_lowercase());
+    aliases.dedup();
+    Ok(Stored {
+        symbol: symbol.to_string(),
+        wikidata_id: Some(wikidata_id),
+        species: found_species,
+        aliases,
+        fetched_at: now(),
+    })
+}
+
+/// `POST query=…` to a SPARQL endpoint, asking for SPARQL JSON.
+fn sparql(endpoint: &str, query: &str) -> Result<serde_json::Value, WikidataError> {
+    let agent = ureq::Agent::config_builder()
+        .timeout_global(Some(std::time::Duration::from_secs(20)))
+        .build()
+        .new_agent();
+    let response = agent
+        .post(endpoint)
+        .header("Accept", "application/sparql-results+json")
+        .header("User-Agent", "genenetwork4 (+https://genenetwork.org)")
+        .send_form([("query", query)])
+        .map_err(|error| WikidataError::Unavailable(format!("{endpoint}: {error}")))?;
+    response
+        .into_body()
+        .read_json::<serde_json::Value>()
+        .map_err(|error| WikidataError::Unavailable(format!("{endpoint}: {error}")))
+}
+
+/// The LMDB environment: one file, `gene-aliases.lmdb`, via LMDB's no-subdir
+/// layout (which also creates `gene-aliases.lmdb-lock`, as LMDB always does).
+fn environment(file: &Path) -> Result<lmdb::Environment, WikidataError> {
+    if let Some(parent) = file.parent() {
+        std::fs::create_dir_all(parent)
+            .map_err(|error| WikidataError::Cache(format!("{}: {error}", parent.display())))?;
+    }
+    lmdb::Environment::new()
+        .set_max_dbs(2)
+        .set_map_size(16 * 1024 * 1024)
+        .set_flags(lmdb::EnvironmentFlags::NO_SUB_DIR)
+        .open_with_permissions(file, 0o600)
+        .map_err(|error| WikidataError::Cache(format!("{}: {error}", file.display())))
+}
+
+/// The cached answer for a key, if any.
+pub fn cached(file: &Path, key: &str) -> Result<Option<Stored>, WikidataError> {
+    let env = environment(file)?;
+    let db = env
+        .create_db(Some("aliases"), lmdb::DatabaseFlags::empty())
+        .map_err(|error| WikidataError::Cache(error.to_string()))?;
+    let txn = env
+        .begin_ro_txn()
+        .map_err(|error| WikidataError::Cache(error.to_string()))?;
+    match txn.get(db, &key) {
+        Ok(bytes) => {
+            let stored: Stored = serde_json::from_slice(bytes)
+                .map_err(|error| WikidataError::Cache(format!("{key}: {error}")))?;
+            Ok(Some(stored))
+        }
+        Err(lmdb::Error::NotFound) => Ok(None),
+        Err(error) => Err(WikidataError::Cache(error.to_string())),
+    }
+}
+
+/// Store an answer.
+pub fn store(file: &Path, key: &str, stored: &Stored) -> Result<(), WikidataError> {
+    let env = environment(file)?;
+    let db = env
+        .create_db(Some("aliases"), lmdb::DatabaseFlags::empty())
+        .map_err(|error| WikidataError::Cache(error.to_string()))?;
+    let value = serde_json::to_vec(stored)
+        .map_err(|error| WikidataError::Cache(format!("{key}: {error}")))?;
+    let mut txn = env
+        .begin_rw_txn()
+        .map_err(|error| WikidataError::Cache(error.to_string()))?;
+    txn.put(db, &key, &value, lmdb::WriteFlags::empty())
+        .map_err(|error| WikidataError::Cache(error.to_string()))?;
+    txn.commit()
+        .map_err(|error| WikidataError::Cache(error.to_string()))
+}
+
+/// Aliases for a symbol: cache when fresh, Wikidata when not, the last value
+/// when Wikidata fails.
+pub fn lookup(
+    file: &Path,
+    endpoint: &str,
+    ttl: i64,
+    symbol: &str,
+    species: Option<&str>,
+    refresh: bool,
+) -> Result<GeneAliases, WikidataError> {
+    let key = key(symbol, species);
+    let previous = cached(file, &key).unwrap_or(None);
+    if let Some(previous) = &previous {
+        if !refresh && is_fresh(previous, ttl, now()) {
+            return Ok(GeneAliases {
+                symbol: previous.symbol.clone(),
+                wikidata_id: previous.wikidata_id.clone(),
+                species: previous.species.clone(),
+                aliases: previous.aliases.clone(),
+                fetched_at: previous.fetched_at,
+                stale: false,
+            });
+        }
+    }
+    match fetch(endpoint, symbol, species) {
+        Ok(fresh) => {
+            // A cache that cannot be written is not a reason to fail the
+            // request; the answer is good and the next call refetches.
+            let _ = store(file, &key, &fresh);
+            Ok(GeneAliases {
+                symbol: fresh.symbol,
+                wikidata_id: fresh.wikidata_id,
+                species: fresh.species,
+                aliases: fresh.aliases,
+                fetched_at: fresh.fetched_at,
+                stale: false,
+            })
+        }
+        Err(error) => match previous {
+            Some(previous) => Ok(GeneAliases {
+                symbol: previous.symbol,
+                wikidata_id: previous.wikidata_id,
+                species: previous.species,
+                aliases: previous.aliases,
+                fetched_at: previous.fetched_at,
+                stale: true,
+            }),
+            None => Err(error),
+        },
+    }
+}
+
+/// The cache file for a configured `WIKIDATA_CACHE_DIR`.
+pub fn cache_file(configured: &str) -> PathBuf {
+    PathBuf::from(configured).join(CACHE_FILE)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_key_is_species_scoped_and_case_insensitive() {
+        assert_eq!(key("Shh", None), "any:shh");
+        assert_eq!(key("Shh", Some("Rat")), "rat:shh");
+        assert_ne!(key("Shh", Some("rat")), key("Shh", Some("mouse")));
+    }
+
+    #[test]
+    fn freshness_is_the_ttl() {
+        let stored = Stored {
+            symbol: "Shh".to_string(),
+            wikidata_id: Some("Q24420953".to_string()),
+            species: Some("rat".to_string()),
+            aliases: vec!["HHG1".to_string()],
+            fetched_at: 1_000_000,
+        };
+        assert!(is_fresh(&stored, DEFAULT_TTL, 1_000_000 + DEFAULT_TTL - 1));
+        assert!(!is_fresh(&stored, DEFAULT_TTL, 1_000_000 + DEFAULT_TTL));
+        // A clock that went backwards does not make the cache stale.
+        assert!(is_fresh(&stored, DEFAULT_TTL, 999_999));
+    }
+
+    #[test]
+    fn the_gene_query_binds_the_taxa_and_the_label() {
+        let query = gene_id_query("Shh", None);
+        assert!(query.contains("wdt:P31 wd:Q7187"), "{query}");
+        assert!(query.contains("wd:Q15978631"), "human: {query}");
+        assert!(query.contains("wd:Q83310"), "mouse: {query}");
+        assert!(query.contains("wd:Q184224"), "rat: {query}");
+        // The label is matched case-insensitively: human genes are labelled
+        // SHH, mouse ones Shh, and both are the same question.
+        assert!(query.contains("LCASE(STR(?label)) = LCASE(\"Shh\")"), "{query}");
+        assert!(query.contains("LANG(?label) = \"en\""), "{query}");
+        let mouse_only = gene_id_query("Shh", Some("mouse"));
+        assert!(mouse_only.contains("wd:Q83310"), "{mouse_only}");
+        assert!(!mouse_only.contains("wd:Q184224"), "{mouse_only}");
+        // A quote in the symbol cannot break out of the literal.
+        assert!(!gene_id_query("a\"b", None).contains("\"a\"b\")"));
+    }
+
+    #[test]
+    fn the_aliases_query_accepts_a_bare_or_prefixed_id() {
+        assert!(aliases_query("Q24420953").contains("wd:Q24420953"));
+        assert!(aliases_query("wd:Q24420953").contains("wd:Q24420953"));
+        assert!(!aliases_query("wd:Q24420953").contains("wd:wd:"));
+    }
+
+    #[test]
+    fn sparql_bindings_are_flattened() {
+        let body = serde_json::json!({
+            "results": {"bindings": [
+                {"alias": {"type": "literal", "value": "HHG1"}},
+                {"alias": {"type": "literal", "value": "TPT"}},
+                {}
+            ]}
+        });
+        assert_eq!(binding_values(&body, "alias"), vec!["HHG1", "TPT"]);
+        assert!(binding_values(&body, "nonesuch").is_empty());
+        assert_eq!(qid_of("http://www.wikidata.org/entity/Q24420953"), "Q24420953");
+        assert_eq!(species_of("Q83310"), Some("mouse".to_string()));
+        assert_eq!(species_of("Q1"), None);
+    }
+
+    #[test]
+    fn the_cache_round_trips_through_lmdb() {
+        let dir = std::env::temp_dir().join(format!("gn4-wikidata-test-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let dir = cache_file(&dir.to_string_lossy());
+        let stored = Stored {
+            symbol: "Shh".to_string(),
+            wikidata_id: Some("Q24420953".to_string()),
+            species: Some("rat".to_string()),
+            aliases: vec!["HHG1".to_string(), "TPT".to_string()],
+            fetched_at: 1_700_000_000,
+        };
+        store(&dir, &key("Shh", None), &stored).unwrap();
+        let back = cached(&dir, &key("Shh", None)).unwrap().unwrap();
+        assert_eq!(back.aliases, stored.aliases);
+        assert_eq!(back.wikidata_id, stored.wikidata_id);
+        assert!(cached(&dir, &key("Nosuch", None)).unwrap().is_none());
+        assert!(dir.ends_with("gene-aliases.lmdb"), "{}", dir.display());
+        assert!(dir.is_file(), "one file, as asked: {}", dir.display());
+        if let Some(parent) = dir.parent() {
+            std::fs::remove_dir_all(parent).ok();
+        }
+    }
+
+    /// Wikidata is a public service; a test that cannot reach it proves the
+    /// stale path rather than failing.
+    #[test]
+    fn an_unreachable_endpoint_serves_the_last_value() {
+        let dir = std::env::temp_dir().join(format!("gn4-wikidata-stale-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let dir = cache_file(&dir.to_string_lossy());
+        let stored = Stored {
+            symbol: "Shh".to_string(),
+            wikidata_id: Some("Q24420953".to_string()),
+            species: Some("rat".to_string()),
+            aliases: vec!["HHG1".to_string()],
+            // Long expired, so the refresh is attempted.
+            fetched_at: 1_600_000_000,
+        };
+        store(&dir, &key("Shh", None), &stored).unwrap();
+        let answer = lookup(
+            &dir,
+            "http://127.0.0.1:1/sparql",
+            DEFAULT_TTL,
+            "Shh",
+            None,
+            false,
+        )
+        .unwrap();
+        assert!(answer.stale, "an unreachable upstream keeps the last value");
+        assert_eq!(answer.aliases, vec!["HHG1".to_string()]);
+        // And with nothing cached, the failure is reported.
+        let empty = std::env::temp_dir().join(format!("gn4-wikidata-none-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&empty);
+        let empty = cache_file(&empty.to_string_lossy());
+        assert!(lookup(&empty, "http://127.0.0.1:1/sparql", DEFAULT_TTL, "Nosuch", None, false).is_err());
+        // The file and LMDB's lock companion; remove the parent directories.
+        for path in [&dir, &empty] {
+            if let Some(parent) = path.parent() {
+                std::fs::remove_dir_all(parent).ok();
+            }
+        }
+    }
+}