Skip to main content

uqa_engine/
fdw.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7use super::Engine;
8use super::RelationIdentity;
9use uqa_fdw::arrays::{column_type_is_array, normalize_array_columns};
10
11pub(crate) use uqa_execution::catalog::foreign::StoredForeignTable;
12
13struct MemoryForeignRowStream<'a> {
14    engine: &'a Engine,
15    table_name: RelationIdentity,
16    columns: Option<Vec<String>>,
17    predicates: Vec<uqa_fdw::FDWPredicate>,
18    limit: Option<u64>,
19    index: usize,
20    emitted: u64,
21}
22
23impl Iterator for MemoryForeignRowStream<'_> {
24    type Item = std::result::Result<uqa_fdw::Row, String>;
25
26    fn next(&mut self) -> Option<Self::Item> {
27        if self.limit.is_some_and(|limit| self.emitted >= limit) {
28            return None;
29        }
30        loop {
31            let row = {
32                let tables = self.engine.extensions.foreign_memory_tables.read();
33                let Some(rows) = tables.get(&self.table_name) else {
34                    return Some(Err(format!(
35                        "Foreign table `{}` lost its loaded memory data during the scan",
36                        self.table_name.qualified_name()
37                    )));
38                };
39                let row = rows.get(self.index)?;
40                row.clone()
41            };
42            self.index = match self.index.checked_add(1) {
43                Some(index) => index,
44                None => return Some(Err("memory FDW cursor index overflow".into())),
45            };
46            match uqa_fdw::row_matches_predicates(&row, &self.predicates) {
47                Ok(true) => {}
48                Ok(false) => continue,
49                Err(error) => return Some(Err(error.to_string())),
50            }
51            self.emitted = match self.emitted.checked_add(1) {
52                Some(emitted) => emitted,
53                None => return Some(Err("memory FDW emitted-row count overflow".into())),
54            };
55            return Some(Ok(uqa_fdw::project_row(&row, self.columns.as_deref())));
56        }
57    }
58}
59
60impl Engine {
61    pub fn register_foreign_server(
62        &self,
63        name: String,
64        fdw_type: String,
65        options: Vec<(String, String)>,
66        if_not_exists: bool,
67    ) -> std::result::Result<(), String> {
68        self.with_implicit_string_transaction(move |engine| {
69            engine
70                .foreign_creation_context()
71                .register_foreign_server_inner(name, &fdw_type, options, if_not_exists)
72        })
73    }
74
75    pub fn register_foreign_table(
76        &self,
77        name: String,
78        server_name: String,
79        columns: Vec<uqa_sql::ast::ColumnDef>,
80        options: Vec<(String, String)>,
81        if_not_exists: bool,
82    ) -> std::result::Result<(), String> {
83        self.with_implicit_string_transaction(move |engine| {
84            engine
85                .foreign_creation_context()
86                .register_foreign_table_inner(
87                    &name,
88                    server_name,
89                    columns,
90                    Vec::new(),
91                    options,
92                    if_not_exists,
93                )
94                .map_err(|error| error.to_string())
95        })
96    }
97
98    pub fn drop_foreign_server(&self, name: &str) -> Result<bool, String> {
99        self.with_implicit_definition_transaction(|engine| {
100            engine.foreign_server_removal_context().drop_server(name)
101        })
102        .map_err(|error| error.to_string())
103    }
104
105    pub fn drop_foreign_table(&self, name: &str) -> Result<bool, String> {
106        self.with_implicit_definition_transaction(|engine| {
107            uqa_execution::schema::removal::direct::drop_foreign_table(
108                &engine.relation_removal_context(),
109                name,
110            )
111        })
112        .map_err(|error| error.to_string())
113    }
114
115    /// Read the retained SQL server definition without requiring a source handler.
116    pub fn foreign_server_definition(
117        &self,
118        name: &str,
119    ) -> Result<Option<uqa_sql::catalog::foreign_server::ForeignServerDefinition>, String> {
120        self.with_direct_query_snapshot(
121            true,
122            |engine| {
123                engine
124                    .foreign_lookup_context()
125                    .foreign_server_definition(name)
126            },
127            |error| error.to_string(),
128        )
129    }
130
131    /// Read the complete retained SQL table definition without requiring a source handler.
132    pub fn foreign_table_definition(
133        &self,
134        name: &str,
135    ) -> Result<Option<StoredForeignTable>, String> {
136        self.with_direct_query_snapshot(
137            true,
138            |engine| {
139                engine
140                    .foreign_lookup_context()
141                    .foreign_table_definition(name)
142            },
143            |error| error.to_string(),
144        )
145    }
146
147    pub fn foreign_server(&self, name: &str) -> Result<Option<uqa_fdw::ForeignServer>, String> {
148        self.with_direct_query_snapshot(
149            true,
150            |engine| engine.foreign_lookup_context().foreign_server(name),
151            |error| error.to_string(),
152        )
153    }
154
155    pub fn foreign_table(&self, name: &str) -> Result<Option<uqa_fdw::ForeignTable>, String> {
156        self.with_direct_query_snapshot(
157            true,
158            |engine| engine.foreign_lookup_context().foreign_table(name),
159            |error| error.to_string(),
160        )
161    }
162
163    pub fn list_foreign_servers(&self) -> Result<Vec<String>, String> {
164        self.with_direct_query_snapshot(
165            true,
166            |engine| engine.foreign_lookup_context().list_foreign_servers(),
167            |error| error.to_string(),
168        )
169    }
170
171    pub fn list_foreign_tables(&self) -> Result<Vec<String>, String> {
172        self.with_direct_query_snapshot(
173            true,
174            |engine| engine.foreign_lookup_context().list_foreign_tables(),
175            |error| error.to_string(),
176        )
177    }
178
179    pub fn foreign_table_columns(&self, table: &str) -> Result<Vec<String>, String> {
180        self.with_direct_query_snapshot(
181            true,
182            |engine| engine.foreign_lookup_context().foreign_table_columns(table),
183            |error| error.to_string(),
184        )
185    }
186
187    pub fn load_memory_foreign_table(
188        &self,
189        table_name: impl Into<String>,
190        rows: Vec<uqa_fdw::Row>,
191    ) -> std::result::Result<(), String> {
192        let table_name = table_name.into();
193        let table_name = self
194            .foreign_lookup_context()
195            .resolve_foreign_table_name(&table_name)
196            .map_err(|err| format!("resolve foreign table: {err}"))?
197            .ok_or_else(|| format!("Foreign table `{table_name}` does not exist"))?;
198        let relation = RelationIdentity::from_legacy_name(&table_name)?;
199        let (table, server) = self
200            .foreign_lookup_context()
201            .foreign_table_source(&table_name)?;
202        if server.fdw_type != "memory_fdw" {
203            return Err(format!(
204                "Foreign table `{table_name}` is backed by `{}` not `memory_fdw`",
205                server.fdw_type
206            ));
207        }
208        let array_columns = table
209            .columns
210            .iter()
211            .filter(|column| column_type_is_array(&column.ty))
212            .map(|column| column.name.clone())
213            .collect::<Vec<_>>();
214        let rows = rows
215            .into_iter()
216            .map(|row| normalize_array_columns(row, &array_columns))
217            .collect::<std::result::Result<Vec<_>, _>>()?;
218        self.extensions
219            .foreign_memory_tables
220            .write()
221            .insert(relation, rows);
222        Ok(())
223    }
224
225    pub(crate) fn scan_foreign_table_stream<'a>(
226        &'a self,
227        table_name: &str,
228        columns: Option<&[String]>,
229        predicates: &[uqa_fdw::FDWPredicate],
230        limit: Option<u64>,
231    ) -> std::result::Result<
232        Box<dyn Iterator<Item = std::result::Result<uqa_fdw::Row, String>> + Send + 'a>,
233        String,
234    > {
235        #[cfg(all(
236            not(target_os = "emscripten"),
237            any(feature = "arrow", feature = "duckdb")
238        ))]
239        use uqa_fdw::FDWHandler as _;
240
241        let (table, server) = self
242            .foreign_lookup_context()
243            .foreign_table_source(table_name)?;
244        let array_columns = table
245            .columns
246            .iter()
247            .filter(|column| column_type_is_array(&column.ty))
248            .map(|column| column.name.clone())
249            .collect::<Vec<_>>();
250
251        let rows: Box<dyn Iterator<Item = std::result::Result<uqa_fdw::Row, String>> + Send + 'a> =
252            match server.fdw_type.as_str() {
253                "memory_fdw" => {
254                    let relation = RelationIdentity::from_legacy_name(&table.name)?;
255                    if !self
256                        .extensions
257                        .foreign_memory_tables
258                        .read()
259                        .contains_key(&relation)
260                    {
261                        return Err(format!(
262                            "Foreign table `{}` has no loaded memory data",
263                            table.name
264                        ));
265                    }
266                    Box::new(MemoryForeignRowStream {
267                        engine: self,
268                        table_name: relation,
269                        columns: columns.map(<[String]>::to_vec),
270                        predicates: predicates.to_vec(),
271                        limit,
272                        index: 0,
273                        emitted: 0,
274                    })
275                }
276                #[cfg(all(not(target_os = "emscripten"), feature = "duckdb"))]
277                "duckdb_fdw" => {
278                    let handler = uqa_fdw::DuckDBHandler::new(server);
279                    Box::new(
280                        handler
281                            .scan_stream(&table, columns, predicates, limit)
282                            .map_err(|error| error.to_string())?
283                            .map(|row| row.map_err(|error| error.to_string())),
284                    )
285                }
286                #[cfg(all(not(target_os = "emscripten"), feature = "arrow"))]
287                "arrow_fdw" => {
288                    let handler = uqa_fdw::ArrowIpcHandler::new(server);
289                    Box::new(
290                        handler
291                            .scan_stream(&table, columns, predicates, limit)
292                            .map_err(|error| error.to_string())?
293                            .map(|row| row.map_err(|error| error.to_string())),
294                    )
295                }
296                other => return Err(format!("FDW type `{other}` is not available in this build")),
297            };
298        Ok(Box::new(rows.map(move |row| {
299            row.and_then(|row| normalize_array_columns(row, &array_columns))
300        })))
301    }
302}