Skip to main content

uqa_sql/semantics/
functions.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Function naming, shape, and relation-field argument semantics.
8
9use crate::registry::FunctionKind;
10use crate::{SQLError, ScalarExpr};
11use std::{borrow::Cow, sync::LazyLock};
12use uqa_core::Value;
13
14mod production;
15pub use production::{
16    builtin_function_dispatch_name_with_control, lowercase_function_name_with_control, FunctionName,
17};
18
19/// Executor-only carrier for `PostgreSQL` 18's `merge_action()` value. The attribute has no SQL name and therefore cannot collide with a target or source column named `_merge_action`.
20pub fn merge_action_attribute() -> crate::ast::InternalColumnRef {
21    static ATTRIBUTE: LazyLock<crate::ast::InternalColumnRef> =
22        LazyLock::new(|| crate::ast::InternalRelationId::allocate().column(0));
23    *ATTRIBUTE
24}
25/// Whether a selected builtin reads the current row through an implicit executor attribute. Such a call is not a constant even when it has no explicit operands; this dependency is independent of routine volatility.
26pub fn function_has_implicit_row_input(binding: &crate::ast::FunctionBinding) -> bool {
27    function_implicit_row_input(binding).is_some()
28}
29
30/// The owned internal identity read by a native call with no written row operand.
31pub fn function_implicit_row_input(
32    binding: &crate::ast::FunctionBinding,
33) -> Option<crate::ast::InternalColumnRef> {
34    (binding.builtin && binding.dispatch == Some(crate::ast::FunctionDispatch::MergeAction))
35        .then(merge_action_attribute)
36}
37
38/// Resolve reserved system-schema aliases only when the local name belongs to
39/// that schema's built-in surface. Ordinary qualified names stay intact for
40/// runtime callbacks and user-defined routine lookup. Already normalized names borrow the original full name or local-name slice; ASCII case folding owns one buffer.
41pub fn builtin_function_dispatch_name(name: &str) -> Cow<'_, str> {
42    let lower = lowercase_function_name(name);
43    let Some((schema, local)) = lower.split_once('.') else {
44        return lower;
45    };
46    let is_builtin = match schema {
47        "ag_catalog" => is_age_catalog_function(local),
48        "pg_catalog" => {
49            crate::registry::is_registered(local)
50                || crate::type_resolution::is_fixed_builtin(local)
51                || crate::expr::variadic_any::is_variadic_any(local)
52                || crate::ast::is_builtin_aggregate_function(local)
53                || is_pg_catalog_function(local)
54        }
55        _ => false,
56    };
57    if !is_builtin {
58        return lower;
59    }
60    let offset = schema.len() + 1;
61    match lower {
62        Cow::Borrowed(lower) => Cow::Borrowed(&lower[offset..]),
63        Cow::Owned(mut lower) => {
64            lower.drain(..offset);
65            Cow::Owned(lower)
66        }
67    }
68}
69
70pub(crate) fn lowercase_function_name(name: &str) -> Cow<'_, str> {
71    if name.bytes().any(|byte| byte.is_ascii_uppercase()) {
72        Cow::Owned(name.to_ascii_lowercase())
73    } else {
74        Cow::Borrowed(name)
75    }
76}
77
78/// The functions of the `ag_catalog` schema that a qualified call names.
79fn is_age_catalog_function(local: &str) -> bool {
80    matches!(
81        local,
82        "cypher"
83            | "create_graph"
84            | "drop_graph"
85            | "graph_exists"
86            | "create_vlabel"
87            | "create_elabel"
88            | "drop_label"
89            | "alter_graph"
90    )
91}
92
93/// The built-in functions outside the scalar registry that a `pg_catalog`-qualified call names.
94fn is_pg_catalog_function(local: &str) -> bool {
95    matches!(
96        local,
97        "generate_series"
98            | "unnest"
99            | "string_to_table"
100            | "json_array_elements"
101            | "jsonb_array_elements"
102            | "json_array_elements_text"
103            | "jsonb_array_elements_text"
104            | "json_each"
105            | "jsonb_each"
106            | "json_each_text"
107            | "jsonb_each_text"
108            | "aclexplode"
109            | "json_object_keys"
110            | "jsonb_object_keys"
111            | "upper"
112            | "lower"
113            | "bit_length"
114            | "char_length"
115            | "character_length"
116            | "crc32"
117            | "crc32c"
118            | "get_byte"
119            | "gamma"
120            | "json_strip_nulls"
121            | "jsonb_strip_nulls"
122            | "length"
123            | "lgamma"
124            | "md5"
125            | "octet_length"
126            | "reverse"
127            | "random"
128            | "setseed"
129            | "nextval"
130            | "currval"
131            | "lastval"
132            | "setval"
133            | "current_schema"
134            | "current_schemas"
135            | "current_setting"
136            | "set_config"
137            | "pg_sleep"
138            | "pg_sleep_for"
139            | "pg_sleep_until"
140            | "pg_backend_pid"
141            | "pg_my_temp_schema"
142            | "pg_is_other_temp_schema"
143            | "pg_trigger_depth"
144            | "pg_listening_channels"
145            | "pg_notify"
146            | "pg_notification_queue_usage"
147            | "pg_get_expr"
148            | "pg_get_partkeydef"
149            | "pg_get_serial_sequence"
150            | "pg_get_sequence_data"
151            | "pg_sequence_last_value"
152            | "pg_sequence_parameters"
153            | "pg_get_triggerdef"
154            | "pg_get_ruledef"
155            | "pg_get_viewdef"
156            | "pg_get_indexdef"
157            | "pg_get_constraintdef"
158            | "pg_get_function_arguments"
159            | "pg_get_function_identity_arguments"
160            | "pg_get_function_result"
161            | "pg_get_functiondef"
162            | "pg_get_function_sqlbody"
163            | "format_type"
164            | "pg_describe_object"
165            | "obj_description"
166            | "pg_has_role"
167            | "pg_get_userbyid"
168            | "has_table_privilege"
169            | "has_column_privilege"
170            | "has_database_privilege"
171            | "has_schema_privilege"
172            | "has_sequence_privilege"
173            | "has_function_privilege"
174            | "has_type_privilege"
175    )
176}
177
178pub fn is_builtin_aggregate(expr: &ScalarExpr) -> bool {
179    matches!(expr, ScalarExpr::Func { name, binding, .. } if is_builtin_aggregate_call(name, binding.as_ref()))
180}
181
182/// Classify the routine selected for a call, retaining qualified built-ins while allowing user scalar overloads with the same local name.
183pub fn is_builtin_aggregate_call(
184    name: &str,
185    binding: Option<&crate::ast::FunctionBinding>,
186) -> bool {
187    if binding.is_some_and(|binding| !binding.builtin || binding.dispatch.is_some()) {
188        return false;
189    }
190    let name = binding.map_or(name, |binding| binding.name.as_str());
191    crate::ast::is_builtin_aggregate_function(builtin_aggregate_dispatch_name(name))
192}
193
194/// Borrow the local name for an already selected built-in aggregate kernel. This does not select a routine: registered aggregates and scalar overloads must keep their selected identities before entering built-in execution. No name or argument allocation occurs for each input row.
195pub fn builtin_aggregate_dispatch_name(name: &str) -> &str {
196    match name.split_once('.') {
197        Some((schema, local)) if schema.eq_ignore_ascii_case("pg_catalog") => local,
198        _ => name,
199    }
200}
201
202pub enum MultiFieldMatchShape<'a> {
203    FieldsThenQuery {
204        fields: Vec<&'a ScalarExpr>,
205        query_idx: usize,
206    },
207    Pairs {
208        fields: Vec<&'a ScalarExpr>,
209    },
210}
211
212pub fn multi_field_match_shape(args: &[ScalarExpr]) -> Result<MultiFieldMatchShape<'_>, SQLError> {
213    let first_non_column = args.iter().position(|arg| {
214        !matches!(
215            arg,
216            ScalarExpr::Column(_) | ScalarExpr::QualifiedColumn { .. }
217        )
218    });
219    if let Some(query_idx) = first_non_column {
220        if query_idx >= 2 {
221            return Ok(MultiFieldMatchShape::FieldsThenQuery {
222                fields: args[..query_idx].iter().collect(),
223                query_idx,
224            });
225        }
226    }
227    if args.len() < 4 || !args.len().is_multiple_of(2) {
228        if let Some(query_idx) = first_non_column {
229            if query_idx < 2 && args.len() >= 3 {
230                return Err(SQLError::TypeMismatch(format!(
231                    "multi_field_match field arguments must be column references, \
232                     but argument {} is an expression; store computed text in an \
233                     indexed column instead of concatenating at query time",
234                    query_idx + 1
235                )));
236            }
237        }
238        return Err(SQLError::BadArity {
239            name: "multi_field_match".into(),
240            expected: ">= 3 (fields..., query[, weights...]) or even >= 4 (field, query pairs)"
241                .into(),
242            actual: args.len(),
243        });
244    }
245    Ok(MultiFieldMatchShape::Pairs {
246        fields: (0..args.len() / 2).map(|i| &args[2 * i]).collect(),
247    })
248}
249
250/// Return whether a registered function consumes this argument as a relation-field identifier rather than as a scalar row value.
251pub fn is_semantic_field_argument(
252    function: &str,
253    args: &[ScalarExpr],
254    argument_index: usize,
255) -> Result<bool, SQLError> {
256    let dispatch_name = crate::semantics::builtin_function_dispatch_name(function);
257    let Some(kind) = crate::registry::lookup(&dispatch_name) else {
258        return Ok(false);
259    };
260    let is_field = match kind {
261        FunctionKind::TextMatch | FunctionKind::BayesianMatch | FunctionKind::KNNMatch => {
262            argument_index == 0
263        }
264        FunctionKind::FTSMatch => argument_index == 0 && !fts_query_is_jsonpath(args.get(1)),
265        FunctionKind::BayesianMatchWithPrior => matches!(argument_index, 0 | 2),
266        FunctionKind::CalibratedVectorMatch => argument_index == 0,
267        FunctionKind::MultiFieldMatch => match multi_field_match_shape(args)? {
268            MultiFieldMatchShape::FieldsThenQuery { query_idx, .. } => argument_index < query_idx,
269            MultiFieldMatchShape::Pairs { .. } => argument_index.is_multiple_of(2),
270        },
271        FunctionKind::StagedRetrieval => {
272            !matches!(args.first(), Some(ScalarExpr::Func { .. }))
273                && argument_index.is_multiple_of(3)
274        }
275        FunctionKind::UQAFacets => true,
276        FunctionKind::ScoreBM25 | FunctionKind::ScoreBayesianBM25 => {
277            args.len() == 2 && argument_index == 0
278        }
279        FunctionKind::FuseLogOdds
280        | FunctionKind::PositiveEvidencePool
281        | FunctionKind::BayesianEvidenceFusion
282        | FunctionKind::GraphPagerank
283        | FunctionKind::GraphHits
284        | FunctionKind::GraphBetweenness
285        | FunctionKind::GraphTraverse
286        | FunctionKind::GraphNeighbors
287        | FunctionKind::DeepPredict
288        | FunctionKind::UQAHighlight
289        | FunctionKind::TraverseMatch
290        | FunctionKind::TemporalTraverse
291        | FunctionKind::RPQ
292        | FunctionKind::GraphCreate
293        | FunctionKind::GraphDrop
294        | FunctionKind::GraphExists
295        | FunctionKind::GraphLabelCreate
296        | FunctionKind::GraphLabelDrop
297        | FunctionKind::GraphAlter
298        | FunctionKind::GraphEdges
299        | FunctionKind::AttentionFusion
300        | FunctionKind::LearnedFusion
301        | FunctionKind::SparseThreshold
302        | FunctionKind::DeepLearn
303        | FunctionKind::Convolve
304        | FunctionKind::Pool
305        | FunctionKind::Flatten
306        | FunctionKind::Dense
307        | FunctionKind::Softmax
308        | FunctionKind::Layer
309        | FunctionKind::Model => false,
310    };
311    Ok(is_field)
312}
313
314/// The `@@` operator doubles as a `JSONPath` match when the right-hand
315/// side is a `$...` path literal; that form evaluates row-level JSON and
316/// needs no text index.
317pub fn fts_query_is_jsonpath(query_arg: Option<&ScalarExpr>) -> bool {
318    matches!(
319        query_arg,
320        Some(ScalarExpr::Literal(Value::Str(path))) if path.trim_start().starts_with('$')
321    )
322}
323
324/// Whether a scalar expression contains a posting-list retrieval operator.
325/// Relational executors use the same classification as access-path planning
326/// so registered retrieval calls never fall through to scalar evaluation.
327pub fn contains_retrieval(expression: &ScalarExpr) -> bool {
328    match expression {
329        ScalarExpr::Func {
330            name,
331            args,
332            order_by,
333            filter,
334            ..
335        } => {
336            retrieval_function(name)
337                || args.iter().any(contains_retrieval)
338                || order_by.iter().any(|order| contains_retrieval(&order.expr))
339                || filter.as_deref().is_some_and(contains_retrieval)
340        }
341        ScalarExpr::Array(items)
342        | ScalarExpr::Row(items)
343        | ScalarExpr::CompositeRow { items, .. }
344        | ScalarExpr::And(items)
345        | ScalarExpr::Or(items) => items.iter().any(contains_retrieval),
346        ScalarExpr::Binary { lhs, rhs, .. } => contains_retrieval(lhs) || contains_retrieval(rhs),
347        ScalarExpr::UnaryMinus(inner)
348        | ScalarExpr::Not(inner)
349        | ScalarExpr::IsNull { expr: inner, .. }
350        | ScalarExpr::Cast { expr: inner, .. }
351        | ScalarExpr::Collated { expr: inner, .. } => contains_retrieval(inner),
352        ScalarExpr::Between { expr, low, high } => {
353            contains_retrieval(expr) || contains_retrieval(low) || contains_retrieval(high)
354        }
355        ScalarExpr::InList { expr, list, .. } => {
356            contains_retrieval(expr) || list.iter().any(contains_retrieval)
357        }
358        ScalarExpr::WindowCall {
359            args, spec, filter, ..
360        } => {
361            args.iter().any(contains_retrieval)
362                || filter.as_deref().is_some_and(contains_retrieval)
363                || spec.partition_by.iter().any(contains_retrieval)
364                || spec
365                    .order_by
366                    .iter()
367                    .any(|order| contains_retrieval(&order.expr))
368        }
369        ScalarExpr::Case {
370            base,
371            when,
372            else_branch,
373        } => {
374            base.as_deref().is_some_and(contains_retrieval)
375                || when.iter().any(|(condition, result)| {
376                    contains_retrieval(condition) || contains_retrieval(result)
377                })
378                || else_branch.as_deref().is_some_and(contains_retrieval)
379        }
380        ScalarExpr::InSubquery { expr, .. } => contains_retrieval(expr),
381        ScalarExpr::Default
382        | ScalarExpr::Star
383        | ScalarExpr::QualifiedStar(_)
384        | ScalarExpr::Column(_)
385        | ScalarExpr::Position(_)
386        | ScalarExpr::InternalColumn(_)
387        | ScalarExpr::QualifiedColumn { .. }
388        | ScalarExpr::Literal(_)
389        | ScalarExpr::TypedLiteral { .. }
390        | ScalarExpr::RetainedLiteral(_)
391        | ScalarExpr::Param(_)
392        | ScalarExpr::ScalarSubquery(_)
393        | ScalarExpr::Exists { .. } => false,
394    }
395}
396
397pub fn retrieval_function(name: &str) -> bool {
398    [
399        "text_match",
400        "bayesian_match",
401        "fts_match",
402        "bayesian_match_with_prior",
403        "calibrated_vector_match",
404        "knn_match",
405        "fuse_log_odds",
406        "pool_positive_evidence",
407        "fuse_bayesian_evidence",
408        "multi_field_match",
409        "staged_retrieval",
410        "attention",
411        "fuse_attention",
412        "fuse_multihead",
413        "learned_fusion",
414        "fuse_learned",
415        "sparse_threshold",
416        "graph_pagerank",
417        "pagerank",
418        "graph_hits",
419        "hits",
420        "graph_betweenness",
421        "betweenness",
422        "graph_traverse",
423        "traverse_match",
424        "graph_neighbors",
425        "graph_edges",
426        "temporal_traverse",
427        "rpq",
428        "deep_predict",
429    ]
430    .iter()
431    .any(|candidate| name.eq_ignore_ascii_case(candidate))
432}
433
434pub fn expect_column_name(expr: &ScalarExpr, label: &str) -> Result<String, SQLError> {
435    match expr {
436        ScalarExpr::Column(name) => Ok(name.to_string()),
437        ScalarExpr::QualifiedColumn { column, .. } => Ok(column.to_string()),
438        other => Err(SQLError::TypeMismatch(format!(
439            "{label} must be a column reference, got {other:?}"
440        ))),
441    }
442}
443
444#[cfg(test)]
445mod tests {
446    use super::{builtin_function_dispatch_name, Cow};
447
448    #[test]
449    fn builtin_dispatch_preserves_schema_identity() {
450        for name in [
451            "pg_get_sequence_data",
452            "pg_sequence_last_value",
453            "pg_sequence_parameters",
454            "date_trunc",
455            "mod",
456            "count",
457            "sum",
458            "array_agg",
459            "percentile_cont",
460            "concat",
461            "concat_ws",
462            "format",
463            "json_build_object",
464            "json_build_array",
465            "jsonb_build_object",
466            "jsonb_build_array",
467            "num_nulls",
468            "num_nonnulls",
469        ] {
470            assert_eq!(builtin_function_dispatch_name(name), name);
471            assert_eq!(
472                builtin_function_dispatch_name(&format!("pg_catalog.{name}")),
473                name
474            );
475            assert_eq!(
476                builtin_function_dispatch_name(&format!("PG_CATALOG.{}", name.to_uppercase())),
477                name
478            );
479            let user_function = format!("public.{name}");
480            assert_eq!(
481                builtin_function_dispatch_name(&user_function),
482                user_function
483            );
484        }
485        assert_eq!(
486            builtin_function_dispatch_name("pg_catalog.custom_function"),
487            "pg_catalog.custom_function"
488        );
489    }
490
491    #[test]
492    fn normalized_dispatch_names_borrow_the_original_identifier() {
493        for (name, expected, offset) in [
494            ("length", "length", 0),
495            ("pg_catalog.length", "length", 11),
496            ("pg_catalog.count", "count", 11),
497            ("pg_catalog.concat", "concat", 11),
498            ("ag_catalog.cypher", "cypher", 11),
499            ("public.length", "public.length", 0),
500            ("pg_catalog.custom", "pg_catalog.custom", 0),
501            ("ag_catalog.length", "ag_catalog.length", 0),
502            ("\"pg_catalog\".length", "\"pg_catalog\".length", 0),
503            ("public.Éclair", "public.Éclair", 0),
504            ("", "", 0),
505        ] {
506            // Initialize immutable builtin metadata outside the per-call allocation measurement.
507            assert_eq!(builtin_function_dispatch_name(name), expected);
508            let allocations = allocation_counter::measure(|| {
509                let actual = builtin_function_dispatch_name(name);
510                assert!(matches!(actual, Cow::Borrowed(_)));
511                assert_eq!(actual, expected);
512                assert_eq!(actual.as_ptr(), name.as_bytes()[offset..].as_ptr());
513            });
514            assert_eq!(allocations.count_total, 0, "{name}: {allocations:?}");
515        }
516        let name = format!("public.{}", "x".repeat(4 * 1024 * 1024));
517        let allocations = allocation_counter::measure(|| {
518            assert!(matches!(
519                builtin_function_dispatch_name(&name),
520                Cow::Borrowed(_)
521            ));
522        });
523        assert_eq!(allocations.count_total, 0, "{allocations:?}");
524    }
525
526    #[test]
527    fn dispatch_case_folding_owns_one_buffer_and_preserves_schema_selection() {
528        for (name, expected) in [
529            ("LENGTH", "length"),
530            ("PG_CATALOG.COUNT", "count"),
531            ("AG_CATALOG.CYPHER", "cypher"),
532            ("PUBLIC.LENGTH", "public.length"),
533            ("PG_CATALOG.CUSTOM", "pg_catalog.custom"),
534            ("PUBLIC.ÉCLAIR", "public.Éclair"),
535        ] {
536            assert_eq!(builtin_function_dispatch_name(name), expected);
537            let allocations = allocation_counter::measure(|| {
538                let actual = builtin_function_dispatch_name(name);
539                assert!(matches!(actual, Cow::Owned(_)));
540                assert_eq!(actual, expected);
541            });
542            assert_eq!(allocations.count_total, 1, "{name}: {allocations:?}");
543            assert_eq!(allocations.bytes_total, name.len() as u64, "{name}");
544        }
545    }
546
547    #[test]
548    fn aggregate_classification_borrows_identifiers_in_every_case() {
549        let long = "x".repeat(4 * 1024 * 1024);
550        for (name, expected) in [
551            ("count", true),
552            ("CoUnT", true),
553            ("PERCENTILE_CONT", true),
554            ("jsonb_object_agg", true),
555            ("pg_catalog.count", false),
556            ("\"count\"", false),
557            ("coünt", false),
558            (long.as_str(), false),
559        ] {
560            let allocations = allocation_counter::measure(|| {
561                assert_eq!(crate::ast::is_builtin_aggregate_function(name), expected);
562            });
563            assert_eq!(allocations.count_total, 0, "{allocations:?}");
564        }
565    }
566
567    #[test]
568    fn retrieval_classification_borrows_normalized_function_names() {
569        for (name, expected) in [("text_match", true), ("knn_match", true), ("length", false)] {
570            let allocations = allocation_counter::measure(|| {
571                assert_eq!(super::retrieval_function(name), expected);
572            });
573            assert_eq!(allocations.count_total, 0, "{name}: {allocations:?}");
574            assert_eq!(
575                super::retrieval_function(&name.to_ascii_uppercase()),
576                expected
577            );
578        }
579    }
580}