Skip to main content

uqa_execution/query/table_functions/
values.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Lazy generate-series, regex, string, and JSON value streams.
8
9use super::TableFunctionRows;
10use uqa_core::Value;
11use uqa_sql::assignment::conversion::{json_table_arg, json_table_value_to_text};
12use uqa_sql::{semantics::table_function_empty_schema, SQLError};
13
14pub fn unnest_row_stream(
15    evaluated: Vec<Value>,
16    output_name: &str,
17    alias: Option<&str>,
18    column_aliases: &[String],
19) -> Result<TableFunctionRows, SQLError> {
20    if evaluated.is_empty() || column_aliases.len() > evaluated.len() {
21        return Err(SQLError::BadArity {
22            name: "unnest".into(),
23            expected: "one output alias per array argument".into(),
24            actual: evaluated.len(),
25        });
26    }
27    let arrays = evaluated
28        .into_iter()
29        .map(|value| match value {
30            Value::Array(array) => {
31                fn flatten(values: &[Value], output: &mut Vec<Value>) {
32                    for value in values {
33                        if let Value::List(nested) = value {
34                            flatten(nested, output);
35                        } else {
36                            output.push(value.clone());
37                        }
38                    }
39                }
40
41                let mut values = Vec::new();
42                flatten(array.elements(), &mut values);
43                Ok(values)
44            }
45            Value::LegacyVector(vector) => Ok(vector.into_array().into_elements()),
46            Value::List(items) => Ok(items),
47            Value::Null => Ok(Vec::new()),
48            _ => Err(SQLError::UnknownFunction(
49                "unnest requires array arguments".into(),
50            )),
51        })
52        .collect::<Result<Vec<_>, _>>()?;
53    let columns = table_function_empty_schema(
54        "unnest",
55        output_name,
56        alias,
57        column_aliases,
58        arrays.len(),
59        false,
60    );
61    let row_count = arrays.iter().map(Vec::len).max().unwrap_or(0);
62    Ok(TableFunctionRows::new(
63        columns,
64        Box::new((0..row_count).map(move |row_position| {
65            Ok(crate::PhysicalRow::from_values(
66                arrays
67                    .iter()
68                    .map(|array| array.get(row_position).cloned().unwrap_or(Value::Null))
69                    .collect(),
70            ))
71        })),
72    ))
73}
74
75pub fn generate_series_values(
76    evaluated: Vec<Value>,
77) -> Result<Box<dyn Iterator<Item = Value> + Send>, SQLError> {
78    if !(2..=3).contains(&evaluated.len()) {
79        return Err(SQLError::TypeMismatch(
80            "generate_series requires 2-3 args".into(),
81        ));
82    }
83    if evaluated.iter().any(|value| matches!(value, Value::Null)) {
84        return Ok(Box::new(std::iter::empty()));
85    }
86    let start = generate_series_integer(&evaluated[0], "start")?;
87    let end = generate_series_integer(&evaluated[1], "stop")?;
88    let increment = evaluated
89        .get(2)
90        .map_or(Ok(1), |value| generate_series_integer(value, "step"))?;
91    if increment == 0 {
92        return Err(SQLError::TypeMismatch(
93            "generate_series step cannot be 0".into(),
94        ));
95    }
96    let mut current = Some(start);
97    Ok(Box::new(std::iter::from_fn(move || {
98        let value = current?;
99        if (increment > 0 && value > end) || (increment < 0 && value < end) {
100            current = None;
101            return None;
102        }
103        current = value.checked_add(increment);
104        Some(Value::Int(value))
105    })))
106}
107
108pub fn generate_series_integer(value: &Value, label: &str) -> Result<i64, SQLError> {
109    match value {
110        Value::Int(value) => Ok(*value),
111        Value::Float(value)
112            if value.is_finite()
113                && value.fract() == 0.0
114                && *value >= i64::MIN as f64
115                && *value < -(i64::MIN as f64) =>
116        {
117            Ok(*value as i64)
118        }
119        _ => Err(SQLError::TypeMismatch(format!(
120            "generate_series {label} must be an integer"
121        ))),
122    }
123}
124
125pub struct RegexSplitValues {
126    regex: regex::Regex,
127    source: String,
128    piece_start: usize,
129    search_start: usize,
130    tail_pending: bool,
131    done: bool,
132}
133
134impl Iterator for RegexSplitValues {
135    type Item = Value;
136
137    fn next(&mut self) -> Option<Self::Item> {
138        if self.done {
139            return None;
140        }
141        if self.tail_pending {
142            self.done = true;
143            return Some(Value::Str(self.source[self.piece_start..].to_string()));
144        }
145        let Some(found) = self.regex.find_at(&self.source, self.search_start) else {
146            self.done = true;
147            return Some(Value::Str(self.source[self.piece_start..].to_string()));
148        };
149        let piece = self.source[self.piece_start..found.start()].to_string();
150        self.piece_start = found.end();
151        if found.start() == found.end() {
152            if found.end() == self.source.len() {
153                self.tail_pending = true;
154            } else {
155                let advance = self.source[found.end()..]
156                    .chars()
157                    .next()
158                    .map_or(1, char::len_utf8);
159                self.search_start = found.end().saturating_add(advance);
160            }
161        } else {
162            self.search_start = found.end();
163        }
164        Some(Value::Str(piece))
165    }
166}
167
168pub fn regexp_split_values(
169    evaluated: Vec<Value>,
170) -> Result<Box<dyn Iterator<Item = Value> + Send>, SQLError> {
171    if evaluated.len() != 2 {
172        return Err(SQLError::TypeMismatch(
173            "regexp_split_to_table requires 2 args".into(),
174        ));
175    }
176    let source = match &evaluated[0] {
177        Value::Str(value) => value.clone(),
178        _ => return Err(SQLError::TypeMismatch("regexp_split_to_table arg 1".into())),
179    };
180    let pattern = match &evaluated[1] {
181        Value::Str(value) => value,
182        _ => return Err(SQLError::TypeMismatch("regexp_split_to_table arg 2".into())),
183    };
184    let regex = regex::Regex::new(pattern)
185        .map_err(|error| SQLError::TypeMismatch(format!("invalid regex: {error}")))?;
186    Ok(Box::new(RegexSplitValues {
187        regex,
188        source,
189        piece_start: 0,
190        search_start: 0,
191        tail_pending: false,
192        done: false,
193    }))
194}
195
196pub fn string_to_table_values(
197    evaluated: Vec<Value>,
198) -> Result<Box<dyn Iterator<Item = Value> + Send>, SQLError> {
199    if evaluated.len() != 2 {
200        return Err(SQLError::TypeMismatch(
201            "string_to_table requires 2 args".into(),
202        ));
203    }
204    let source = match &evaluated[0] {
205        Value::Str(value) => value.clone(),
206        _ => return Err(SQLError::TypeMismatch("string_to_table arg 1".into())),
207    };
208    let delimiter = match &evaluated[1] {
209        Value::Str(value) => value.clone(),
210        _ => return Err(SQLError::TypeMismatch("string_to_table arg 2".into())),
211    };
212    Ok(Box::new(LiteralSplitValues {
213        source,
214        delimiter,
215        cursor: 0,
216        done: false,
217    }))
218}
219
220pub struct LiteralSplitValues {
221    source: String,
222    delimiter: String,
223    cursor: usize,
224    done: bool,
225}
226
227impl Iterator for LiteralSplitValues {
228    type Item = Value;
229
230    fn next(&mut self) -> Option<Self::Item> {
231        if self.done {
232            return None;
233        }
234        if self.delimiter.is_empty() {
235            let value = self.source[self.cursor..].chars().next()?;
236            self.cursor += value.len_utf8();
237            if self.cursor == self.source.len() {
238                self.done = true;
239            }
240            return Some(Value::Str(value.to_string()));
241        }
242        if let Some(relative) = self.source[self.cursor..].find(&self.delimiter) {
243            let delimiter_start = self.cursor + relative;
244            let piece = self.source[self.cursor..delimiter_start].to_string();
245            self.cursor = delimiter_start + self.delimiter.len();
246            return Some(Value::Str(piece));
247        }
248        self.done = true;
249        Some(Value::Str(self.source[self.cursor..].to_string()))
250    }
251}
252
253pub fn json_array_values(
254    name: &str,
255    evaluated: Vec<Value>,
256) -> Result<Box<dyn Iterator<Item = Value> + Send>, SQLError> {
257    if evaluated.len() != 1 {
258        return Err(SQLError::TypeMismatch(format!("{name} takes 1 arg")));
259    }
260    let parsed = json_table_arg(&evaluated[0], name)?;
261    let serde_json::Value::Array(items) = parsed else {
262        return Err(SQLError::TypeMismatch(format!(
263            "{name}: argument is not an array"
264        )));
265    };
266    Ok(Box::new(
267        items
268            .into_iter()
269            .map(|value| json_table_value_to_text(&value)),
270    ))
271}
272
273pub fn json_object_key_values(
274    name: &str,
275    evaluated: Vec<Value>,
276) -> Result<Box<dyn Iterator<Item = Value> + Send>, SQLError> {
277    if evaluated.len() != 1 {
278        return Err(SQLError::TypeMismatch(format!("{name} takes 1 arg")));
279    }
280    let parsed = json_table_arg(&evaluated[0], name)?;
281    let serde_json::Value::Object(object) = parsed else {
282        return Err(SQLError::TypeMismatch(format!(
283            "{name}: argument is not an object"
284        )));
285    };
286    Ok(Box::new(object.into_iter().map(|(key, _)| Value::Str(key))))
287}
288
289pub fn json_each_row_stream(
290    name: &str,
291    evaluated: Vec<Value>,
292    _alias: Option<&str>,
293    column_aliases: &[String],
294) -> Result<TableFunctionRows, SQLError> {
295    if evaluated.len() != 1 {
296        return Err(SQLError::TypeMismatch(format!("{name} takes 1 arg")));
297    }
298    let parsed = json_table_arg(&evaluated[0], name)?;
299    let serde_json::Value::Object(object) = parsed else {
300        return Err(SQLError::TypeMismatch(format!(
301            "{name}: argument is not an object"
302        )));
303    };
304    let key_column = column_aliases
305        .first()
306        .cloned()
307        .unwrap_or_else(|| "key".into());
308    let value_column = column_aliases
309        .get(1)
310        .cloned()
311        .unwrap_or_else(|| "value".into());
312    Ok(TableFunctionRows::new(
313        vec![key_column, value_column],
314        Box::new(object.into_iter().map(move |(key, value)| {
315            Ok(crate::PhysicalRow::from_values(vec![
316                Value::Str(key),
317                json_table_value_to_text(&value),
318            ]))
319        })),
320    ))
321}