1use crate::registry::FunctionKind;
10use crate::{SQLError, ScalarExpr};
11use std::{borrow::Cow, sync::LazyLock};
12use uqa_core::Value;
13
14pub 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}
20pub fn function_has_implicit_row_input(binding: &crate::ast::FunctionBinding) -> bool {
22 function_implicit_row_input(binding).is_some()
23}
24
25pub 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
33pub 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
73fn 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
88fn 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
177pub 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
189pub 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
245pub 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
309pub 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
319pub 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 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}