vantage_table/source.rs
1//! Source representation for tables whose FROM clause may be a sub-`SELECT`.
2//!
3//! A backend's [`TableSource::Source`](crate::traits::table_source::TableSource::Source)
4//! is either a plain `String` (most backends) or [`SelectSource<S>`] — the
5//! shared enum used by every backend whose `Select` can express
6//! `FROM (subquery)` (SQLite, PostgreSQL, MySQL, SurrealDB).
7
8use vantage_expressions::{Expressive, expr_any, traits::selectable::Selectable};
9
10use crate::traits::table_source_spec::TableSourceSpec;
11
12/// The source of a table: a named table, or an arbitrary query used as a
13/// derived (sub-`SELECT`) source.
14///
15/// `S` is the backend's `Select` type. The same enum serves all four
16/// subquery-capable backends; the only per-backend code is the one-line
17/// `type Source = SelectSource<Self::Select>;` on their `TableSource` impl.
18#[derive(Clone, Debug)]
19pub enum SelectSource<S> {
20 /// A physical table/collection name.
21 Name(String),
22 /// A physical table read under another name, rendered
23 /// `FROM <name> AS <alias>`. A subquery over the outer query's own table
24 /// uses it to tell its rows from the outer ones.
25 Aliased { name: String, alias: String },
26 /// A query used as the FROM source, rendered `FROM (<select>) AS <alias>`.
27 Query { select: Box<S>, alias: String },
28}
29
30impl<S> SelectSource<S> {
31 /// Build a query source from a select and the alias to expose it under.
32 pub fn query(select: S, alias: impl Into<String>) -> Self {
33 SelectSource::Query {
34 select: Box::new(select),
35 alias: alias.into(),
36 }
37 }
38}
39
40impl<S: Clone + Send + Sync + 'static> TableSourceSpec for SelectSource<S> {
41 fn name(&self) -> &str {
42 match self {
43 SelectSource::Name(name) => name.as_str(),
44 SelectSource::Aliased { alias, .. } | SelectSource::Query { alias, .. } => {
45 alias.as_str()
46 }
47 }
48 }
49
50 fn from_name(name: String) -> Self {
51 SelectSource::Name(name)
52 }
53
54 fn aliased(&self, alias: &str) -> Option<Self> {
55 let alias = alias.to_string();
56 Some(match self {
57 SelectSource::Name(name) | SelectSource::Aliased { name, .. } => {
58 SelectSource::Aliased {
59 name: name.clone(),
60 alias,
61 }
62 }
63 SelectSource::Query { select, .. } => SelectSource::Query {
64 select: select.clone(),
65 alias,
66 },
67 })
68 }
69}
70
71impl<S> From<&str> for SelectSource<S> {
72 fn from(value: &str) -> Self {
73 SelectSource::Name(value.to_string())
74 }
75}
76
77impl<S> From<String> for SelectSource<S> {
78 fn from(value: String) -> Self {
79 SelectSource::Name(value)
80 }
81}
82
83/// Applies a source to a freshly-created `Select`.
84///
85/// `Table::select_empty` is generic over *every* `SelectableDataSource`,
86/// including backends whose `Source` is `String` and whose `Select` is not
87/// `Expressive`. So the source can't be matched against `SelectSource`
88/// directly there — this trait dispatches on the concrete source type, keeping
89/// the `Expressive` requirement confined to the query-capable backends.
90pub trait SelectSeed<S, V, C> {
91 /// Add this source to `select` as its FROM clause.
92 fn seed(&self, select: &mut S)
93 where
94 S: Selectable<V, C>,
95 V: From<String>;
96}
97
98impl<S, V, C> SelectSeed<S, V, C> for String {
99 fn seed(&self, select: &mut S)
100 where
101 S: Selectable<V, C>,
102 V: From<String>,
103 {
104 select.add_source(self.as_str(), None);
105 }
106}
107
108impl<S, V, C> SelectSeed<S, V, C> for SelectSource<S>
109where
110 S: Expressive<V> + Clone,
111 V: Clone,
112{
113 fn seed(&self, select: &mut S)
114 where
115 S: Selectable<V, C>,
116 V: From<String>,
117 {
118 match self {
119 SelectSource::Name(name) => select.add_source(name.as_str(), None),
120 SelectSource::Aliased { name, alias } => {
121 select.add_source(name.as_str(), Some(alias.clone()))
122 }
123 SelectSource::Query {
124 select: query,
125 alias,
126 } => {
127 // Parenthesize the subquery ourselves: `expr()` renders a bare
128 // statement, and the SQL dialects' `add_source` does not wrap a
129 // nested source (only SurrealDB does). One wrap here is correct
130 // for every backend.
131 let subquery = expr_any!("({})", (query.expr()));
132 select.add_source(subquery, Some(alias.clone()));
133 }
134 }
135 }
136}