Skip to main content

chdb_rust/
arrow_options.rs

1//! Options for chDB's Arrow paths: the insert-side [`InsertOptions`] (tuning
2//! knobs for `INSERT … SELECT` and direct FFI insert) and the read-side
3//! [`ArrowOptions`] (type-mapping knobs for Arrow export).
4
5/// Tuning knobs appended as `SETTINGS` on the insert `INSERT … SELECT` query,
6/// or passed to direct FFI insert APIs.
7#[derive(Debug, Clone, Default, PartialEq, Eq)]
8pub struct InsertOptions {
9    /// `max_threads` insert setting (default: 4).
10    pub max_threads: Option<u32>,
11    /// `max_insert_block_size` insert setting.
12    pub max_insert_block_size: Option<u64>,
13    /// `min_insert_block_size_rows` insert setting.
14    pub min_insert_block_size_rows: Option<u64>,
15}
16
17impl InsertOptions {
18    /// Sensible defaults for bulk Arrow ingest.
19    pub fn default_bulk() -> Self {
20        Self {
21            max_threads: Some(4),
22            max_insert_block_size: None,
23            min_insert_block_size_rows: None,
24        }
25    }
26
27    pub(crate) fn settings_clause(&self) -> Option<String> {
28        let mut parts = Vec::new();
29        if let Some(v) = self.max_threads {
30            parts.push(format!("max_threads = {v}"));
31        }
32        if let Some(v) = self.max_insert_block_size {
33            parts.push(format!("max_insert_block_size = {v}"));
34        }
35        if let Some(v) = self.min_insert_block_size_rows {
36            parts.push(format!("min_insert_block_size_rows = {v}"));
37        }
38        if parts.is_empty() {
39            None
40        } else {
41            Some(parts.join(", "))
42        }
43    }
44}
45
46/// How the engine maps ClickHouse types to Arrow types on export.
47///
48/// Distinct from [`InsertOptions`], which tunes the *insert* path — this is the
49/// read side, and it wraps a different C struct (`chdb_arrow_options`).
50///
51/// [`Default`] reproduces the engine's own defaults, so
52/// `ArrowOptions::default()` behaves exactly like passing no options at all.
53#[derive(Debug, Clone, Copy, PartialEq, Eq)]
54pub struct ArrowOptions {
55    /// Emit types with no faithful Arrow mapping — JSON/Object, Dynamic,
56    /// AggregateFunction — as `Binary` instead of failing. Default `false`,
57    /// meaning the engine throws `UNKNOWN_TYPE` for such columns; `true`
58    /// degrades them to `Binary`.
59    pub unsupported_as_binary: bool,
60    /// Emit `LowCardinality(T)` as an Arrow dictionary array instead of
61    /// materializing it to `T`. Default `false`.
62    ///
63    /// The consumer must be able to handle dictionaries whose values are stable
64    /// across batches.
65    pub low_cardinality_as_dictionary: bool,
66    /// Emit `String` as Arrow `Utf8`. Default `true`; `false` emits `Binary`.
67    pub string_as_string: bool,
68}
69
70impl Default for ArrowOptions {
71    fn default() -> Self {
72        Self {
73            unsupported_as_binary: false,
74            low_cardinality_as_dictionary: false,
75            string_as_string: true,
76        }
77    }
78}
79
80impl ArrowOptions {
81    pub(crate) fn to_c(self) -> crate::bindings::chdb_arrow_options {
82        crate::bindings::chdb_arrow_options {
83            unsupported_as_binary: i32::from(self.unsupported_as_binary),
84            low_cardinality_as_dictionary: i32::from(self.low_cardinality_as_dictionary),
85            string_as_string: i32::from(self.string_as_string),
86        }
87    }
88}
89
90#[cfg(test)]
91mod tests {
92    use super::*;
93
94    #[test]
95    fn insert_options_settings_clause() {
96        let opts = InsertOptions {
97            max_threads: Some(4),
98            max_insert_block_size: Some(1_048_576),
99            min_insert_block_size_rows: None,
100        };
101        assert_eq!(
102            opts.settings_clause().as_deref(),
103            Some("max_threads = 4, max_insert_block_size = 1048576")
104        );
105        assert!(InsertOptions::default().settings_clause().is_none());
106    }
107}