Skip to main content

uqa_engine/
sql_registry.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7use super::{
8    Arc, Engine, RegisteredSQLFunction, SQLAggregateFunction, SQLError, SQLFunctionOptions,
9    SQLFunctionVolatility, SQLScalarFunction, SQLTableFunction, Value,
10};
11
12impl Engine {
13    fn normalize_sql_function_name(name: &str) -> std::result::Result<String, SQLError> {
14        let normalized = name.trim().to_ascii_lowercase();
15        if normalized.is_empty() {
16            return Err(SQLError::TypeMismatch(
17                "SQL function name cannot be empty".into(),
18            ));
19        }
20        Ok(normalized)
21    }
22
23    pub fn register_scalar_function<F>(
24        &self,
25        name: &str,
26        function: F,
27    ) -> std::result::Result<(), SQLError>
28    where
29        F: SQLScalarFunction + 'static,
30    {
31        self.register_scalar_function_with_options(name, SQLFunctionOptions::default(), function)
32    }
33
34    /// Register a Rust scalar callback with explicit optimizer and transaction
35    /// properties.
36    pub fn register_scalar_function_with_options<F>(
37        &self,
38        name: &str,
39        options: SQLFunctionOptions,
40        function: F,
41    ) -> std::result::Result<(), SQLError>
42    where
43        F: SQLScalarFunction + 'static,
44    {
45        Self::validate_sql_function_options(options)?;
46        let name = Self::normalize_sql_function_name(name)?;
47        self.extensions.scalar_functions.write().insert(
48            name.clone(),
49            RegisteredSQLFunction::new(Arc::new(function), options),
50        );
51        self.clear_sql_statement_cache();
52        self.invalidate_prepared_analysis();
53        Ok(())
54    }
55
56    pub fn register_table_function<F>(
57        &self,
58        name: &str,
59        function: F,
60    ) -> std::result::Result<(), SQLError>
61    where
62        F: SQLTableFunction + 'static,
63    {
64        self.register_table_function_with_options(name, SQLFunctionOptions::default(), function)
65    }
66
67    /// Register a Rust table callback with explicit optimizer and transaction
68    /// properties.
69    pub fn register_table_function_with_options<F>(
70        &self,
71        name: &str,
72        options: SQLFunctionOptions,
73        function: F,
74    ) -> std::result::Result<(), SQLError>
75    where
76        F: SQLTableFunction + 'static,
77    {
78        Self::validate_sql_function_options(options)?;
79        let name = Self::normalize_sql_function_name(name)?;
80        self.extensions.table_functions.write().insert(
81            name.clone(),
82            RegisteredSQLFunction::new(Arc::new(function), options),
83        );
84        self.clear_sql_statement_cache();
85        self.invalidate_prepared_analysis();
86        Ok(())
87    }
88
89    pub fn register_aggregate_function<F>(
90        &self,
91        name: &str,
92        function: F,
93    ) -> std::result::Result<(), SQLError>
94    where
95        F: SQLAggregateFunction + 'static,
96    {
97        self.register_aggregate_function_with_options(name, SQLFunctionOptions::default(), function)
98    }
99
100    /// Register a Rust aggregate callback with explicit optimizer and
101    /// transaction properties.
102    pub fn register_aggregate_function_with_options<F>(
103        &self,
104        name: &str,
105        options: SQLFunctionOptions,
106        function: F,
107    ) -> std::result::Result<(), SQLError>
108    where
109        F: SQLAggregateFunction + 'static,
110    {
111        Self::validate_sql_function_options(options)?;
112        let name = Self::normalize_sql_function_name(name)?;
113        self.extensions.aggregate_functions.write().insert(
114            name.clone(),
115            RegisteredSQLFunction::new(Arc::new(function), options),
116        );
117        // Aggregate-vs-projection is a structural choice in `QueryPlan`.
118        // Cached plans compiled before this registration must be rebound.
119        self.clear_sql_statement_cache();
120        self.invalidate_prepared_analysis();
121        Ok(())
122    }
123
124    fn validate_sql_function_options(options: SQLFunctionOptions) -> Result<(), SQLError> {
125        if options.may_mutate_engine && options.volatility != SQLFunctionVolatility::Volatile {
126            return Err(SQLError::TypeMismatch(
127                "a callback that may mutate engine state must be VOLATILE".into(),
128            ));
129        }
130        Ok(())
131    }
132
133    pub(crate) fn call_registered_scalar_function(
134        &self,
135        name: &str,
136        args: &[Value],
137    ) -> Option<std::result::Result<Value, SQLError>> {
138        let registration = self.query_runtime_view().lookup_scalar_function(name)?;
139        Some(
140            uqa_sql::expr::enums::render_host_arguments(Some(self), args)
141                .and_then(|args| registration.function.call(&args)),
142        )
143    }
144
145    pub(crate) fn has_registered_scalar_functions(&self) -> bool {
146        self.query_runtime_view().has_scalar_functions()
147    }
148
149    pub(crate) fn has_registered_scalar_function(&self, name: &str) -> bool {
150        self.query_runtime_view().has_scalar_function(name)
151    }
152
153    pub(crate) fn has_registered_table_function(&self, name: &str) -> bool {
154        self.query_runtime_view().has_table_function(name)
155    }
156
157    pub(crate) fn has_registered_aggregate_function(&self, name: &str) -> bool {
158        self.query_runtime_view().has_aggregate_function(name)
159    }
160
161    pub(crate) fn registered_aggregate_function(
162        &self,
163        name: &str,
164    ) -> Option<Arc<dyn SQLAggregateFunction>> {
165        self.query_runtime_view()
166            .lookup_aggregate_function(name)
167            .map(|registration| registration.function)
168    }
169
170    pub(crate) fn registered_runtime_function_may_mutate_engine(&self, name: &str) -> bool {
171        self.registered_runtime_function_options(name)
172            .into_iter()
173            .flatten()
174            .any(|options| options.may_mutate_engine)
175    }
176
177    pub(crate) fn registered_runtime_function_volatility(
178        &self,
179        name: &str,
180    ) -> Option<SQLFunctionVolatility> {
181        let mut volatility = None;
182        for options in self
183            .registered_runtime_function_options(name)
184            .into_iter()
185            .flatten()
186        {
187            volatility = Some(match (volatility, options.volatility) {
188                (_, SQLFunctionVolatility::Volatile)
189                | (Some(SQLFunctionVolatility::Volatile), _) => SQLFunctionVolatility::Volatile,
190                (_, SQLFunctionVolatility::Stable) | (Some(SQLFunctionVolatility::Stable), _) => {
191                    SQLFunctionVolatility::Stable
192                }
193                _ => SQLFunctionVolatility::Immutable,
194            });
195        }
196        volatility
197    }
198
199    fn registered_runtime_function_options(&self, name: &str) -> [Option<SQLFunctionOptions>; 3] {
200        self.query_runtime_view().registered_function_options(name)
201    }
202}