Skip to main content

uqa_sql/retrieval/
description.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Inspect vector-call identity while leaving unsafe or unavailable arguments unevaluated.
8
9use super::{calls, ControlledConstantEvaluator, RetrievalConstants, RetrievalExpr};
10use crate::SQLParam;
11use crate::{registry::FunctionKind, SQLError, ScalarExpr};
12use uqa_core::memory::{Produced, ProductionControl};
13
14#[cfg(test)]
15mod tests;
16
17pub struct VectorCallDescription<S = String, B = RetrievalExpr> {
18    pub field: Option<S>,
19    pub qualifier: Option<S>,
20    pub calibrated: bool,
21    pub bound: Option<B>,
22    pub invalid_arguments: bool,
23}
24
25pub type ProducedVectorCallDescription =
26    VectorCallDescription<Produced<String>, Produced<RetrievalExpr>>;
27
28pub fn describe_vector_call(
29    expression: &ScalarExpr,
30    constants: &RetrievalConstants<'_>,
31    can_evaluate: &dyn Fn(&ScalarExpr) -> bool,
32) -> Result<Option<VectorCallDescription>, SQLError> {
33    let value = describe_vector_call_with_control(
34        expression,
35        constants.params,
36        &|expression, params, control| {
37            Ok(control.retain_external_value((constants.evaluate)(expression, params)?)?)
38        },
39        can_evaluate,
40        &ProductionControl::uncontrolled(),
41    )?;
42    Ok(value.map(|value| VectorCallDescription {
43        field: value
44            .field
45            .map(|field| field.into_uncontrolled().expect("ordinary field")),
46        qualifier: value
47            .qualifier
48            .map(|qualifier| qualifier.into_uncontrolled().expect("ordinary qualifier")),
49        calibrated: value.calibrated,
50        bound: value
51            .bound
52            .map(|call| call.into_uncontrolled().expect("ordinary vector call")),
53        invalid_arguments: value.invalid_arguments,
54    }))
55}
56
57pub fn describe_vector_call_with_control(
58    expression: &ScalarExpr,
59    params: &[SQLParam],
60    evaluate: &ControlledConstantEvaluator<'_>,
61    can_evaluate: &dyn Fn(&ScalarExpr) -> bool,
62    control: &ProductionControl<'_>,
63) -> Result<Option<ProducedVectorCallDescription>, SQLError> {
64    control.check()?;
65    let ScalarExpr::Func { name, args, .. } = expression else {
66        return Ok(None);
67    };
68    let calibrated = match crate::registry::lookup(name) {
69        Some(FunctionKind::KNNMatch) => false,
70        Some(FunctionKind::CalibratedVectorMatch) => true,
71        _ => return Ok(None),
72    };
73    calls::validate_operator_function_arity(name, args.len())?;
74    let field = calls::vector::field(
75        &args[0],
76        calibrated && can_evaluate(&args[0]),
77        params,
78        evaluate,
79        control,
80    )?;
81    let qualifier = match &args[0] {
82        ScalarExpr::QualifiedColumn { qualifier, .. } => Some(control.copy_text(qualifier)?),
83        _ => None,
84    };
85    let available = field.is_some() && args.iter().skip(1).all(can_evaluate);
86    let bound = if available {
87        match calls::vector::bind(calibrated, args, params, evaluate, control) {
88            Ok(value) => Some(value),
89            Err(error) if calls::vector::resource_failure(&error) => return Err(error),
90            Err(_) => None,
91        }
92    } else {
93        None
94    };
95    Ok(Some(VectorCallDescription {
96        field,
97        qualifier,
98        calibrated,
99        invalid_arguments: available && bound.is_none(),
100        bound,
101    }))
102}