Skip to main content

quack_rs/
expression.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! Bound expressions (`DuckDB` 1.5.0+).
7//!
8//! [`Expression`] is an RAII wrapper around `DuckDB`'s `duckdb_expression` handle.
9//! Extension authors obtain one from a scalar function's *bind* callback via
10//! [`ScalarBindInfo::argument`][crate::scalar::ScalarBindInfo::argument], which
11//! lets the bind phase inspect each argument's static type and — when the
12//! argument is a constant — fold it to a concrete [`Value`].
13//!
14//! This is the canonical way to implement scalar functions whose behaviour
15//! depends on a constant argument (for example a format string or a precision)
16//! that should be validated or pre-computed once at bind time rather than on
17//! every row.
18//!
19//! # Example
20//!
21//! ```rust,no_run
22//! use quack_rs::scalar::{RawScalarBindInfo, ScalarBindInfo};
23//!
24//! unsafe extern "C" fn my_bind(info: RawScalarBindInfo) {
25//!     let bind = unsafe { ScalarBindInfo::new(info) };
26//!     if let Some(arg) = unsafe { bind.argument(0) } {
27//!         // Inspect the argument's static return type at bind time.
28//!         let _ty = arg.return_type();
29//!         if arg.is_foldable() {
30//!             // With a `ClientContext`, `arg.fold(&ctx)` pre-computes the constant.
31//!         }
32//!     }
33//! }
34//! ```
35
36use libduckdb_sys::{
37    duckdb_destroy_expression, duckdb_expression, duckdb_expression_fold,
38    duckdb_expression_is_foldable, duckdb_expression_return_type, duckdb_value,
39};
40
41use crate::client_context::ClientContext;
42use crate::error_data::{DuckDbErrorType, ErrorData};
43use crate::types::LogicalType;
44use crate::value::Value;
45
46/// RAII wrapper for a `duckdb_expression`.
47///
48/// Automatically destroyed when dropped.
49pub struct Expression {
50    raw: duckdb_expression,
51}
52
53impl Expression {
54    /// Wraps a raw `duckdb_expression` handle, taking ownership.
55    ///
56    /// # Safety
57    ///
58    /// `raw` must be a valid `duckdb_expression` returned by a `DuckDB` API call
59    /// (e.g. `duckdb_scalar_function_bind_get_argument`). The caller must not
60    /// destroy the handle after this call.
61    #[inline]
62    #[must_use]
63    pub const unsafe fn from_raw(raw: duckdb_expression) -> Self {
64        Self { raw }
65    }
66
67    /// Returns the raw handle without consuming the `Expression`.
68    #[inline]
69    #[must_use]
70    pub const fn as_raw(&self) -> duckdb_expression {
71        self.raw
72    }
73
74    /// Returns `true` if the underlying handle is null.
75    #[inline]
76    #[must_use]
77    pub const fn is_null(&self) -> bool {
78        self.raw.is_null()
79    }
80
81    /// Returns the static return type of this expression, or `None` if the
82    /// handle is null.
83    #[must_use]
84    pub fn return_type(&self) -> Option<LogicalType> {
85        if self.raw.is_null() {
86            return None;
87        }
88        // SAFETY: self.raw is a non-null, valid duckdb_expression. The returned
89        // logical type is owned by the caller and freed by LogicalType on drop.
90        let raw = unsafe { duckdb_expression_return_type(self.raw) };
91        if raw.is_null() {
92            return None;
93        }
94        // SAFETY: raw is a non-null logical type handle owned by the caller.
95        Some(unsafe { LogicalType::from_raw(raw) })
96    }
97
98    /// Returns `true` if this expression is *foldable* — i.e. it is constant and
99    /// can be evaluated to a single [`Value`] via [`fold`][Expression::fold]
100    /// without per-row input.
101    #[must_use]
102    pub fn is_foldable(&self) -> bool {
103        if self.raw.is_null() {
104            return false;
105        }
106        // SAFETY: self.raw is a non-null, valid duckdb_expression.
107        unsafe { duckdb_expression_is_foldable(self.raw) }
108    }
109
110    /// Folds this (constant) expression into a single [`Value`].
111    ///
112    /// Only succeeds when [`is_foldable`][Expression::is_foldable] returns
113    /// `true`.
114    ///
115    /// The returned [`Value`] always has a non-null handle, but may hold SQL
116    /// `NULL` (`fold` of `NULL::INTEGER`); its typed getters return `None` for
117    /// that.
118    ///
119    /// # Errors
120    ///
121    /// Returns the structured [`ErrorData`] if evaluation fails, and an
122    /// [`DuckDbErrorType::InvalidInput`] error when the expression handle is
123    /// null or the expression is not foldable (for example it references a
124    /// column). `duckdb_expression_fold` reports that last case by returning
125    /// *no* error and leaving the output value unset.
126    ///
127    /// For an evaluation failure, `DuckDB` 1.5.5 builds the error from
128    /// `ex.what()` — the exception's JSON form, such as
129    /// `{"exception_type":"Conversion","exception_message":"Could not convert
130    /// string 'abc' to INT64",...}` — and always tags it `INVALID_INPUT`
131    /// (`src/main/capi/expression-c.cpp`). This unpacks it: the returned error
132    /// carries the plain `exception_message` and the
133    /// [`DuckDbErrorType`] named by `exception_type`. Text that does not parse
134    /// as that JSON is returned unchanged, still typed `InvalidInput`.
135    pub fn fold(&self, context: &ClientContext) -> Result<Value, ErrorData> {
136        let mut out_value: duckdb_value = std::ptr::null_mut();
137        // SAFETY: self.raw and context.as_raw() are valid; out_value is a valid
138        // out-pointer that DuckDB writes an owned duckdb_value into.
139        let err_raw =
140            unsafe { duckdb_expression_fold(context.as_raw(), self.raw, &raw mut out_value) };
141        // SAFETY: duckdb_expression_fold returns an owned duckdb_error_data.
142        let err = unsafe { ErrorData::from_raw(err_raw) };
143        if err.has_error() {
144            // SAFETY: out_value may have been left null/invalid; destroy any value.
145            if !out_value.is_null() {
146                // SAFETY: `out_value` is the handle DuckDB just wrote, and taking ownership
147                // here is what frees it.
148                drop(unsafe { Value::from_raw(out_value) });
149            }
150            return Err(unpack_exception_json(err));
151        }
152        if out_value.is_null() {
153            // `duckdb_expression_fold` returns early, with neither an error nor
154            // a value, for a null or non-foldable expression.
155            return Err(ErrorData::new(
156                DuckDbErrorType::InvalidInput,
157                "Expression::fold: the expression is not foldable (it is not constant)",
158            ));
159        }
160        // SAFETY: folding succeeded and out_value is non-null, so it is an
161        // owned duckdb_value.
162        Ok(unsafe { Value::from_raw(out_value) })
163    }
164}
165
166/// Replaces an error whose message is `DuckDB`'s exception JSON with one
167/// carrying the plain message and the named error type. Anything else is
168/// returned unchanged.
169fn unpack_exception_json(err: ErrorData) -> ErrorData {
170    let Some(raw) = err.message() else {
171        return err;
172    };
173    let Some((type_name, message)) = parse_exception_json(&raw) else {
174        return err;
175    };
176    ErrorData::new(error_type_from_name(&type_name), &message)
177}
178
179/// Maps `Exception::ExceptionTypeToString` names (`EXCEPTION_MAP` in
180/// `src/common/exception.cpp`) back to [`DuckDbErrorType`]. An unknown name
181/// maps to [`DuckDbErrorType::Invalid`], as `DuckDB`'s own reverse lookup does.
182fn error_type_from_name(name: &str) -> DuckDbErrorType {
183    use DuckDbErrorType as T;
184    match name {
185        "Out of Range" => T::OutOfRange,
186        "Conversion" => T::Conversion,
187        "Unknown Type" => T::UnknownType,
188        "Decimal" => T::Decimal,
189        "Mismatch Type" => T::MismatchType,
190        "Divide by Zero" => T::DivideByZero,
191        "Object Size" => T::ObjectSize,
192        "Invalid type" => T::InvalidType,
193        "Serialization" => T::Serialization,
194        "TransactionContext" => T::Transaction,
195        "Not implemented" => T::NotImplemented,
196        "Expression" => T::Expression,
197        "Catalog" => T::Catalog,
198        "Parser" => T::Parser,
199        "Binder" => T::Binder,
200        "Planner" => T::Planner,
201        "Scheduler" => T::Scheduler,
202        "Executor" => T::Executor,
203        "Constraint" => T::Constraint,
204        "Index" => T::Index,
205        "Stat" => T::Stat,
206        "Connection" => T::Connection,
207        "Syntax" => T::Syntax,
208        "Settings" => T::Settings,
209        "Optimizer" => T::Optimizer,
210        "NullPointer" => T::NullPointer,
211        "IO" => T::Io,
212        "INTERRUPT" => T::Interrupt,
213        "FATAL" => T::Fatal,
214        "INTERNAL" => T::Internal,
215        "Invalid Input" => T::InvalidInput,
216        "Out of Memory" => T::OutOfMemory,
217        "Permission" => T::Permission,
218        "Parameter Not Resolved" => T::ParameterNotResolved,
219        "Parameter Not Allowed" => T::ParameterNotAllowed,
220        "Dependency" => T::Dependency,
221        "Missing Extension" => T::MissingExtension,
222        "HTTP" => T::Http,
223        "Extension Autoloading" => T::Autoload,
224        "Sequence" => T::Sequence,
225        "Invalid Configuration" => T::InvalidConfiguration,
226        "Data Corruption" => T::DataCorruption,
227        "Resource In Use" => T::ResourceInUse,
228        _ => T::Invalid,
229    }
230}
231
232/// Parses `DuckDB`'s exception JSON — a flat object whose values are all
233/// strings, written by `StringUtil::ExceptionToJSONMap` — and returns its
234/// `exception_type` and `exception_message`.
235///
236/// Returns `None` for anything else (not an object, a non-string value, a
237/// missing key, trailing text), so the caller can fall back to the raw text.
238fn parse_exception_json(raw: &str) -> Option<(String, String)> {
239    let mut chars = raw.trim().chars().peekable();
240    let mut exception_type = None;
241    let mut exception_message = None;
242    let skip_ws = |chars: &mut std::iter::Peekable<std::str::Chars<'_>>| {
243        while chars.peek().is_some_and(char::is_ascii_whitespace) {
244            chars.next();
245        }
246    };
247    if chars.next()? != '{' {
248        return None;
249    }
250    skip_ws(&mut chars);
251    if chars.peek() == Some(&'}') {
252        return None;
253    }
254    loop {
255        skip_ws(&mut chars);
256        let key = parse_json_string(&mut chars)?;
257        skip_ws(&mut chars);
258        if chars.next()? != ':' {
259            return None;
260        }
261        skip_ws(&mut chars);
262        let value = parse_json_string(&mut chars)?;
263        match key.as_str() {
264            "exception_type" => exception_type = Some(value),
265            "exception_message" => exception_message = Some(value),
266            _ => {}
267        }
268        skip_ws(&mut chars);
269        match chars.next()? {
270            ',' => {}
271            '}' => break,
272            _ => return None,
273        }
274    }
275    skip_ws(&mut chars);
276    if chars.next().is_some() {
277        return None;
278    }
279    Some((exception_type?, exception_message?))
280}
281
282/// Parses one JSON string literal, including its quotes, decoding escapes
283/// (with `\u` surrogate pairs).
284fn parse_json_string(chars: &mut std::iter::Peekable<std::str::Chars<'_>>) -> Option<String> {
285    if chars.next()? != '"' {
286        return None;
287    }
288    let mut out = String::new();
289    loop {
290        match chars.next()? {
291            '"' => return Some(out),
292            '\\' => match chars.next()? {
293                '"' => out.push('"'),
294                '\\' => out.push('\\'),
295                '/' => out.push('/'),
296                'b' => out.push('\u{8}'),
297                'f' => out.push('\u{c}'),
298                'n' => out.push('\n'),
299                'r' => out.push('\r'),
300                't' => out.push('\t'),
301                'u' => {
302                    let high = parse_hex4(chars)?;
303                    let code = if (0xD800..0xDC00).contains(&high) {
304                        if chars.next()? != '\\' || chars.next()? != 'u' {
305                            return None;
306                        }
307                        let low = parse_hex4(chars)?;
308                        if !(0xDC00..0xE000).contains(&low) {
309                            return None;
310                        }
311                        0x10000 + ((high - 0xD800) << 10) + (low - 0xDC00)
312                    } else {
313                        high
314                    };
315                    out.push(char::from_u32(code)?);
316                }
317                _ => return None,
318            },
319            c => out.push(c),
320        }
321    }
322}
323
324/// Reads four hex digits of a `\u` escape.
325fn parse_hex4(chars: &mut std::iter::Peekable<std::str::Chars<'_>>) -> Option<u32> {
326    let mut code = 0;
327    for _ in 0..4 {
328        code = code * 16 + chars.next()?.to_digit(16)?;
329    }
330    Some(code)
331}
332
333impl Drop for Expression {
334    fn drop(&mut self) {
335        if !self.raw.is_null() {
336            // SAFETY: self.raw is a valid duckdb_expression that we own.
337            unsafe { duckdb_destroy_expression(&raw mut self.raw) };
338        }
339    }
340}
341
342crate::debug_repr::impl_handle_debug!(Expression.raw);
343
344#[cfg(test)]
345mod tests {
346    use super::*;
347
348    #[test]
349    fn null_expression_is_null() {
350        let expr = unsafe { Expression::from_raw(std::ptr::null_mut()) };
351        assert!(expr.is_null());
352        assert!(!expr.is_foldable());
353        assert!(expr.return_type().is_none());
354    }
355
356    #[test]
357    fn exception_json_is_unpacked_into_type_and_message() {
358        let raw = r#"{"exception_type":"Conversion","exception_message":"Could not convert string 'abc' to INT64","position":"20"}"#;
359        assert_eq!(
360            parse_exception_json(raw),
361            Some((
362                "Conversion".to_owned(),
363                "Could not convert string 'abc' to INT64".to_owned()
364            ))
365        );
366        assert_eq!(
367            error_type_from_name("Out of Range"),
368            DuckDbErrorType::OutOfRange
369        );
370        assert_eq!(
371            error_type_from_name("Conversion"),
372            DuckDbErrorType::Conversion
373        );
374        assert_eq!(
375            error_type_from_name("no such type"),
376            DuckDbErrorType::Invalid
377        );
378    }
379
380    #[test]
381    fn exception_json_escapes_are_decoded() {
382        let raw = r#"{ "exception_message" : "a\"b\\c\n\u00e9\ud83e\udd86\/" , "exception_type" : "IO" }"#;
383        assert_eq!(
384            parse_exception_json(raw),
385            Some(("IO".to_owned(), "a\"b\\c\n\u{e9}\u{1f986}/".to_owned()))
386        );
387    }
388
389    #[test]
390    fn text_that_is_not_exception_json_is_not_parsed() {
391        for raw in [
392            "plain text",
393            "",
394            "{}",
395            r#"{"exception_type":"IO"}"#,
396            r#"{"exception_type":"IO","exception_message":"m","n":1}"#,
397            r#"{"exception_type":"IO","exception_message":"m"} trailing"#,
398            r#"{"exception_type":"IO","exception_message":"unterminated}"#,
399            r#"{"exception_type":"IO","exception_message":"\ud800"}"#,
400        ] {
401            assert_eq!(parse_exception_json(raw), None, "{raw}");
402        }
403    }
404
405    /// Every name `Exception::ExceptionTypeToString` can produce maps to the
406    /// error type with the same code. The pairs are `EXCEPTION_MAP`
407    /// (`src/common/exception.cpp`) joined with the `ExceptionType` codes
408    /// (`exception.hpp`) of `DuckDB` 1.5.5, extracted by script; the C API's
409    /// `duckdb_error_type` uses the same codes. `NETWORK` (25) has no name.
410    #[test]
411    fn every_exception_type_name_maps_to_the_error_type_with_its_code() {
412        for (code, name) in [
413            (0, "Invalid"),
414            (1, "Out of Range"),
415            (2, "Conversion"),
416            (3, "Unknown Type"),
417            (4, "Decimal"),
418            (5, "Mismatch Type"),
419            (6, "Divide by Zero"),
420            (7, "Object Size"),
421            (8, "Invalid type"),
422            (9, "Serialization"),
423            (10, "TransactionContext"),
424            (11, "Not implemented"),
425            (12, "Expression"),
426            (13, "Catalog"),
427            (14, "Parser"),
428            (24, "Binder"),
429            (15, "Planner"),
430            (16, "Scheduler"),
431            (17, "Executor"),
432            (18, "Constraint"),
433            (19, "Index"),
434            (20, "Stat"),
435            (21, "Connection"),
436            (22, "Syntax"),
437            (23, "Settings"),
438            (26, "Optimizer"),
439            (27, "NullPointer"),
440            (28, "IO"),
441            (29, "INTERRUPT"),
442            (30, "FATAL"),
443            (31, "INTERNAL"),
444            (32, "Invalid Input"),
445            (33, "Out of Memory"),
446            (34, "Permission"),
447            (35, "Parameter Not Resolved"),
448            (36, "Parameter Not Allowed"),
449            (37, "Dependency"),
450            (39, "Missing Extension"),
451            (38, "HTTP"),
452            (40, "Extension Autoloading"),
453            (41, "Sequence"),
454            (42, "Invalid Configuration"),
455            (43, "Data Corruption"),
456            (44, "Resource In Use"),
457        ] {
458            let mapped = error_type_from_name(name);
459            assert_eq!(u64::from(mapped.to_raw()), code, "{name}");
460            assert_eq!(mapped, DuckDbErrorType::from_raw(mapped.to_raw()), "{name}");
461        }
462    }
463
464    #[test]
465    fn every_single_character_json_escape_is_decoded() {
466        let raw = r#"{"exception_type":"IO","exception_message":"\"\\\/\b\f\n\r\t"}"#;
467        assert_eq!(
468            parse_exception_json(raw),
469            Some(("IO".to_owned(), "\"\\/\u{8}\u{c}\n\r\t".to_owned()))
470        );
471        assert_eq!(
472            parse_exception_json(r#"{"exception_type":"IO","exception_message":"\q"}"#),
473            None
474        );
475    }
476
477    #[test]
478    fn size_of_expression_is_one_pointer() {
479        assert_eq!(
480            std::mem::size_of::<Expression>(),
481            std::mem::size_of::<usize>()
482        );
483    }
484}