1use 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
19pub 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}
25pub fn function_has_implicit_row_input(binding: &crate::ast::FunctionBinding) -> bool {
27 function_implicit_row_input(binding).is_some()
28}
29
30pub 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
38pub 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
78fn 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
93fn 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
182pub 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
194pub 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
250pub 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
314pub 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
324pub 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 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}