Skip to main content

vantage_table/table/impls/
selectable.rs

1use std::cell::Cell;
2use std::sync::Arc;
3
4use vantage_core::{Result, error};
5use vantage_expressions::traits::selectable::Selectable;
6use vantage_expressions::{Expression, Expressive, SelectableDataSource, expr_any};
7use vantage_types::{EmptyEntity, Entity};
8
9use crate::{
10    column::core::ColumnType,
11    source::{SelectSeed, SelectSource},
12    table::Table,
13    traits::column_like::ColumnLike,
14    traits::table_source::TableSource,
15};
16
17thread_local! {
18    /// Set while a dotted column's target is built only to look the column up.
19    /// That build leaves out the target's own dotted columns: nothing traverses
20    /// them, and a self-reference (`manager.name` on `employee`) or a cycle of
21    /// them would otherwise rebuild the tables until the stack runs out.
22    static RESOLVING_DOTTED: Cell<bool> = const { Cell::new(false) };
23}
24
25/// Marks this thread as resolving a dotted column until dropped, restoring the
26/// previous state (an error or panic mid-build included).
27struct ResolvingDotted(bool);
28
29impl ResolvingDotted {
30    fn enter() -> Self {
31        Self(RESOLVING_DOTTED.with(|r| r.replace(true)))
32    }
33}
34
35impl Drop for ResolvingDotted {
36    fn drop(&mut self) {
37        RESOLVING_DOTTED.with(|r| r.set(self.0));
38    }
39}
40
41fn resolving_dotted() -> bool {
42    RESOLVING_DOTTED.with(Cell::get)
43}
44
45impl<T, E> Table<T, E>
46where
47    T: SelectableDataSource<T::Value, T::Condition> + TableSource,
48    T::Source: SelectSeed<T::Select, T::Value, T::Condition>,
49    T::Value: From<String>, // that's because table is specified as a string
50    E: Entity<T::Value>,
51{
52    /// Create a bare select with source, conditions, ordering, and pagination —
53    /// but no fields. Used by `select_column` and aggregates to avoid evaluating
54    /// all expressions.
55    pub fn select_empty(&self) -> T::Select {
56        let mut select = self.data_source.select();
57        self.source.seed(&mut select);
58
59        for condition in self.conditions.values() {
60            select.add_where_condition(condition.clone());
61        }
62
63        for (expr, direction) in self.order_by.values() {
64            let order = match direction {
65                crate::sorting::SortDirection::Ascending => vantage_expressions::Order::Asc,
66                crate::sorting::SortDirection::Descending => vantage_expressions::Order::Desc,
67            };
68            select.add_order_by(expr.clone(), order);
69        }
70
71        if let Some(pagination) = &self.pagination {
72            select.set_limit(Some(pagination.limit()), Some(pagination.skip()));
73        }
74
75        select
76    }
77
78    /// Create a select query with table configuration applied.
79    ///
80    /// Panics if an expression callback fails; use
81    /// [`try_select`](Self::try_select).
82    pub fn select(&self) -> T::Select {
83        self.try_select().unwrap_or_else(|e| panic!("{e}"))
84    }
85
86    /// Create a select query with table configuration applied. Runs the
87    /// callback of each expression column in the projection, and of no
88    /// other; a failing callback's error names its column and table.
89    pub fn try_select(&self) -> Result<T::Select> {
90        let mut select = self.select_empty();
91
92        for column in self.columns.values() {
93            // Lazy-expression columns exist only on returned records — the
94            // source has no such field to project (SQLite would silently
95            // degrade the unknown quoted identifier to a string literal;
96            // other SQL backends would error).
97            if self.lazy_expressions.contains_key(column.name()) {
98                continue;
99            }
100            // With an active-column set, project only its members. The id
101            // column is always projected — consumers rely on it to key rows.
102            if !self.is_active_column(column.name()) {
103                continue;
104            }
105            if let Some(expr) = self.try_expression_column(column.name())? {
106                self.data_source.add_select_column(
107                    &mut select,
108                    expr_any!("({})", (expr)),
109                    Some(column.name()),
110                );
111            } else if let Some(alias) = column.alias() {
112                let expr = self.data_source.expr(column.name(), vec![]);
113                self.data_source
114                    .add_select_column(&mut select, expr, Some(alias));
115            } else {
116                select.add_field(column.name());
117            }
118        }
119
120        for name in self.expressions.keys() {
121            if !self.columns.contains_key(name)
122                && self.is_active_column(name)
123                && let Some(expr) = self.try_expression_column(name)?
124            {
125                self.data_source.add_select_column(
126                    &mut select,
127                    expr_any!("({})", (expr)),
128                    Some(name),
129                );
130            }
131        }
132
133        Ok(select)
134    }
135
136    /// A select of this table's rows with one field: `column`, or its
137    /// expression when it is an expression column. No other callback runs.
138    /// Used for `IN (subquery)` joins and by aggregates.
139    pub fn try_select_only<Type>(&self, column: &T::Column<Type>) -> Result<T::Select>
140    where
141        Type: ColumnType,
142    {
143        let mut select = self.select_empty();
144        select.clear_order_by();
145        match self.try_expression_column(column.name())? {
146            Some(expr) => select.add_expression(expr_any!("({})", (expr))),
147            None => select.add_field(column.name()),
148        }
149        Ok(select)
150    }
151    /// Get count of records in the table
152    pub async fn get_count(&self) -> Result<i64> {
153        self.check_read().await?;
154        self.data_source.get_table_count(self).await
155    }
156
157    /// Get sum of a column in the table
158    pub async fn get_sum(&self, column: &T::Column<T::AnyType>) -> Result<T::Value> {
159        self.check_read().await?;
160        self.data_source.get_table_sum(self, column).await
161    }
162
163    /// Get max of a column in the table
164    pub async fn get_max(&self, column: &T::Column<T::AnyType>) -> Result<T::Value> {
165        self.check_read().await?;
166        self.data_source.get_table_max(self, column).await
167    }
168
169    /// Get min of a column in the table
170    pub async fn get_min(&self, column: &T::Column<T::AnyType>) -> Result<T::Value> {
171        self.check_read().await?;
172        self.data_source.get_table_min(self, column).await
173    }
174
175    /// Create a count query expression (does not execute).
176    /// The result is wrapped in parentheses so it's safe to nest as a subquery.
177    pub fn get_count_query(&self) -> Expression<T::Value> {
178        expr_any!("({})", (self.select_empty().as_count()))
179    }
180
181    /// Create a sum query expression for a column (does not execute).
182    /// The result is wrapped in parentheses so it's safe to nest as a subquery.
183    pub fn get_sum_query<Type>(&self, column: &T::Column<Type>) -> Expression<T::Value>
184    where
185        Type: ColumnType,
186        T::Column<Type>: Expressive<T::Value>,
187    {
188        expr_any!("({})", (self.select_empty().as_sum(column.expr())))
189    }
190
191    /// Create a min query expression for a column (does not execute), in
192    /// parentheses like [`Self::get_sum_query`].
193    pub fn get_min_query<Type>(&self, column: &T::Column<Type>) -> Expression<T::Value>
194    where
195        Type: ColumnType,
196        T::Column<Type>: Expressive<T::Value>,
197    {
198        expr_any!("({})", (self.select_empty().as_min(column.expr())))
199    }
200
201    /// Create a max query expression for a column (does not execute), in
202    /// parentheses like [`Self::get_sum_query`].
203    pub fn get_max_query<Type>(&self, column: &T::Column<Type>) -> Expression<T::Value>
204    where
205        Type: ColumnType,
206        T::Column<Type>: Expressive<T::Value>,
207    {
208        expr_any!("({})", (self.select_empty().as_max(column.expr())))
209    }
210
211    /// Create an average query expression for a column (does not execute), in
212    /// parentheses like [`Self::get_sum_query`].
213    pub fn get_avg_query<Type>(&self, column: &T::Column<Type>) -> Expression<T::Value>
214    where
215        Type: ColumnType,
216        T::Column<Type>: Expressive<T::Value>,
217        T::Select: Expressive<T::Value>,
218    {
219        expr_any!("({})", (self.select_empty().as_avg(column.expr())))
220    }
221
222    /// Create a subquery expression that selects a single column from this table.
223    ///
224    /// Builds `SELECT field FROM table WHERE conditions` — useful as a correlated
225    /// subquery inside `with_expression`. Returns `None` if `field` is not a
226    /// column on this table (mirroring [`get_column_expr`](Self::get_column_expr),
227    /// its panic on a failing expression callback included);
228    /// when the caller hardcodes a known column name, `.expect(...)` is fine:
229    ///
230    /// ```rust,ignore
231    /// .with_expression("category", |t| {
232    ///     t.get_subquery_as::<Category>("category").unwrap()
233    ///         .select_column("name")
234    ///         .expect("Category has a 'name' column")
235    /// })
236    /// ```
237    pub fn select_column(&self, field: &str) -> Option<Expression<T::Value>>
238    where
239        T::Column<T::AnyType>: Expressive<T::Value>,
240        T::Select: Expressive<T::Value>,
241    {
242        Some(self.select_expression(self.get_column_expr(field)?))
243    }
244
245    /// Wrap an arbitrary expression as a single-column subquery over this
246    /// table's source and conditions: `(SELECT <expr> FROM table WHERE …)`.
247    ///
248    /// Extracted from [`select_column`](Self::select_column) so a traversal
249    /// expression can nest one subquery inside another (multi-hop implicit
250    /// references). Fields and ordering are cleared — only `expr` is projected.
251    pub fn select_expression(&self, expr: Expression<T::Value>) -> Expression<T::Value>
252    where
253        T::Select: Expressive<T::Value>,
254    {
255        let mut select = self.select_empty();
256        select.clear_fields();
257        select.clear_order_by();
258        select.add_expression(expr);
259        select.expr()
260    }
261
262    /// Restrict this table to an explicit set of columns, and import **implicit
263    /// references** — dotted names that traverse declared `has_one` relations
264    /// and surface the target's field as a read-only, typed column aliased
265    /// under the literal dotted name.
266    ///
267    /// ```rust,ignore
268    /// let orders = Order::sqlite_table(db)
269    ///     .with_active_columns(&["id", "client.name", "client.bakery.name"])?;
270    /// // SELECT id,
271    /// //   (SELECT name FROM client WHERE client.id = client_order.client_id) AS "client.name",
272    /// //   (SELECT (SELECT name FROM bakery WHERE bakery.id = client.bakery_id)
273    /// //      FROM client WHERE client.id = client_order.client_id)           AS "client.bakery.name"
274    /// // FROM client_order
275    /// ```
276    ///
277    /// A non-dotted entry restricts projection to an existing column or
278    /// expression column (exactly today's declared set). A dotted entry `a.b…c`
279    /// resolves `a`, `b`… as `has_one` relations and `c` as a column on the
280    /// final target. Everything is validated here, so every failure is a
281    /// **build-time** error, never a fetch-time surprise: unknown column,
282    /// unknown relation, a `has_many` hop, or a backend that cannot lower
283    /// traversal into its query (e.g. CSV, REST). Same-datasource
284    /// only; cross-datasource traversal is a Diorama augmentation concern.
285    pub fn with_active_columns(mut self, cols: &[&str]) -> Result<Self>
286    where
287        T: 'static,
288        E: 'static,
289        T::Column<T::AnyType>: Expressive<T::Value>,
290        T::Select: Expressive<T::Value>,
291    {
292        for &col in cols {
293            let parts: Vec<&str> = col.split('.').collect();
294            if parts.iter().any(|p| p.is_empty()) {
295                return Err(error!("invalid active column name", column = col));
296            }
297
298            if parts.len() >= 2 {
299                // A target built only to look up a dotted column carries no
300                // dotted columns of its own (see `RESOLVING_DOTTED`).
301                if resolving_dotted() {
302                    continue;
303                }
304                self.import_dotted_column(col)?;
305                self.active_columns
306                    .get_or_insert_with(Default::default)
307                    .insert(col.to_string());
308            } else {
309                // Expression columns registered via `with_expression` alone
310                // (no column def) are projectable too — activating them must
311                // work, or an active set would silently drop them for good.
312                if !self.columns.contains_key(col) && !self.expressions.contains_key(col) {
313                    return Err(error!("unknown active column", column = col));
314                }
315                self.active_columns
316                    .get_or_insert_with(Default::default)
317                    .insert(col.to_string());
318            }
319        }
320        Ok(self)
321    }
322
323    /// Import a dotted implicit-reference column (`a.b…c`) **additively**:
324    /// the column joins the projection without restricting it, so the
325    /// declared columns keep flowing. Use this to give one consumer (an API
326    /// vista, a page) an extra traversal column that the shared table
327    /// definition does not carry.
328    pub fn with_imported_column(mut self, col: &str) -> Result<Self>
329    where
330        T: 'static,
331        E: 'static,
332        T::Column<T::AnyType>: Expressive<T::Value>,
333        T::Select: Expressive<T::Value>,
334    {
335        self.import_dotted_column(col)?;
336        Ok(self)
337    }
338
339    /// In-place form of [`with_imported_column`](Self::with_imported_column).
340    pub fn add_imported_column(&mut self, col: &str) -> Result<()>
341    where
342        T: 'static,
343        E: 'static,
344        T::Column<T::AnyType>: Expressive<T::Value>,
345        T::Select: Expressive<T::Value>,
346    {
347        self.import_dotted_column(col)
348    }
349
350    /// Shared body of the dotted branch: validate the `has_one` chain, lower
351    /// it to an expression (native idiom path or nested subqueries), register
352    /// the dotted alias as a column + expression and mark it imported. Does
353    /// NOT touch `active_columns` — the caller decides whether the projection
354    /// is restricted.
355    fn import_dotted_column(&mut self, col: &str) -> Result<()>
356    where
357        T: 'static,
358        E: 'static,
359        T::Column<T::AnyType>: Expressive<T::Value>,
360        T::Select: Expressive<T::Value>,
361    {
362        let parts: Vec<&str> = col.split('.').collect();
363        if parts.len() < 2 || parts.iter().any(|p| p.is_empty()) {
364            return Err(error!("invalid dotted column name", column = col));
365        }
366        let column = parts[parts.len() - 1];
367        let hops = &parts[..parts.len() - 1];
368        if resolving_dotted() {
369            return Ok(());
370        }
371
372        if !self.data_source().supports_traversal() {
373            return Err(error!(
374                "backend does not support implicit-reference traversal in columns",
375                column = col
376            ));
377        }
378
379        // Every table built from here to the lowering below is built only to
380        // look the column up.
381        let resolving = ResolvingDotted::enter();
382        let (target, fk_hops) = self.resolve_has_one_target(hops)?;
383        let computed = target.is_calculated_column(column);
384        if !computed && !target.columns().contains_key(column) {
385            return Err(error!(
386                "implicit reference target has no such column",
387                column = column
388            ));
389        }
390
391        // Lower to an expression: native path first, else the generic
392        // nested correlated-subquery chain. The native path receives
393        // the foreign-key/link *fields*, not the relation names — a
394        // SurrealDB idiom path traverses record-link fields, and a
395        // relation is free to be named differently from its FK
396        // (`with_one("owner", "client", …)` must lower to
397        // `client.name`, not the nonexistent `owner.name`). A computed target
398        // column has no field to follow, so it takes the subquery chain,
399        // which renders the target's expression; a backend with a native
400        // path (SurrealDB) reads a list of rows there, not one value, so it
401        // is refused.
402        let fk_refs: Vec<&str> = fk_hops.iter().map(String::as_str).collect();
403        let native = self.data_source().traversal_path_expr(&fk_refs, column);
404        let expr = match (native, computed) {
405            (Some(_), true) => {
406                return Err(error!(
407                    format!(
408                        "dotted column `{col}`: `{column}` is a computed column of `{}`; \
409                         this backend can't read it through the link, declare an `expr:` \
410                         on this table instead",
411                        hops.join(".")
412                    ),
413                    column = col
414                ));
415            }
416            (Some(e), false) => e,
417            (None, _) => self.traverse_rest_generic(hops, column)?,
418        };
419        drop(resolving);
420
421        let dotted = col.to_string();
422        if !self.columns.contains_key(&dotted) {
423            let column_def = self.data_source.create_column::<T::AnyType>(&dotted);
424            self.add_column(column_def);
425        }
426        let wrapped: crate::table::base::ExpressionFn<T> = Arc::new(move |_| Ok(expr.clone()));
427        self.expressions.insert(dotted.clone(), wrapped);
428        self.imported_columns.insert(dotted.clone());
429        Ok(())
430    }
431
432    /// Recursively lower a dotted implicit reference into nested correlated
433    /// subqueries. One hop wraps the recursion's inner expression in a
434    /// `get_subquery_as` target via [`select_expression`](Self::select_expression);
435    /// the base case projects the final column. Used only when the backend has
436    /// no native [`traversal_path_expr`](crate::prelude::TableSource::traversal_path_expr).
437    fn traverse_rest_generic(&self, hops: &[&str], column: &str) -> Result<Expression<T::Value>>
438    where
439        T: 'static,
440        E: 'static,
441        T::Column<T::AnyType>: Expressive<T::Value>,
442        T::Select: Expressive<T::Value>,
443    {
444        match hops.split_first() {
445            None => self.try_get_column_expr(column)?.ok_or_else(|| {
446                error!(
447                    "implicit reference target has no such column",
448                    column = column
449                )
450            }),
451            Some((head, tail)) => {
452                let target: Table<T, EmptyEntity> = self.get_subquery_erased(head)?;
453                let inner = target.traverse_rest_generic(tail, column)?;
454                // The base case returns a bare column; a deeper hop returns a
455                // SELECT that must be parenthesized before it can nest as a
456                // scalar inside this hop's SELECT.
457                let inner = if tail.is_empty() {
458                    inner
459                } else {
460                    expr_any!("({})", (inner))
461                };
462                Ok(target.select_expression(inner))
463            }
464        }
465    }
466
467    /// Walk a chain of `has_one` hops and return the final target table along
468    /// with each hop's foreign-key/link field (in hop order), erroring at
469    /// build time on an unknown relation or a `has_many` hop. The FK fields
470    /// feed the backend-native path lowering, which traverses fields — the
471    /// relation *names* only address the refs registry.
472    fn resolve_has_one_target(&self, hops: &[&str]) -> Result<(Table<T, EmptyEntity>, Vec<String>)>
473    where
474        T: 'static,
475        E: 'static,
476    {
477        let (head, tail) = hops
478            .split_first()
479            .ok_or_else(|| error!("empty implicit reference path"))?;
480        if self.ref_cardinality(head)? != vantage_vista::ReferenceKind::HasOne {
481            return Err(error!(
482                "implicit reference hop must traverse a has_one relation",
483                relation = *head
484            ));
485        }
486        let fk = self.ref_foreign_key(head)?;
487        let target: Table<T, EmptyEntity> = self.get_ref_target_erased(head)?;
488        // The path follows the link the key holds, which only a single key
489        // on the target's id is.
490        let keys = self.ref_keys(head)?;
491        let target_id = target.id_field_name();
492        if keys.len() > 1 || keys[0].to.as_ref().is_some_and(|to| *to != target_id) {
493            return Err(error!(
494                "implicit reference hop must join the target's id by one key",
495                relation = *head
496            ));
497        }
498        if tail.is_empty() {
499            Ok((target, vec![fk]))
500        } else {
501            let (final_target, mut fks) = target.resolve_has_one_target(tail)?;
502            fks.insert(0, fk);
503            Ok((final_target, fks))
504        }
505    }
506}
507
508// Constructors for tables sourced from an arbitrary query (a derived / sub-SELECT
509// source). Only available to backends whose `Source` is `SelectSource<Select>`
510// (the four subquery-capable SQL/SurrealDB backends). `V`/`C`/`S` are named
511// explicitly rather than projected through `T` to avoid a bound-resolution cycle.
512impl<T, E, V, C, S> Table<T, E>
513where
514    T: SelectableDataSource<V, C, Select = S>
515        + TableSource<Value = V, Condition = C, Source = SelectSource<S>>,
516    V: Clone + Send + Sync + 'static + From<String>,
517    C: Clone + Send + Sync + 'static,
518    S: Expressive<V> + Clone,
519    E: Entity<V>,
520{
521    /// Build a read-only table whose FROM clause is `select`, exposed under
522    /// `alias`. Columns/relations start empty — declare or inherit them.
523    pub fn from_select(data_source: T, alias: impl Into<String>, select: S) -> Self {
524        let alias = alias.into();
525        let mut table = Table::new(alias.clone(), data_source);
526        table.source = SelectSource::query(select, alias);
527        table
528    }
529
530    /// Derive a table from an existing one: transform its select via `modifier`
531    /// and use the result as the (sub-SELECT) source, inheriting the listed
532    /// `columns` and `relations` plus identity/title metadata.
533    ///
534    /// Panics if one of `source`'s expression callbacks fails (it reads
535    /// `source.select()`).
536    ///
537    /// `modifier` receives `source.select()` and decides flat-vs-wrapped — it
538    /// may extend the query in place (joins referencing the base tables) or wrap
539    /// it as a subquery (to filter/sort on a computed alias). Conditions already
540    /// baked into the base select are not re-applied.
541    ///
542    /// Implicit references are **not** inherited: the derived table starts with
543    /// no active set, and listing an imported dotted column in `columns` copies
544    /// only its bare definition (no traversal expression, no read-only
545    /// tracking). Re-declare traversals on the derived table if needed.
546    pub fn derive_from<E2: Entity<V> + 'static>(
547        source: &Table<T, E2>,
548        alias: impl Into<String>,
549        modifier: impl FnOnce(S) -> S,
550        columns: &[&str],
551        relations: &[&str],
552    ) -> Self
553    where
554        T: 'static,
555        E: 'static,
556    {
557        let alias = alias.into();
558        let select = modifier(source.select());
559        let mut table = Table::new(alias.clone(), source.data_source().clone());
560        table.source = SelectSource::query(select, alias);
561        table.copy_columns_from(source, Some(columns));
562        table.copy_relations_from(source, Some(relations));
563        table.id_field = source.id_field.clone();
564        table.id_auto = source.id_auto;
565        table.title_field = source.title_field.clone();
566        table.title_fields = source.title_fields.clone();
567        table
568    }
569}
570
571impl<T, E> Table<T, E>
572where
573    T: SelectableDataSource<serde_json::Value, T::Condition>
574        + TableSource<Value = serde_json::Value>
575        + vantage_expressions::traits::datasource::ExprDataSource<serde_json::Value>,
576    T::Source: SelectSeed<T::Select, serde_json::Value, T::Condition>,
577    T::Value: From<String>,
578    E: Entity<serde_json::Value>,
579{
580    /// Get count using QuerySource for serde_json::Value
581    pub async fn get_count_via_query(&self) -> Result<i64> {
582        self.check_read().await?;
583        let count_query = self.get_count_query();
584        let result = self.data_source.execute(&count_query).await?;
585
586        // Unwrap a single-element array, e.g. `[{"count": 42}]` or `[42]`,
587        // which is how SQL/Surreal count queries commonly come back.
588        let result = match result.as_array().map(Vec::as_slice) {
589            Some([single]) => single,
590            _ => &result,
591        };
592
593        // Anything but `{"count": N}` or a bare `N` is an unexpected shape:
594        // surface it rather than silently reporting zero rows.
595        if let Some(count) = result.get("count").and_then(|v| v.as_i64()) {
596            Ok(count)
597        } else if let Some(count) = result.as_i64() {
598            Ok(count)
599        } else {
600            Err(vantage_core::error!(
601                "count query returned an unexpected result shape",
602                result = result
603            ))
604        }
605    }
606}