Skip to main content

uqa_engine/
queries.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Engine query entry points, statement gates, execution clocks and the statement thread context.
8
9use uqa_execution::ColumnarBatch;
10
11use crate::{Engine, SQLCursor, SQLCursorSummary};
12use uqa_sql::{SQLError, SQLParam, SQLResult};
13
14struct SQLExecutionScope<'a> {
15    engine: &'a Engine,
16    depth: &'a std::sync::atomic::AtomicUsize,
17    statement_clock: &'a std::sync::atomic::AtomicI64,
18    previous_clock: Option<i64>,
19    /// The statement thread context, whose transaction start the statement's input functions and `now()` read and whose cancellation its evaluation observes, entered for the outermost statement on the executing thread; a nested statement keeps its caller's.
20    _statement_thread: Option<uqa_execution::statement::thread_scope::StatementThreadScope>,
21}
22
23impl<'a> SQLExecutionScope<'a> {
24    fn enter(engine: &'a Engine) -> (Self, bool) {
25        let depth = &engine.runtime.sql_execution_depth;
26        let statement_clock = &engine.session.statement_started_at_micros;
27        let nested = depth.fetch_add(1, std::sync::atomic::Ordering::Relaxed) != 0;
28        let previous_clock = (!nested).then(|| {
29            statement_clock.swap(
30                uqa_sql::expr::clock_timestamp_micros(),
31                std::sync::atomic::Ordering::Relaxed,
32            )
33        });
34        let statement_thread = (!nested).then(|| engine.statement_thread_context().enter());
35        (
36            Self {
37                engine,
38                depth,
39                statement_clock,
40                previous_clock,
41                _statement_thread: statement_thread,
42            },
43            nested,
44        )
45    }
46}
47
48impl Drop for SQLExecutionScope<'_> {
49    fn drop(&mut self) {
50        if let Some(previous) = self.previous_clock {
51            self.statement_clock
52                .store(previous, std::sync::atomic::Ordering::Relaxed);
53        }
54        let previous = self
55            .depth
56            .fetch_sub(1, std::sync::atomic::Ordering::Relaxed);
57        debug_assert!(previous != 0, "SQL execution depth underflow");
58        // A statement outside a transaction block runs in a transaction of its own, so the LOCAL assignments it made (`set_config(..., true)`) end with it.
59        if previous == 1 && self.engine.transaction_depth() == 0 {
60            self.engine.restore_local_runtime_parameters();
61        }
62    }
63}
64
65impl Engine {
66    /// Bind retained regex state after provider initialization, which can install the native session allowance during initial catalog restoration.
67    pub(crate) fn session_regex_cache(&self) -> std::sync::Arc<uqa_sql::expr::RegexCache> {
68        let budget = self
69            .storage
70            .backend
71            .as_ref()
72            .and_then(|backend| backend.retention_control())
73            .map_or_else(
74                || self.session.query_retention.clone(),
75                |control| control.memory().clone(),
76            );
77        let mut retained = self.session.regex_cache.lock();
78        if let Some(cache) = retained
79            .as_ref()
80            .filter(|cache| cache.shares_allowance(&budget))
81        {
82            return cache.clone();
83        }
84        let cache = std::sync::Arc::new(uqa_sql::expr::RegexCache::new(budget));
85        *retained = Some(cache.clone());
86        cache
87    }
88
89    /// The thread context this session's statements evaluate under: its transaction clock, live date order and interval style, cancellation token and retained regex cache. Direct APIs that evaluate SQL expressions outside a statement enter the same context.
90    pub(crate) fn statement_thread_context(
91        &self,
92    ) -> uqa_execution::statement::thread_context::StatementThreadContext {
93        uqa_execution::statement::thread_context::StatementThreadContext {
94            retained_rows:
95                uqa_execution::query::sources::retained_source::RetainedRowContext::current(),
96            regex_cache: Some(self.session_regex_cache()),
97            temporal_input: uqa_sql::expr::TemporalInputContext {
98                transaction_clock_micros: self.session_transaction_clock_micros(),
99                interval_style: self.session.interval_style(),
100                date_order: uqa_sql::semantics::parameters::datestyle::date_order(
101                    &self.session.setting("DateStyle"),
102                ),
103            },
104            cancellation: Some(self.runtime.cancellation.clone()),
105        }
106    }
107
108    /// Public typed reads own a statement boundary; internal execution adapters retain their caller's existing scope instead.
109    pub(crate) fn with_direct_read_snapshot<R>(
110        &self,
111        read: impl FnOnce(&Self) -> Result<R, SQLError>,
112    ) -> Result<R, SQLError> {
113        self.with_direct_query_snapshot(true, read, std::convert::identity)
114    }
115
116    pub(crate) fn with_catalog_read_snapshot<R>(
117        &self,
118        read: impl FnOnce(&Self) -> uqa_storage::StorageBackendResult<R>,
119    ) -> uqa_storage::StorageBackendResult<R> {
120        self.with_direct_query_snapshot(true, read, |error| {
121            uqa_storage::StorageBackendError::backend("catalog query", error)
122        })
123    }
124
125    pub(crate) fn with_direct_query_snapshot<R, E: std::fmt::Display>(
126        &self,
127        read_only: bool,
128        query: impl FnOnce(&Self) -> Result<R, E>,
129        map_transaction_error: impl Fn(SQLError) -> E,
130    ) -> Result<R, E> {
131        let _statement = self.lock_statement_gate();
132        let (_execution, nested) = SQLExecutionScope::enter(self);
133        self.with_query_transaction_snapshot(!nested, read_only, query, map_transaction_error)
134    }
135
136    /// Execute a simple-query message, delivering each statement's result in order. The whole message is parsed before execution, and implicit transaction segments retain the same boundaries as [`Engine::sql`]. The final result is delivered only after its implicit transaction has committed. Earlier results may have been delivered when a later statement fails; such failure still rolls back its implicit segment. An empty message delivers one result with no command completion.
137    pub fn sql_simple_query(
138        &self,
139        query: &str,
140        params: &[SQLParam],
141        mut consume: impl FnMut(&SQLResult) -> Result<(), SQLError>,
142    ) -> Result<(), SQLError> {
143        let _statement = self.lock_statement_gate();
144        let (_execution, nested) = SQLExecutionScope::enter(self);
145        self.synchronize_table_catalog()
146            .map_err(|error| SQLError::Internal(format!("refresh table catalog: {error}")))?;
147        self.synchronize_table_data().map_err(|error| {
148            SQLError::Internal(format!("refresh committed table data: {error}"))
149        })?;
150        self.synchronize_catalog_registries().map_err(|error| {
151            SQLError::Internal(format!("refresh durable catalog registries: {error}"))
152        })?;
153        uqa_execution::statement::batch::execute_simple_query(
154            &self.batch_execution_context(),
155            query,
156            params,
157            nested,
158            &mut consume,
159        )
160    }
161
162    /// Run a single SQL statement against the engine.
163    pub fn sql(&self, query: &str, params: &[SQLParam]) -> Result<SQLResult, SQLError> {
164        let _statement = self.lock_statement_gate();
165        let (_execution, nested) = SQLExecutionScope::enter(self);
166        self.synchronize_table_catalog()
167            .map_err(|err| SQLError::Internal(format!("refresh table catalog: {err}")))?;
168        self.synchronize_table_data()
169            .map_err(|err| SQLError::Internal(format!("refresh committed table data: {err}")))?;
170        self.synchronize_catalog_registries().map_err(|err| {
171            SQLError::Internal(format!("refresh durable catalog registries: {err}"))
172        })?;
173        if nested {
174            uqa_execution::statement::batch::execute_nested(
175                &self.batch_execution_context(),
176                query,
177                params,
178            )
179        } else {
180            uqa_execution::statement::batch::execute(&self.batch_execution_context(), query, params)
181        }
182    }
183
184    /// Execute one read query into a bounded spill and return a columnar batch
185    /// cursor. Unlike [`Engine::sql`], this path never retains the complete
186    /// result as `Vec<ResultRow>` in memory. The statement finishes and its
187    /// snapshot is committed before the cursor is returned.
188    pub fn sql_cursor(&self, query: &str, params: &[SQLParam]) -> Result<SQLCursor, SQLError> {
189        let _statement = self.lock_statement_gate();
190        let (_execution, _) = SQLExecutionScope::enter(self);
191        self.synchronize_table_catalog()
192            .map_err(|err| SQLError::Internal(format!("refresh table catalog: {err}")))?;
193        self.synchronize_table_data()
194            .map_err(|err| SQLError::Internal(format!("refresh committed table data: {err}")))?;
195        self.synchronize_catalog_registries().map_err(|err| {
196            SQLError::Internal(format!("refresh durable catalog registries: {err}"))
197        })?;
198        uqa_execution::statement::cursor::execute(&self.batch_execution_context(), query, params)
199    }
200
201    /// Consume the bounded cursor synchronously without retaining batches.
202    pub fn sql_columnar(
203        &self,
204        query: &str,
205        params: &[SQLParam],
206        mut consume: impl FnMut(ColumnarBatch) -> Result<(), SQLError>,
207    ) -> Result<SQLCursorSummary, SQLError> {
208        let mut cursor = self.sql_cursor(query, params)?;
209        let summary = cursor.summary();
210        for batch in &mut cursor {
211            consume(batch?)?;
212        }
213        Ok(summary)
214    }
215}