Skip to main content

uqa_sql/semantics/
volatility.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! SQL function volatility and expression rewrite safety over catalog metadata.
8//!
9//! Volatility is a semantic property, not merely an optimizer hint.  A
10//! `VOLATILE` call may not be duplicated, elided, moved to a different join
11//! level, or hidden behind a statement-local view cache.  Keep the decision in
12//! one place so the view, CTE, predicate-pushdown, column-pruning, and `DPccp`
13//! paths cannot drift apart.
14
15use crate::ast::{FunctionBinding, FunctionVolatility};
16use crate::plan::{QueryBlockPlan, QueryPlan, UnifiedPlan};
17use crate::SQLError;
18use crate::ScalarExpr;
19
20mod production;
21pub use production::{
22    builtin_function_volatility_with_control, expr_contains_volatile_function_with_control,
23    function_volatility_with_binding_and_control, query_contains_volatile_function_with_control,
24    scalar_calls_are_volatile_with_control,
25    scalar_in_scope_contains_volatile_function_with_control,
26    select_contains_volatile_function_with_control,
27    unified_plan_contains_volatile_function_with_control,
28};
29
30/// Metadata needed to classify SQL expressions without invoking a routine or reading a row.
31pub trait VolatilityCatalog {
32    fn host_function_volatility(&self, name: &str) -> Option<FunctionVolatility>;
33    fn routine_volatilities(
34        &self,
35        name: &str,
36        binding: Option<&FunctionBinding>,
37    ) -> Option<Vec<FunctionVolatility>>;
38    /// Aggregate an external catalog's completed metadata; native registries override this with a borrowed fold.
39    fn routine_volatility_with_control(
40        &self,
41        name: &str,
42        binding: Option<&FunctionBinding>,
43        control: &uqa_core::memory::ProductionControl<'_>,
44    ) -> Result<Option<FunctionVolatility>, SQLError> {
45        control.check()?;
46        let result = self
47            .routine_volatilities(name, binding)
48            .as_deref()
49            .map(production::strongest);
50        control.check()?;
51        Ok(result)
52    }
53    fn view_query(&self, name: &str) -> Result<Option<QueryPlan>, SQLError>;
54
55    /// Lend the selected view plan for one read. Catalogs retaining immutable definitions can override this adapter without constructing an owned plan.
56    fn with_view_query(
57        &self,
58        name: &str,
59        read: &mut dyn FnMut(&QueryPlan) -> Result<bool, SQLError>,
60    ) -> Result<Option<bool>, SQLError> {
61        self.view_query(name)?.as_ref().map(read).transpose()
62    }
63
64    /// Read a retained native view under the current production scope. The external default keeps its existing callback boundary; native borrowed overrides do not construct a query copy.
65    fn with_view_query_with_control(
66        &self,
67        name: &str,
68        control: &uqa_core::memory::ProductionControl<'_>,
69        read: &mut dyn FnMut(&QueryPlan) -> Result<bool, SQLError>,
70    ) -> Result<Option<bool>, SQLError> {
71        control.check()?;
72        let result = self.with_view_query(name, &mut |query| {
73            control.check()?;
74            read(query)
75        })?;
76        control.check()?;
77        Ok(result)
78    }
79}
80
81use super::builtin_function_dispatch_name;
82
83/// Resolve the volatility of the implementation that can run for `name`.
84///
85/// Rust extension callbacks default to `VOLATILE`, while registrations with
86/// explicit options use their declared volatility. SQL routine overloads are
87/// combined conservatively: a name is only non-volatile when every overload
88/// registered under it is non-volatile. This remains correct before runtime
89/// argument coercion selects a particular overload.
90pub fn function_volatility(
91    catalog: &dyn VolatilityCatalog,
92    name: &str,
93    argument_count: usize,
94) -> FunctionVolatility {
95    function_volatility_with_binding(catalog, name, None, argument_count)
96}
97
98pub fn function_binding_is_volatile(
99    catalog: &dyn VolatilityCatalog,
100    name: &str,
101    binding: Option<&FunctionBinding>,
102    argument_count: usize,
103) -> bool {
104    function_volatility_with_binding(catalog, name, binding, argument_count)
105        == FunctionVolatility::Volatile
106}
107
108fn is_intrinsic_scalar_syntax(binding: Option<&FunctionBinding>) -> bool {
109    binding
110        .and_then(|binding| binding.dispatch)
111        .is_some_and(crate::ast::FunctionDispatch::is_concatenation)
112        || matches!(
113            binding.and_then(|binding| binding.dispatch),
114            Some(
115                crate::ast::FunctionDispatch::NumericOperator(_)
116                    | crate::ast::FunctionDispatch::Pattern { .. }
117                    | crate::ast::FunctionDispatch::PatternEscape { .. }
118                    | crate::ast::FunctionDispatch::Collate { .. }
119                    | crate::ast::FunctionDispatch::BooleanTest(_)
120                    | crate::ast::FunctionDispatch::ArraySubscripts
121                    | crate::ast::FunctionDispatch::ArraySlices
122                    | crate::ast::FunctionDispatch::ArraySlicesWithBounds(_)
123            )
124        )
125}
126
127pub fn function_volatility_with_binding(
128    catalog: &dyn VolatilityCatalog,
129    name: &str,
130    binding: Option<&FunctionBinding>,
131    argument_count: usize,
132) -> FunctionVolatility {
133    function_volatility_with_binding_and_control(
134        catalog,
135        name,
136        binding,
137        argument_count,
138        &uqa_core::memory::ProductionControl::uncontrolled(),
139    )
140    .expect("ordinary routine volatility has no resource failure")
141}
142
143/// Classify an already selected built-in without consulting host or SQL routine registrations. Callers that have not resolved the routine must use the catalog-aware entry point instead.
144pub fn builtin_function_volatility(
145    name: &str,
146    binding: Option<&FunctionBinding>,
147    argument_count: usize,
148) -> FunctionVolatility {
149    if let Some(crate::ast::FunctionDispatch::Concat { oid }) =
150        binding.and_then(|binding| binding.dispatch)
151    {
152        return oid
153            .and_then(|oid| crate::type_resolution::binary_operator_by_oid(i64::from(oid)))
154            .filter(|operator| operator.name == "||")
155            .map_or(FunctionVolatility::Stable, |operator| operator.volatility());
156    }
157    if is_intrinsic_scalar_syntax(binding) {
158        return FunctionVolatility::Immutable;
159    }
160    let lower = builtin_function_dispatch_name(name);
161    if builtin_is_volatile(&lower) {
162        return FunctionVolatility::Volatile;
163    }
164
165    // UQA retrieval/graph functions not listed above read the statement's
166    // catalog snapshot.  Session/catalog introspection functions have the same
167    // statement-stable contract.  All remaining built-ins are value-pure.
168    if crate::registry::is_registered(&lower)
169        || matches!(
170            lower.as_ref(),
171            "current_schema"
172                | "concat"
173                | "concat_ws"
174                | "format"
175                | "pg_typeof"
176                | "pg_collation_for"
177                | "typeof"
178                | "row_to_json"
179                | "to_json"
180                | "to_jsonb"
181                | "json_build_object"
182                | "jsonb_build_object"
183                | "json_build_array"
184                | "jsonb_build_array"
185                | "to_char"
186                | "to_date"
187                | "to_number"
188                | "now"
189                | "current_date"
190                | "current_time"
191                | "current_timestamp"
192                | "localtime"
193                | "localtimestamp"
194                | "statement_timestamp"
195                | "transaction_timestamp"
196                | "current_schemas"
197                | "current_setting"
198                | "pg_backend_pid"
199                | "pg_my_temp_schema"
200                | "pg_is_other_temp_schema"
201                | "pg_trigger_depth"
202                | "version"
203                | "pg_listening_channels"
204                | "to_regclass"
205                | "to_regcollation"
206                | "to_regnamespace"
207                | "to_regproc"
208                | "to_regprocedure"
209                | "to_regrole"
210                | "to_regtype"
211                | "current_database"
212                | "current_catalog"
213                | "current_user"
214                | "session_user"
215                | "list_analyzers"
216                | "fts_index_stats"
217                | "pg_get_expr"
218                | "pg_get_partkeydef"
219                | "pg_get_serial_sequence"
220                | "pg_sequence_parameters"
221                | "pg_get_triggerdef"
222                | "pg_get_ruledef"
223                | "pg_get_viewdef"
224                | "pg_get_indexdef"
225                | "pg_get_constraintdef"
226                | "pg_get_function_arguments"
227                | "pg_get_function_identity_arguments"
228                | "pg_get_function_result"
229                | "pg_get_functiondef"
230            | "pg_get_function_sqlbody"
231                | "format_type"
232                | "pg_describe_object"
233            | "obj_description"
234                | "pg_has_role"
235                | "pg_get_userbyid"
236                | "has_database_privilege"
237                | "has_table_privilege"
238                | "has_column_privilege"
239                | "has_schema_privilege"
240                | "has_sequence_privilege"
241                | "has_function_privilege"
242                | "has_type_privilege"
243                // The enum support functions that read a type's label list see labels added later in the transaction.
244                | "enum_first"
245                | "enum_last"
246                | "enum_range"
247        )
248        || builtin_overload_is_stable(&lower, binding, argument_count)
249    {
250        FunctionVolatility::Stable
251    } else {
252        FunctionVolatility::Immutable
253    }
254}
255
256fn builtin_overload_is_stable(
257    name: &str,
258    binding: Option<&FunctionBinding>,
259    argument_count: usize,
260) -> bool {
261    (matches!(name, "age" | "timezone") && argument_count == 1)
262        || (name == "to_timestamp" && argument_count == 2)
263        || (matches!(name, "quote_literal" | "quote_nullable")
264            && binding.is_none_or(|binding| binding.argument_types.as_slice() != ["text"]))
265        || (matches!(name, "date_part" | "extract" | "date_trunc")
266            && argument_count == 2
267            && binding.is_none_or(|binding| {
268                binding
269                    .argument_types
270                    .iter()
271                    .any(|ty| matches!(ty.as_str(), "timestamptz" | "timestamp with time zone"))
272            }))
273}
274
275// These built-ins mutate catalog/session state or derive a fresh value on every evaluation.
276fn builtin_is_volatile(name: &str) -> bool {
277    matches!(
278        name,
279        "random"
280            | "setseed"
281            | "set_config"
282            | "pg_sleep"
283            | "pg_sleep_for"
284            | "pg_sleep_until"
285            | "pg_notify"
286            | "pg_notification_queue_usage"
287            | "array_sample"
288            | "nextval"
289            | "currval"
290            | "lastval"
291            | "setval"
292            | "pg_get_sequence_data"
293            | "pg_sequence_last_value"
294            | "clock_timestamp"
295            | "timeofday"
296            | "gen_random_uuid"
297            | "uuidv4"
298            | "uuidv7"
299            | "create_analyzer"
300            | "drop_analyzer"
301            | "set_table_analyzer"
302            | "graph_create"
303            | "graph_drop"
304            | "create_graph"
305            | "drop_graph"
306            | "graph_exists"
307            | "create_vlabel"
308            | "create_elabel"
309            | "drop_label"
310            | "alter_graph"
311            | "cypher"
312            | "deep_learn"
313            // Retrieval calibration learns and persists parameters on a
314            // cache miss; it therefore is not a read-only scalar operation.
315            | "bayesian_match"
316            | "bayesian_match_with_prior"
317            | "fts_match"
318            | "multi_field_match"
319    )
320}
321
322pub fn expr_contains_volatile_function(catalog: &dyn VolatilityCatalog, expr: &ScalarExpr) -> bool {
323    expr_contains_volatile_function_with(catalog, expr, true)
324}
325
326/// Inspect calls in this scalar expression only. The caller must inspect query-valued children through their owning arena before moving or duplicating an expression.
327pub fn scalar_calls_are_volatile(catalog: &dyn VolatilityCatalog, expr: &ScalarExpr) -> bool {
328    expr_contains_volatile_function_with(catalog, expr, false)
329}
330
331/// Query-level walks inspect a block's subquery plans themselves, so their expression scan treats a subquery reference as opaque-but-inspected (`conservative_subqueries == false`) instead of assuming volatility.
332fn expr_contains_volatile_function_with(
333    catalog: &dyn VolatilityCatalog,
334    expr: &ScalarExpr,
335    conservative_subqueries: bool,
336) -> bool {
337    production::expression_contains_volatile_with_control(
338        catalog,
339        expr,
340        conservative_subqueries,
341        &uqa_core::memory::ProductionControl::uncontrolled(),
342    )
343    .expect("ordinary scalar volatility has no resource failure")
344}
345
346/// Inspect a scalar plan with its query arena instead of treating every subquery as an opaque volatile call.
347pub fn expression_plan_contains_volatile_function(
348    catalog: &dyn VolatilityCatalog,
349    plan: &crate::plan::ExpressionPlan,
350) -> Result<bool, SQLError> {
351    scalar_with_subqueries_contains_volatile_function(catalog, &plan.scalar, &plan.subqueries)
352}
353
354/// Inspect a borrowed expression and only the query children it references in its owning arena. Other projections may share that arena without contributing effects to this expression.
355pub fn scalar_with_subqueries_contains_volatile_function(
356    catalog: &dyn VolatilityCatalog,
357    scalar: &ScalarExpr,
358    subqueries: &[QueryPlan],
359) -> Result<bool, SQLError> {
360    scalar_in_scope_contains_volatile_function(catalog, scalar, subqueries, &|_| false)
361}
362
363/// Inspect an expression's referenced subqueries under its enclosing CTE namespace. Those external producers are owned and evaluated by their defining query, not by this scalar expression.
364pub fn scalar_in_scope_contains_volatile_function(
365    catalog: &dyn VolatilityCatalog,
366    scalar: &ScalarExpr,
367    subqueries: &[QueryPlan],
368    visible_ctes: &dyn Fn(&str) -> bool,
369) -> Result<bool, SQLError> {
370    scalar_in_scope_contains_volatile_function_with_control(
371        catalog,
372        scalar,
373        subqueries,
374        visible_ctes,
375        &uqa_core::memory::ProductionControl::uncontrolled(),
376    )
377}
378
379/// The block's own subquery plans are inspected separately by the query-level walk, so subquery references here are not conservatively volatile.
380pub fn select_contains_volatile_function(
381    catalog: &dyn VolatilityCatalog,
382    block: &QueryBlockPlan,
383) -> bool {
384    select_contains_volatile_function_with_control(
385        catalog,
386        block,
387        &uqa_core::memory::ProductionControl::uncontrolled(),
388    )
389    .expect("ordinary block volatility")
390}
391
392/// Inspect a complete query, including transitive view dependencies.
393pub fn query_contains_volatile_function(
394    catalog: &dyn VolatilityCatalog,
395    plan: &QueryPlan,
396) -> Result<bool, SQLError> {
397    query_contains_volatile_function_with_control(
398        catalog,
399        plan,
400        &uqa_core::memory::ProductionControl::uncontrolled(),
401    )
402}
403
404/// Whether scalar optimizer rewrites or `DPccp` join enumeration must preserve volatile call scheduling. Borrow the plan and its expression roots; inspecting constants must not copy their retained payloads or allocate command child lists.
405pub fn unified_plan_contains_volatile_function(
406    catalog: &dyn VolatilityCatalog,
407    plan: &UnifiedPlan,
408) -> bool {
409    unified_plan_contains_volatile_function_with_control(
410        catalog,
411        plan,
412        &uqa_core::memory::ProductionControl::uncontrolled(),
413    )
414    .expect("ordinary statement volatility")
415}
416
417#[cfg(test)]
418mod tests;