Skip to main content

qualia_core_db/domains/geospatial/adapters/
sparql_adapter.rs

1use crate::domains::geospatial::adapters::{AdapterHttpRequest, DataAdapter};
2use crate::net::disclosure::NetworkDisclosureRegistry;
3
4/// Adapter for Semantic Web RDF / SPARQL endpoints (e.g. Wikidata).
5pub struct SparqlAdapter {
6    pub id: &'static str,
7    pub endpoint: String,
8}
9
10/// Build a provenance quin with the crate's canonical 5-field XOR parity checksum.
11fn quin(s: u64, p: u64, o: u64) -> crate::NQuin {
12    let context = 0u64;
13    let metadata = 0u64;
14    crate::NQuin {
15        subject: s,
16        predicate: p,
17        object: o,
18        context,
19        metadata,
20        parity: crate::NQuin::calculate_parity(s, p, o, context, metadata),
21    }
22}
23
24impl SparqlAdapter {
25    /// Creates a default `SparqlAdapter`.
26    pub fn new(id: &'static str, endpoint: &str) -> Self {
27        Self {
28            id,
29            endpoint: endpoint.to_string(),
30        }
31    }
32
33    /// Parse a standard SPARQL 1.1 Query Results JSON response (e.g. from Wikidata
34    /// or any generic SPARQL endpoint) into provenance `NQuin`s.
35    ///
36    /// The mapping is generic and deterministic so the resulting quins are queryable
37    /// by the SPARQL layer, which hashes IRIs with the same `generate_60bit_token`:
38    ///
39    /// For each `results.bindings` row `i` (iterating `head.vars` in declared order):
40    /// * subject = the value of the FIRST variable whose binding is `type == "uri"`;
41    ///   if the row binds no URI, subject = `generate_60bit_token("urn:sparql:row:{i}")`.
42    /// * for every OTHER bound variable `v` in the row: predicate =
43    ///   `generate_60bit_token("urn:sparql:var:{v}")`, object =
44    ///   `generate_60bit_token(binding.value)`, emitting `quin(subject, predicate, object)`.
45    ///
46    /// If `results` or `results.bindings` are absent, an empty `Vec` is returned
47    /// (not an error). `Err` is only returned when `body` is not valid JSON.
48    pub fn parse_features(&self, body: &str) -> Result<Vec<crate::NQuin>, String> {
49        use crate::query::lexicon::generate_60bit_token;
50
51        let json: serde_json::Value = serde_json::from_str(body).map_err(|e| e.to_string())?;
52
53        // Ordered list of variable names from head.vars (deterministic subject selection).
54        let vars: Vec<String> = json
55            .get("head")
56            .and_then(|h| h.get("vars"))
57            .and_then(|v| v.as_array())
58            .map(|arr| {
59                arr.iter()
60                    .filter_map(|v| v.as_str().map(|s| s.to_string()))
61                    .collect()
62            })
63            .unwrap_or_default();
64
65        // Absent results / bindings => empty Vec, not an error.
66        let bindings = match json
67            .get("results")
68            .and_then(|r| r.get("bindings"))
69            .and_then(|b| b.as_array())
70        {
71            Some(b) => b,
72            None => return Ok(Vec::new()),
73        };
74
75        let mut quins = Vec::new();
76
77        for (i, row) in bindings.iter().enumerate() {
78            // Pick subject: first head var bound in this row with type == "uri".
79            let mut subject_var: Option<&str> = None;
80            for v in &vars {
81                if let Some(binding) = row.get(v.as_str()) {
82                    if binding.get("type").and_then(|t| t.as_str()) == Some("uri") {
83                        subject_var = Some(v.as_str());
84                        break;
85                    }
86                }
87            }
88
89            let subject = match subject_var {
90                Some(v) => {
91                    let val = row
92                        .get(v)
93                        .and_then(|b| b.get("value"))
94                        .and_then(|v| v.as_str())
95                        .unwrap_or("");
96                    generate_60bit_token(val.as_bytes())
97                }
98                None => generate_60bit_token(format!("urn:sparql:row:{}", i).as_bytes()),
99            };
100
101            // Emit a quin for every OTHER bound variable in this row.
102            for v in &vars {
103                if Some(v.as_str()) == subject_var {
104                    continue;
105                }
106                let value = match row
107                    .get(v.as_str())
108                    .and_then(|b| b.get("value"))
109                    .and_then(|v| v.as_str())
110                {
111                    Some(val) => val,
112                    None => continue, // variable not bound in this row
113                };
114                let predicate = generate_60bit_token(format!("urn:sparql:var:{}", v).as_bytes());
115                let object = generate_60bit_token(value.as_bytes());
116                quins.push(quin(subject, predicate, object));
117            }
118        }
119
120        Ok(quins)
121    }
122}
123
124impl DataAdapter for SparqlAdapter {
125    fn adapter_id(&self) -> &'static str {
126        self.id
127    }
128
129    fn build_fetch_request(
130        &self,
131        bbox: (f64, f64, f64, f64),
132        _time_range: (u64, u64),
133        registry: &NetworkDisclosureRegistry,
134    ) -> Result<AdapterHttpRequest, String> {
135        if !registry.check_egress_consent(self.adapter_id(), &self.endpoint) {
136            return Err(format!(
137                "Consent denied or unregistered for SPARQL endpoint {}",
138                self.endpoint
139            ));
140        }
141
142        // Construct geospatial SPARQL query. Using wdt:P625 for Earth-based coordinates.
143        // Bounding box: west, south, east, north -> bbox.0, bbox.1, bbox.2, bbox.3
144        let sparql_query = format!(
145            "SELECT ?item ?itemLabel ?location WHERE {{
146  ?item wdt:P625 ?location.
147  SERVICE wikibase:box {{
148    ?item wdt:P625 ?location.
149    bd:serviceParam wikibase:cornerSouthWest \"Point({} {})\"^^geo:wktLiteral.
150    bd:serviceParam wikibase:cornerNorthEast \"Point({} {})\"^^geo:wktLiteral.
151  }}
152  SERVICE wikibase:label {{ bd:serviceParam wikibase:language \"[AUTO_LANGUAGE],en\". }}
153}}",
154            bbox.0, bbox.1, bbox.2, bbox.3
155        );
156
157        let url = format!(
158            "{}?query={}&format=json",
159            self.endpoint,
160            urlencoding::encode(&sparql_query)
161        );
162
163        Ok(AdapterHttpRequest::get(url, "SPARQL"))
164    }
165
166    fn parse_response(&self, body: &str) -> Result<Vec<crate::NQuin>, String> {
167        self.parse_features(body)
168    }
169
170    fn primary_endpoint(&self) -> &str {
171        &self.endpoint
172    }
173
174    fn estimate_tile_count(&self, _bbox: (f64, f64, f64, f64)) -> u32 {
175        1 // A single complex SPARQL query.
176    }
177}
178
179#[cfg(test)]
180mod tests {
181    use super::*;
182
183    #[test]
184    fn test_sparql_adapter_consent_denied() {
185        let registry = NetworkDisclosureRegistry::new();
186        let adapter = SparqlAdapter::new("sparql_adapter", "https://query.wikidata.org/sparql");
187
188        let res = adapter.fetch_region((0.0, 0.0, 1.0, 1.0), (0, 0), &registry);
189        assert!(res.is_err());
190    }
191
192    #[test]
193    fn test_sparql_results_parse_features() {
194        use crate::query::lexicon::generate_60bit_token;
195
196        let body = r#"{"head":{"vars":["item","itemLabel","coord"]},
197 "results":{"bindings":[
198   {"item":{"type":"uri","value":"http://www.wikidata.org/entity/Q42"},
199    "itemLabel":{"type":"literal","value":"Douglas Adams"},
200    "coord":{"type":"literal","value":"Point(-0.13 51.5)"}},
201   {"item":{"type":"uri","value":"http://www.wikidata.org/entity/Q64"},
202    "itemLabel":{"type":"literal","value":"Berlin"}}
203 ]}}"#;
204
205        let adapter = SparqlAdapter::new("sparql_adapter", "https://query.wikidata.org/sparql");
206        let quins = adapter.parse_features(body).expect("parse should succeed");
207
208        // Row1 (Q42): itemLabel + coord => 2 quins. Row2 (Q64): itemLabel => 1 quin. Total 3.
209        assert_eq!(quins.len(), 3, "expected 3 quins, got {}", quins.len());
210
211        // The Q42 subject must have an `urn:sparql:var:itemLabel` quin with the Douglas Adams value.
212        let q42_subject = generate_60bit_token(b"http://www.wikidata.org/entity/Q42");
213        let label_pred = generate_60bit_token(b"urn:sparql:var:itemLabel");
214        let douglas_obj = generate_60bit_token(b"Douglas Adams");
215
216        let found = quins.iter().any(|q| {
217            q.subject == q42_subject
218                && q.predicate == label_pred
219                && q.object == douglas_obj
220                && q.verify_ecc_parity()
221                && q.parity == (q.subject ^ q.predicate ^ q.object ^ q.context ^ q.metadata)
222        });
223        assert!(found, "expected Q42 itemLabel=Douglas Adams quin not found");
224    }
225}