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