Skip to main content

rete_core/sparql/
diag.rs

1//! Query diagnostics: a side channel for the expression **type errors** that
2//! SPARQL silently resolves: a FILTER or HAVING drops the row (an error stays an
3//! error through `!`), BIND, projection and ORDER BY see an unbound value.
4//!
5//! `FILTER(CONTAINS(?iri, "x"))` is not unsupported — it is a type error,
6//! because CONTAINS takes string literals and an IRI is not one, and the spec
7//! says a FILTER whose expression errors drops the row. That is correct and it
8//! stays: results are never changed by this module. What changes is that the error is
9//! *counted*, so a query that came back empty can say why.
10//!
11//! Recording happens only on the error path (and, for the case-sensitivity
12//! hint, once per function per query on the no-match path), into a
13//! thread-local sink — SPARQL evaluation is single-threaded, and a
14//! thread-local keeps two queries running on two server threads from
15//! mixing their warnings. The sink is bounded: one entry per
16//! `(function, argument position, argument kind)`, holding a count and the
17//! first offending value.
18
19use std::cell::RefCell;
20
21use super::{ArithOp, Builtin, FExpr, Op, QueryOutput};
22
23/// Where a type error was raised: a built-in function, or an operator
24/// (`+ - * /`, a comparison, `IN`), which SPARQL defines as functions too
25/// (`op:numeric-add`, `op:numeric-equal`, …) but which have no call syntax.
26#[derive(Debug, Clone, Copy, PartialEq, Eq)]
27pub(crate) enum Site {
28    Fn(Builtin),
29    /// The operator's SPARQL spelling: `+`, `<=`, `IN`, …
30    Op(&'static str),
31}
32
33impl From<Builtin> for Site {
34    fn from(f: Builtin) -> Self {
35        Site::Fn(f)
36    }
37}
38
39impl Site {
40    pub(crate) fn arith(op: ArithOp) -> Site {
41        Site::Op(match op {
42            ArithOp::Add => "+",
43            ArithOp::Sub => "-",
44            ArithOp::Mul => "*",
45            ArithOp::Div => "/",
46        })
47    }
48
49    pub(crate) fn compare(op: Op) -> Site {
50        Site::Op(match op {
51            Op::Eq => "=",
52            Op::Ne => "!=",
53            Op::Lt => "<",
54            Op::Le => "<=",
55            Op::Gt => ">",
56            Op::Ge => ">=",
57        })
58    }
59
60    fn name(self) -> &'static str {
61        match self {
62            Site::Fn(f) => fn_name(f),
63            Site::Op(sym) => sym,
64        }
65    }
66
67    /// The family a site belongs to, which decides the hint.
68    fn family(self) -> Family {
69        match self {
70            Site::Fn(Builtin::Abs | Builtin::Ceil | Builtin::Floor | Builtin::Round) => {
71                Family::Numeric
72            }
73            Site::Op("+" | "-" | "*" | "/") => Family::Numeric,
74            Site::Op(_) => Family::Compare,
75            Site::Fn(Builtin::Lang | Builtin::Datatype) => Family::LiteralAccessor,
76            Site::Fn(Builtin::StrDt | Builtin::StrLang) => Family::Constructor,
77            Site::Fn(_) => Family::Other,
78        }
79    }
80}
81
82#[derive(Debug, Clone, Copy, PartialEq, Eq)]
83enum Family {
84    Numeric,
85    Compare,
86    LiteralAccessor,
87    Constructor,
88    Other,
89}
90
91/// How serious a [`QueryWarning`] is.
92#[derive(Debug, Clone, Copy, PartialEq, Eq)]
93#[non_exhaustive]
94pub enum WarningSeverity {
95    /// A SPARQL type error was raised and silently absorbed (FILTER drops the
96    /// row, BIND → unbound). The results are spec-correct; the query probably is not
97    /// what its author meant.
98    TypeError,
99    /// No error happened; a guess at why a query came back empty (for example,
100    /// string matching is case-sensitive). Phrased as a suggestion.
101    Hint,
102}
103
104impl WarningSeverity {
105    /// `"type-error"` or `"hint"` — the JSON spelling.
106    pub fn as_str(self) -> &'static str {
107        match self {
108            WarningSeverity::TypeError => "type-error",
109            WarningSeverity::Hint => "hint",
110        }
111    }
112}
113
114/// One diagnostic about a query evaluation: a counted class of type errors, or
115/// a hint. Returned by [`eval_query_with_warnings`](super::eval_query_with_warnings).
116#[derive(Debug, Clone, PartialEq, Eq)]
117#[non_exhaustive]
118pub struct QueryWarning {
119    pub severity: WarningSeverity,
120    /// The SPARQL function name, upper-case (`"CONTAINS"`), or the operator's
121    /// spelling for an operator: `+` `-` `*` `/`, `=` `!=` `<` `<=` `>` `>=`,
122    /// `IN`.
123    pub function: String,
124    /// 1-based argument position the problem is about (0 = not argument-specific).
125    /// For an operator, 1 is the left operand and 2 the right one.
126    pub argument: usize,
127    /// What the argument was: `iri`, `blank-node`, `quoted-triple`, `numeric`,
128    /// `typed-literal`, `string`, `language-tagged`, `invalid-number`,
129    /// `language-mismatch`, `unbound`, `invalid-regex`, `not-a-datetime`,
130    /// `division-by-zero` (argument 2 of `/`), `incomparable` (a comparison
131    /// whose two operands no operator is defined for; argument 0), or, for the
132    /// hints, `case-sensitive` and `string-vs-number` (an `=` / `!=` / `IN`
133    /// that found a string unequal to the number its text spells; argument 0).
134    pub kind: String,
135    /// How many evaluations raised this error (an evaluation is one row reaching
136    /// the expression; LIMIT / ASK stop early, so this is not a data count).
137    pub count: u64,
138    /// The first offending value, truncated to 80 characters (plus `…`).
139    pub sample: Option<String>,
140    /// A short, actionable suggestion.
141    pub hint: String,
142    /// The whole warning as one plain-language sentence.
143    pub message: String,
144}
145
146/// Samples are cut to this many characters (plus `…`).
147const SAMPLE_CHARS: usize = 80;
148
149#[derive(Debug, Clone, Copy, PartialEq, Eq)]
150pub(crate) enum ArgKind {
151    Iri,
152    Blank,
153    QuotedTriple,
154    Numeric,
155    TypedLiteral,
156    LangMismatch,
157    Unbound,
158    InvalidRegex,
159    NotDatetime,
160    /// A string literal (plain or `xsd:string`) where a number, a literal
161    /// accessor's operand or a simple literal was needed.
162    StringLit,
163    /// A language-tagged literal where a simple literal was needed.
164    LangTagged,
165    /// A literal of a numeric datatype whose lexical form is not a number.
166    InvalidNumber,
167    /// The divisor of `/` was zero.
168    DivByZero,
169    /// A comparison's two operands are a pair §17.3 defines no operator for
170    /// (a string and a number under `<`, two IRIs under `<`, two different
171    /// literals of an unknown datatype under `=`). Not argument-specific.
172    Incomparable,
173    /// Not an error: `=` / `!=` / `IN` compared a string with a number whose
174    /// value the string's text spells (`"2020" = 2020`), which is false.
175    StringVsNumber,
176}
177
178impl ArgKind {
179    fn as_str(self) -> &'static str {
180        match self {
181            ArgKind::Iri => "iri",
182            ArgKind::Blank => "blank-node",
183            ArgKind::QuotedTriple => "quoted-triple",
184            ArgKind::Numeric => "numeric",
185            ArgKind::TypedLiteral => "typed-literal",
186            ArgKind::LangMismatch => "language-mismatch",
187            ArgKind::Unbound => "unbound",
188            ArgKind::InvalidRegex => "invalid-regex",
189            ArgKind::NotDatetime => "not-a-datetime",
190            ArgKind::StringLit => "string",
191            ArgKind::LangTagged => "language-tagged",
192            ArgKind::InvalidNumber => "invalid-number",
193            ArgKind::DivByZero => "division-by-zero",
194            ArgKind::Incomparable => "incomparable",
195            ArgKind::StringVsNumber => "string-vs-number",
196        }
197    }
198}
199
200struct Entry {
201    site: Site,
202    pos: usize,
203    kind: ArgKind,
204    count: u64,
205    sample: String,
206    /// Kind-specific detail: a datatype, the two language tags, a regex error.
207    detail: String,
208}
209
210/// Bits of the case-sensitivity probe ([`note_no_match`]).
211pub(crate) const MISS_CONTAINS: u8 = 1;
212pub(crate) const MISS_STRSTARTS: u8 = 2;
213pub(crate) const MISS_STRENDS: u8 = 4;
214pub(crate) const MISS_REGEX: u8 = 8;
215
216#[derive(Default)]
217struct Sink {
218    entries: Vec<Entry>,
219    /// Constant needles of string predicates that returned `false` on valid
220    /// string arguments at least once: `(function, needle)`.
221    misses: Vec<(Builtin, String)>,
222    /// The union default graph was built by merging every graph's triples.
223    union_merged: bool,
224}
225
226thread_local! {
227    static SINK: RefCell<Sink> = RefCell::new(Sink::default());
228}
229
230/// Start a fresh diagnostic scope (drops anything a previous query left).
231pub(crate) fn begin() {
232    SINK.with(|s| {
233        let mut s = s.borrow_mut();
234        s.entries.clear();
235        s.misses.clear();
236        s.union_merged = false;
237    });
238}
239
240/// What a thread's diagnostic scope holds, to hand to another thread's.
241#[cfg_attr(not(feature = "parallel"), allow(dead_code))]
242pub(crate) struct Taken {
243    entries: Vec<Entry>,
244    misses: Vec<(Builtin, String)>,
245}
246
247/// Empty the calling thread's scope (a worker thread of a query run as
248/// shards, when it ends).
249#[cfg_attr(not(feature = "parallel"), allow(dead_code))]
250pub(crate) fn take() -> Taken {
251    SINK.with(|s| {
252        let mut s = s.borrow_mut();
253        Taken {
254            entries: std::mem::take(&mut s.entries),
255            misses: std::mem::take(&mut s.misses),
256        }
257    })
258}
259
260/// Add another thread's records to the calling thread's scope: the same
261/// `(site, position, kind)` adds its count, as [`record`] does.
262#[cfg_attr(not(feature = "parallel"), allow(dead_code))]
263pub(crate) fn absorb(taken: Taken) {
264    SINK.with(|s| {
265        let mut s = s.borrow_mut();
266        for e in taken.entries {
267            match s
268                .entries
269                .iter_mut()
270                .find(|h| h.site == e.site && h.pos == e.pos && h.kind == e.kind)
271            {
272                Some(have) => have.count += e.count,
273                None => s.entries.push(e),
274            }
275        }
276        for m in taken.misses {
277            if !s.misses.contains(&m) {
278                s.misses.push(m);
279            }
280        }
281    });
282}
283
284/// Record that the union default graph was built by merging every graph's
285/// triples into one index: the file has no quad index with graph-last orders
286/// to stream it from, so the query reads every graph.
287#[cold]
288#[inline(never)]
289pub(crate) fn union_materialized() {
290    SINK.with(|s| s.borrow_mut().union_merged = true);
291}
292
293/// Record one type error. `describe` builds `(sample, detail)` and runs only
294/// for the first occurrence of a `(func, pos, kind)` key.
295#[cold]
296#[inline(never)]
297pub(crate) fn record(
298    site: impl Into<Site>,
299    pos: usize,
300    kind: ArgKind,
301    describe: impl FnOnce() -> (String, String),
302) {
303    let site = site.into();
304    SINK.with(|s| {
305        let mut s = s.borrow_mut();
306        if let Some(e) = s
307            .entries
308            .iter_mut()
309            .find(|e| e.site == site && e.pos == pos && e.kind == kind)
310        {
311            e.count += 1;
312            return;
313        }
314        let (sample, detail) = describe();
315        s.entries.push(Entry {
316            site,
317            pos,
318            kind,
319            count: 1,
320            sample: truncate(&sample),
321            detail,
322        });
323    });
324}
325
326/// Record that a string predicate returned no match on valid string
327/// arguments. Called once per function per query (the caller keeps a bit in
328/// `Ctx`); the needle is kept only when it is a constant in the query.
329#[cold]
330#[inline(never)]
331pub(crate) fn note_no_match(func: Builtin, needle: &FExpr) {
332    if let FExpr::Const(c) = needle {
333        let lex = crate::terms::literal_lexical(c).unwrap_or_else(|| c.clone());
334        SINK.with(|s| s.borrow_mut().misses.push((func, lex)));
335    }
336}
337
338/// A string function rejected the bound term `token` at 1-based `pos`.
339#[cold]
340#[inline(never)]
341pub(crate) fn bad_arg(func: Builtin, pos: usize, token: &str) {
342    record(func, pos, kind_of(token), || {
343        (token.to_string(), detail_of(token))
344    });
345}
346
347/// Both arguments of a binary string function are strings, but argument 2
348/// carries a language tag that argument 1 does not share (§17.4.3).
349#[cold]
350#[inline(never)]
351pub(crate) fn lang_mismatch(func: Builtin, text: &str, pat: &str) {
352    record(func, 2, ArgKind::LangMismatch, || {
353        let tag = |t: &str| match crate::terms::lang_tag(t).filter(|l| !l.is_empty()) {
354            Some(l) => format!("@{l}"),
355            None => "no tag".to_string(),
356        };
357        (pat.to_string(), format!("{} vs {}", tag(pat), tag(text)))
358    });
359}
360
361/// The argument at 1-based `pos` is the variable `var`, unbound in this row.
362#[cold]
363#[inline(never)]
364pub(crate) fn unbound(site: impl Into<Site>, pos: usize, var: &str) {
365    record(site, pos, ArgKind::Unbound, || {
366        (format!("?{var}"), String::new())
367    });
368}
369
370/// The REGEX / REPLACE pattern does not compile.
371#[cold]
372#[inline(never)]
373pub(crate) fn invalid_regex(func: Builtin, pattern: &str, flags: &str) {
374    record(func, 2, ArgKind::InvalidRegex, || {
375        (
376            pattern.to_string(),
377            crate::row::Resolver::regex_error(pattern, flags),
378        )
379    });
380}
381
382/// A date/time accessor got a value that does not parse as an xsd:dateTime.
383#[cold]
384#[inline(never)]
385pub(crate) fn bad_datetime(func: Builtin, token: &str) {
386    record(func, 1, ArgKind::NotDatetime, || {
387        let detail = match crate::terms::literal_datatype(token) {
388            Some(dt) if token.starts_with('"') => short_dt(&dt),
389            _ => kind_of(token).as_str().to_string(),
390        };
391        (token.to_string(), detail)
392    });
393}
394
395/// A numeric function or an arithmetic operator got a term that is not a
396/// number: a literal of a numeric datatype with a valid lexical form is one,
397/// a string is not, whatever its text.
398#[cold]
399#[inline(never)]
400pub(crate) fn not_a_number(site: impl Into<Site>, pos: usize, token: &str) {
401    let kind = match term_kind(token) {
402        ArgKind::Numeric => ArgKind::InvalidNumber,
403        k => k,
404    };
405    record(site, pos, kind, || {
406        (token.to_string(), detail_of_any(token))
407    });
408}
409
410/// A comparison operator (`=` … `>=`, `IN`) got two operands §17.3 defines it
411/// for no pair of: a type error.
412#[cold]
413#[inline(never)]
414pub(crate) fn incomparable(site: Site, a: &str, b: &str) {
415    record(site, 0, ArgKind::Incomparable, || {
416        (
417            format!("{a} vs {b}"),
418            format!("{} vs {}", operand_kind(a), operand_kind(b)),
419        )
420    });
421}
422
423/// `=` / `!=` / `IN` compared a string with a number: unequal, as SPARQL says.
424/// Counted (as a hint, not an error) only when the string's text spells that
425/// number — `"2020" = 2020` — the case whose answer looks wrong to a reader.
426pub(crate) fn string_vs_number(site: Site, a: &str, b: &str) {
427    let (s, n) = if a.starts_with('"') && super::value::numeric(a).is_none() {
428        (a, b)
429    } else {
430        (b, a)
431    };
432    let (Some(text), Some(num)) = (crate::terms::as_number(s), super::value::numeric(n)) else {
433        return;
434    };
435    if text == num {
436        record(site, 0, ArgKind::StringVsNumber, || {
437            (format!("{a} vs {b}"), String::new())
438        });
439    }
440}
441
442/// How an operand reads in a comparison warning: `a string`, `xsd:integer`, …
443fn operand_kind(token: &str) -> String {
444    use super::value::{classify, Class};
445    match classify(token) {
446        Class::Blank => "a blank node".into(),
447        Class::Iri => "an IRI".into(),
448        Class::Triple => "a quoted triple".into(),
449        Class::Str => "a string".into(),
450        Class::Lang => match crate::terms::lang_tag(token) {
451            Some(l) if !l.is_empty() => format!("a language-tagged literal (@{l})"),
452            _ => "a language-tagged literal".into(),
453        },
454        Class::Other => match crate::terms::literal_datatype(token) {
455            Some(dt) if super::value::compared_by_value(&dt) => {
456                format!("an invalid {} literal", short_dt(&dt))
457            }
458            Some(dt) => format!("a literal of datatype {}", short_dt(&dt)),
459            None => "a literal".into(),
460        },
461        _ => match crate::terms::literal_datatype(token) {
462            Some(dt) => short_dt(&dt),
463            None => "a number".into(),
464        },
465    }
466}
467
468/// `/` with a zero divisor (`token` is the divisor as written).
469#[cold]
470#[inline(never)]
471pub(crate) fn div_by_zero(token: &str) {
472    record(Site::Op("/"), 2, ArgKind::DivByZero, || {
473        (token.to_string(), detail_of(token))
474    });
475}
476
477/// LANG / DATATYPE got a term that is not a literal.
478#[cold]
479#[inline(never)]
480pub(crate) fn not_a_literal(func: Builtin, token: &str) {
481    record(func, 1, kind_of(token), || {
482        (token.to_string(), String::new())
483    });
484}
485
486/// STRDT / STRLANG argument 1 is not a simple literal, or STRDT argument 2 is
487/// not an IRI.
488#[cold]
489#[inline(never)]
490pub(crate) fn bad_constructor_arg(func: Builtin, pos: usize, token: &str) {
491    record(func, pos, term_kind(token), || {
492        (token.to_string(), detail_of_any(token))
493    });
494}
495
496/// Classify any term, telling string and language-tagged literals apart from
497/// other typed ones (no allocation for IRIs and blank nodes).
498fn term_kind(token: &str) -> ArgKind {
499    if !token.starts_with('"') {
500        return kind_of(token);
501    }
502    if crate::terms::lang_tag(token).is_some_and(|l| !l.is_empty()) {
503        return ArgKind::LangTagged;
504    }
505    match crate::terms::literal_datatype(token) {
506        Some(dt) if dt == "http://www.w3.org/2001/XMLSchema#string" => ArgKind::StringLit,
507        None => ArgKind::StringLit,
508        Some(dt) if is_numeric_datatype(&dt) => ArgKind::Numeric,
509        Some(_) => ArgKind::TypedLiteral,
510    }
511}
512
513/// [`detail_of`], but a language-tagged literal reports its tag (`@en`).
514fn detail_of_any(token: &str) -> String {
515    match crate::terms::lang_tag(token).filter(|l| !l.is_empty()) {
516        Some(l) if token.starts_with('"') => format!("@{l}"),
517        _ => detail_of(token),
518    }
519}
520
521/// Classify a bound term that a string function rejected (no allocation for
522/// IRIs and blank nodes, the common case).
523fn kind_of(token: &str) -> ArgKind {
524    if token.starts_with("<<") {
525        ArgKind::QuotedTriple
526    } else if token.starts_with('<') {
527        ArgKind::Iri
528    } else if token.starts_with("_:") {
529        ArgKind::Blank
530    } else if crate::terms::literal_datatype(token).is_some_and(|dt| is_numeric_datatype(&dt)) {
531        ArgKind::Numeric
532    } else {
533        ArgKind::TypedLiteral
534    }
535}
536
537/// The short datatype of a literal (`xsd:integer`), else `""`.
538fn detail_of(token: &str) -> String {
539    match crate::terms::literal_datatype(token) {
540        Some(dt) if token.starts_with('"') => short_dt(&dt),
541        _ => String::new(),
542    }
543}
544
545fn is_numeric_datatype(dt: &str) -> bool {
546    dt.strip_prefix("http://www.w3.org/2001/XMLSchema#")
547        .is_some_and(|local| {
548            matches!(
549                local,
550                "integer"
551                    | "decimal"
552                    | "float"
553                    | "double"
554                    | "int"
555                    | "long"
556                    | "short"
557                    | "byte"
558                    | "nonNegativeInteger"
559                    | "nonPositiveInteger"
560                    | "negativeInteger"
561                    | "positiveInteger"
562                    | "unsignedInt"
563                    | "unsignedLong"
564                    | "unsignedShort"
565                    | "unsignedByte"
566            )
567        })
568}
569
570fn short_dt(dt: &str) -> String {
571    match dt.strip_prefix("http://www.w3.org/2001/XMLSchema#") {
572        Some(local) => format!("xsd:{local}"),
573        None => format!("<{dt}>"),
574    }
575}
576
577fn truncate(s: &str) -> String {
578    match s.char_indices().nth(SAMPLE_CHARS) {
579        Some((i, _)) => format!("{}…", &s[..i]),
580        None => s.to_string(),
581    }
582}
583
584/// SPARQL spelling of a builtin, for messages.
585pub(crate) fn fn_name(f: Builtin) -> &'static str {
586    match f {
587        Builtin::Str => "STR",
588        Builtin::StrLen => "STRLEN",
589        Builtin::UCase => "UCASE",
590        Builtin::LCase => "LCASE",
591        Builtin::Concat => "CONCAT",
592        Builtin::SubStr => "SUBSTR",
593        Builtin::StrBefore => "STRBEFORE",
594        Builtin::StrAfter => "STRAFTER",
595        Builtin::Contains => "CONTAINS",
596        Builtin::StrStarts => "STRSTARTS",
597        Builtin::StrEnds => "STRENDS",
598        Builtin::Regex => "REGEX",
599        Builtin::Replace => "REPLACE",
600        Builtin::EncodeForUri => "ENCODE_FOR_URI",
601        Builtin::Md5 => "MD5",
602        Builtin::Sha1 => "SHA1",
603        Builtin::Sha256 => "SHA256",
604        Builtin::Sha384 => "SHA384",
605        Builtin::Sha512 => "SHA512",
606        Builtin::Year => "YEAR",
607        Builtin::Month => "MONTH",
608        Builtin::Day => "DAY",
609        Builtin::Hours => "HOURS",
610        Builtin::Minutes => "MINUTES",
611        Builtin::Seconds => "SECONDS",
612        Builtin::Timezone => "TIMEZONE",
613        Builtin::Tz => "TZ",
614        Builtin::Abs => "ABS",
615        Builtin::Ceil => "CEIL",
616        Builtin::Floor => "FLOOR",
617        Builtin::Round => "ROUND",
618        Builtin::Lang => "LANG",
619        Builtin::Datatype => "DATATYPE",
620        Builtin::StrDt => "STRDT",
621        Builtin::StrLang => "STRLANG",
622        _ => "function",
623    }
624}
625
626fn ordinal(site: Site, pos: usize) -> String {
627    match (site, pos) {
628        (Site::Op(_), 1) => "the left operand".to_string(),
629        (Site::Op(_), 2) => "the right operand".to_string(),
630        _ => format!("argument {pos}"),
631    }
632}
633
634fn rows(n: u64) -> String {
635    if n == 1 {
636        "1 row".to_string()
637    } else {
638        format!("{n} rows")
639    }
640}
641
642/// The hint for a site family other than the string functions, or `None` to
643/// keep the kind's own hint (which was written for the string functions).
644fn family_hint(family: Family, pos: usize, kind: ArgKind) -> Option<&'static str> {
645    use ArgKind::*;
646    Some(match (family, kind) {
647        (
648            _,
649            Unbound | InvalidRegex | NotDatetime | LangMismatch | DivByZero | Incomparable
650            | StringVsNumber,
651        ) => return None,
652        (Family::Numeric, StringLit) => {
653            "a string is not a number; cast one that holds a number first, e.g. \
654             xsd:decimal(?x), or restrict the variable with isNumeric()"
655        }
656        (Family::Numeric, InvalidNumber) => {
657            "its text is not a valid number for its datatype; restrict the variable with \
658             isNumeric(), which checks the lexical form"
659        }
660        (Family::Numeric, _) => "it is not a number; restrict the variable with isNumeric()",
661        (Family::LiteralAccessor, _) => {
662            "LANG() and DATATYPE() take a literal; restrict the variable with isLiteral()"
663        }
664        (Family::Constructor, Blank | QuotedTriple) if pos == 1 => {
665            "argument 1 must be a simple literal; restrict the variable with isLiteral()"
666        }
667        (Family::Constructor, _) if pos == 1 => {
668            "argument 1 must be a simple literal (no language tag, no datatype); use STR() on \
669             it to take its lexical form"
670        }
671        (Family::Constructor, _) => {
672            "argument 2 of STRDT must be a datatype IRI, e.g. xsd:integer; IRI(?x) turns a \
673             string into one"
674        }
675        (Family::Compare | Family::Other, _) => return None,
676    })
677}
678
679/// Is a comparison's `"<kind> vs <kind>"` detail a string against a number?
680fn string_and_number(detail: &str) -> bool {
681    let numeric = |k: &str| {
682        k.strip_prefix("xsd:")
683            .is_some_and(|l| is_numeric_datatype(&format!("http://www.w3.org/2001/XMLSchema#{l}")))
684            || k == "a number"
685    };
686    match detail.split_once(" vs ") {
687        Some((l, r)) => (l == "a string" && numeric(r)) || (numeric(l) && r == "a string"),
688        None => false,
689    }
690}
691
692impl Entry {
693    /// The two comparison kinds, which are about a pair of operands rather
694    /// than one argument.
695    fn into_comparison_warning(self) -> QueryWarning {
696        let name = self.site.name();
697        let n = rows(self.count);
698        let sample = (!self.sample.is_empty()).then(|| format!("; e.g. {}", self.sample));
699        let (severity, hint, message) = if self.kind == ArgKind::StringVsNumber {
700            let hint = "SPARQL never reads a string as a number; to compare values cast \
701                        the string, e.g. xsd:integer(?x) or xsd:decimal(?x), or to compare \
702                        text use STR() on the number"
703                .to_string();
704            let message = format!(
705                "Operator {name} compared a string with a number in {n} and found them \
706                 unequal although the string's text is that number{}. Hint: {hint}.",
707                sample.unwrap_or_default()
708            );
709            (WarningSeverity::Hint, hint, message)
710        } else {
711            let hint = if string_and_number(&self.detail) {
712                "a string is never compared as a number; cast it first, e.g. \
713                 xsd:integer(?x) or xsd:decimal(?x), or compare the text of both sides \
714                 with STR()"
715            } else if self.detail.contains("an invalid ") {
716                "a value whose text is not valid for its datatype (an ill-typed literal, \
717                 such as a year of fewer than four digits typed xsd:gYear) compares with \
718                 nothing; fix the data, or compare the text of both sides with STR()"
719            } else {
720                "SPARQL orders only two numbers, two strings (with the same language tag), \
721                 two booleans or two date/time values of one type, and = cannot tell two \
722                 different literals of an unrecognised datatype apart; cast both sides to \
723                 one type, or compare their text with STR()"
724            }
725            .to_string();
726            let message = format!(
727                "Operator {name} compared {} in {n}: a SPARQL type error, which makes a \
728                 FILTER drop the row, even under ! (BIND leaves the variable unbound){}. \
729                 Hint: {hint}.",
730                self.detail.replacen(" vs ", " with ", 1),
731                sample.unwrap_or_default()
732            );
733            (WarningSeverity::TypeError, hint, message)
734        };
735        QueryWarning {
736            severity,
737            function: name.to_string(),
738            argument: 0,
739            kind: self.kind.as_str().to_string(),
740            count: self.count,
741            sample: (!self.sample.is_empty()).then_some(self.sample),
742            hint,
743            message,
744        }
745    }
746
747    fn into_warning(self) -> QueryWarning {
748        if matches!(self.kind, ArgKind::Incomparable | ArgKind::StringVsNumber) {
749            return self.into_comparison_warning();
750        }
751        let name = self.site.name();
752        let arg = ordinal(self.site, self.pos);
753        let n = rows(self.count);
754        let dt = |what: &str| {
755            if self.detail.is_empty() {
756                what.to_string()
757            } else {
758                format!("{what} ({})", self.detail)
759            }
760        };
761        let (what, hint) = match self.kind {
762            ArgKind::Iri => (
763                "an IRI".to_string(),
764                "wrap it in STR() to match the IRI's text".to_string(),
765            ),
766            ArgKind::Blank => (
767                "a blank node".to_string(),
768                "blank nodes are not strings; restrict the variable with isLiteral()".to_string(),
769            ),
770            ArgKind::QuotedTriple => (
771                "a quoted triple".to_string(),
772                "quoted triples are not strings; restrict the variable with isLiteral()"
773                    .to_string(),
774            ),
775            ArgKind::Numeric => (
776                dt("a number"),
777                "wrap it in STR() to match its lexical form".to_string(),
778            ),
779            ArgKind::TypedLiteral => (
780                dt("a non-string typed literal"),
781                "wrap it in STR() to match its lexical form".to_string(),
782            ),
783            ArgKind::StringLit => (
784                "a string".to_string(),
785                "wrap it in STR() to match its lexical form".to_string(),
786            ),
787            ArgKind::LangTagged => (
788                dt("a language-tagged literal"),
789                "use STR() on it to drop the language tag".to_string(),
790            ),
791            ArgKind::InvalidNumber => (
792                dt("a literal whose text is not a valid number for its datatype"),
793                String::new(),
794            ),
795            ArgKind::LangMismatch => (
796                format!(
797                    "a literal whose language tag does not match argument 1 ({})",
798                    self.detail
799                ),
800                "the language tags differ; use STR() on both arguments".to_string(),
801            ),
802            ArgKind::Unbound => (
803                format!("an unbound variable ({})", self.sample),
804                "the variable has no value in those rows (an OPTIONAL that did not match, \
805                 or a misspelled variable); use BOUND() or COALESCE() if that is intended"
806                    .to_string(),
807            ),
808            ArgKind::InvalidRegex => (
809                "an invalid regex pattern".to_string(),
810                format!(
811                    "invalid regex pattern ({}); rete uses Rust regex syntax, which has no \
812                     look-around or back-references",
813                    self.detail
814                ),
815            ),
816            ArgKind::NotDatetime => (
817                dt("a value that is not an xsd:dateTime"),
818                "this function needs an xsd:dateTime; for a year in a plain or xsd:date value \
819                 use SUBSTR(STR(?x), 1, 4)"
820                    .to_string(),
821            ),
822            ArgKind::DivByZero => (
823                "zero".to_string(),
824                "guard the divisor, e.g. IF(?d != 0, ?n / ?d, 0), or FILTER(?d != 0) first"
825                    .to_string(),
826            ),
827            ArgKind::Incomparable | ArgKind::StringVsNumber => {
828                unreachable!("handled by into_comparison_warning")
829            }
830        };
831        let hint = match family_hint(self.site.family(), self.pos, self.kind) {
832            Some(h) => h.to_string(),
833            None => hint,
834        };
835        let mut message = match (self.kind, self.site) {
836            (ArgKind::DivByZero, _) => format!("{name} divided by zero in {n}: a SPARQL error"),
837            (_, Site::Op(_)) => {
838                format!("Operator {name} received {what} as {arg} in {n}: a SPARQL type error")
839            }
840            _ => format!("{name} received {what} as {arg} in {n}: a SPARQL type error"),
841        };
842        message.push_str(
843            ", which makes a FILTER drop the row, even under ! (BIND leaves the variable unbound)",
844        );
845        if !matches!(self.kind, ArgKind::Unbound | ArgKind::DivByZero) && !self.sample.is_empty() {
846            message.push_str(&format!("; e.g. {}", self.sample));
847        }
848        message.push_str(&format!(". Hint: {hint}."));
849        QueryWarning {
850            severity: WarningSeverity::TypeError,
851            function: name.to_string(),
852            argument: self.pos,
853            kind: self.kind.as_str().to_string(),
854            count: self.count,
855            sample: (!self.sample.is_empty()).then_some(self.sample),
856            hint,
857            message,
858        }
859    }
860}
861
862fn is_empty_result(out: &QueryOutput) -> bool {
863    match out {
864        QueryOutput::Select(_, rows) => rows.is_empty(),
865        QueryOutput::Ask(b) => !*b,
866        QueryOutput::Construct(t) => t.is_empty(),
867    }
868}
869
870/// Close the scope opened by [`begin`]: turn the sink into warnings for `out`.
871pub(crate) fn finish(out: &QueryOutput) -> Vec<QueryWarning> {
872    let (entries, misses, merged) = SINK.with(|s| {
873        let mut s = s.borrow_mut();
874        (
875            std::mem::take(&mut s.entries),
876            std::mem::take(&mut s.misses),
877            std::mem::take(&mut s.union_merged),
878        )
879    });
880    let errored = !entries.is_empty();
881    let mut out_w: Vec<QueryWarning> = entries.into_iter().map(Entry::into_warning).collect();
882    if merged {
883        let hint = "store the file with a quad index (--named-graphs quad) so the union \
884                    is read in place, or name the graphs with FROM"
885            .to_string();
886        out_w.push(QueryWarning {
887            severity: WarningSeverity::Hint,
888            function: "UNION DEFAULT GRAPH".to_string(),
889            argument: 0,
890            kind: "materialized-union".to_string(),
891            count: 0,
892            sample: None,
893            message: format!(
894                "The union default graph was built by merging every graph in memory, \
895                 because this file has no quad index to read it from; a large file may \
896                 not fit. To avoid that, {hint}."
897            ),
898            hint,
899        });
900    }
901    // Case-sensitivity hint: only for an empty result, only when no type
902    // error offers a better explanation, only for a constant needle that has
903    // letters with case, and only when the predicate actually ran on string
904    // values and said no. It is a suggestion, never an error.
905    if !errored && is_empty_result(out) {
906        let mut seen: Vec<(Builtin, String)> = Vec::new();
907        for (func, needle) in misses {
908            if needle.to_lowercase() == needle.to_uppercase()
909                || seen.iter().any(|(f, n)| *f == func && *n == needle)
910            {
911                continue;
912            }
913            seen.push((func, needle.clone()));
914            let name = fn_name(func);
915            let hint = if func == Builtin::Regex {
916                format!("add the \"i\" flag: REGEX(?x, \"{needle}\", \"i\")")
917            } else {
918                format!(
919                    "compare case-folded: {name}(LCASE(?x), \"{}\")",
920                    needle.to_lowercase()
921                )
922            };
923            out_w.push(QueryWarning {
924                severity: WarningSeverity::Hint,
925                function: name.to_string(),
926                argument: 2,
927                kind: "case-sensitive".to_string(),
928                count: 0,
929                sample: Some(truncate(&needle)),
930                message: format!(
931                    "No results. {name} ran on string values but never matched \"{}\"; \
932                     string matching is case-sensitive. If you expected matches, {hint}.",
933                    truncate(&needle)
934                ),
935                hint,
936            });
937        }
938    }
939    out_w
940}
941
942/// The warnings as a JSON array (`[]` when empty), in the field order of
943/// [`QueryWarning`] with `argKind` for `kind`.
944pub fn warnings_json(warnings: &[QueryWarning]) -> String {
945    use crate::results::push_json_string;
946    let mut s = String::from("[");
947    for (i, w) in warnings.iter().enumerate() {
948        if i > 0 {
949            s.push(',');
950        }
951        s.push_str(r#"{"severity":"#);
952        push_json_string(&mut s, w.severity.as_str());
953        s.push_str(r#","function":"#);
954        push_json_string(&mut s, &w.function);
955        s.push_str(&format!(r#","argument":{}"#, w.argument));
956        s.push_str(r#","argKind":"#);
957        push_json_string(&mut s, &w.kind);
958        s.push_str(&format!(r#","count":{}"#, w.count));
959        s.push_str(r#","sample":"#);
960        match &w.sample {
961            Some(v) => push_json_string(&mut s, v),
962            None => s.push_str("null"),
963        }
964        s.push_str(r#","hint":"#);
965        push_json_string(&mut s, &w.hint);
966        s.push_str(r#","message":"#);
967        push_json_string(&mut s, &w.message);
968        s.push('}');
969    }
970    s.push(']');
971    s
972}