Struct ArrowOptions

#[non_exhaustive]
pub struct ArrowOptions { /* private fields */ }

Configuration options for Arrow serialization and deserialization with ClickHouse.

The ArrowOptions struct defines settings that control how Apache Arrow data types are mapped to ClickHouse types during serialization (e.g., inserts), deserialization (e.g., queries), and schema creation (e.g., DDL operations). These options are used by [ArrowClient] and set via [ClientBuilder::with_arrow_options] or directly in ClientOptions.

Fields

• strings_as_strings: If true, maps ClickHouse String to Arrow Utf8; if false, maps to Binary (default).
• use_date32_for_date: If true, maps Arrow Date32 to ClickHouse Date32; if false, maps to Date (default).
• strict_schema: If true, enforces strict type mappings during serialization (inserts) and schema creation, causing errors on ClickHouse invariant violations (e.g., Nullable(LowCardinality(String))); if false, attempts to correct violations (e.g., mapping to LowCardinality(Nullable(String))) (default).
• disable_strict_schema_ddl: If true, prevents automatic strict mode during schema creation (via ArrowOptions::into_strict_ddl); if false, schema creation defaults to strict mode (default).
• nullable_array_default_empty: If true, maps Nullable(Array(...)) to Array(...) with [] for nulls during inserts and schema creation (if disable_strict_schema_ddl = true); if false, errors on Nullable(Array(...)) (default).

Notes

• During schema creation, options are converted to strict mode (via ArrowOptions::into_strict_ddl) unless disable_strict_schema_ddl is true. Strict mode sets strict_schema = true and effectively enforces nullable_array_default_empty = false, ensuring non-nullable arrays.
• When strict_schema is false, violations like Nullable(LowCardinality(String)) are corrected, but arrays are handled per nullable_array_default_empty for inserts, while nullable arrays are ignored during schema creation.
• If strict_schema = true and nullable_array_default_empty = true, non-array violations (e.g., LowCardinality) error, but arrays map to [] for nulls during insert. This is useful in cases where the arrow Schema is used to create the table, but arrays may come from different RecordBatches.
• This struct is #[non_exhaustive], so future fields may be added (e.g., for new ClickHouse types or serialization options). Use ArrowOptions::new or ArrowOptions::default to construct instances.

Examples

use clickhouse_arrow::prelude::*;

let arrow_options = ArrowOptions::new()
    .with_strings_as_strings(true)
    .with_strict_schema(true)
    .with_nullable_array_default_empty(false);
let options = ClientOptions {
    arrow: Some(arrow_options),
    ..ClientOptions::default()
};

Implementations

impl ArrowOptions

pub const fn new() -> Self

Creates a new ArrowOptions instance with default values.

This method is equivalent to ArrowOptions::default, initializing fields for relaxed type mappings. Use this to start configuring Arrow serialization/deserialization options for ClickHouse.

Returns

A new ArrowOptions instance with default settings.

Examples

use clickhouse_arrow::arrow::ArrowOptions;

let arrow_options = ArrowOptions::new();
println!("Nullable array default empty: {}", arrow_options.nullable_array_default_empty); // true

pub const fn strict() -> Self

Creates an ArrowOptions instance with strict type mapping settings.

This method configures options for strict type mappings, where ClickHouse invariant violations (e.g., Nullable(LowCardinality(String)) or Nullable(Array(...))) cause errors during serialization (inserts) and schema creation. It sets strict_schema to true and nullable_array_default_empty to false, leaving other fields as false. Use this for operations where ClickHouse invariants must be strictly enforced.

Returns

An ArrowOptions instance with strict settings.

Examples

use clickhouse_arrow::arrow::ArrowOptions;

let arrow_options = ArrowOptions::strict();
println!("Strict schema: {}", arrow_options.strict_schema); // true

pub fn into_strict_ddl(self) -> Self

Converts the options to strict mode for schema creation, unless disabled.

This method returns a new ArrowOptions with strict settings (equivalent to ArrowOptions::strict) unless disable_strict_schema_ddl is true. If disable_strict_schema_ddl is true, the original options are returned unchanged. This method is called automatically during schema creation to enforce ClickHouse invariants, including non-nullable arrays, unless explicitly disabled.

Returns

A new ArrowOptions instance with strict settings or the original options.

Examples

use clickhouse_arrow::arrow::ArrowOptions;

let options_strict_off = ArrowOptions::new()
    .with_disable_strict_schema_ddl(true)
    .into_strict_ddl();
assert!(!options_strict_off.strict_schema);
assert!(options_strict_off.nullable_array_default_empty);

let options_strict = ArrowOptions::new()
    .with_disable_strict_schema_ddl(false) // Default
    .into_strict_ddl();
assert!(options_strict.strict_schema);
assert!(!options_strict.nullable_array_default_empty);

pub fn with_strings_as_strings(self, enabled: bool) -> Self

Sets whether ClickHouse String types are deserialized as Arrow Utf8.

By default, ClickHouse String types map to Arrow Binary. When this option is enabled (true), they map to Arrow Utf8, which is more suitable for text data. Use this to control serialization/deserialization behavior for string columns.

Parameters

• enabled: If true, maps crate::Type::String to arrow::datatypes::DataType::Utf8; if false, maps to arrow::datatypes::DataType::Binary.

Returns

A new ArrowOptions with the updated setting.

Examples

use clickhouse_arrow::prelude::*;

let arrow_options = ArrowOptions::new()
    .with_strings_as_strings(true);
println!("Strings as strings: {}", arrow_options.strings_as_strings); // true

pub fn with_use_date32_for_date(self, enabled: bool) -> Self

Sets whether Arrow Date32 is mapped to ClickHouse Date or Date32.

By default, Arrow Date32 maps to ClickHouse Date (days since 1970-01-01). When this option is enabled (true), it maps to ClickHouse Date32 (days since 1900-01-01). Use this to control date serialization/deserialization behavior.

Parameters

• enabled: If true, maps Date32 to ClickHouse Date32; if false, maps to Date.

Returns

A new ArrowOptions with the updated setting.

Examples

use clickhouse_arrow::prelude::*;

let arrow_options = ArrowOptions::new()
    .with_use_date32_for_date(true);
println!("Use Date32 for Date: {}", arrow_options.use_date32_for_date); // true

pub fn with_strict_schema(self, enabled: bool) -> Self

Sets whether type mappings are strict during serialization and schema creation.

By default, type mappings are relaxed, allowing ClickHouse invariant violations (e.g., Nullable(LowCardinality(String))) to be corrected automatically (e.g., mapping to LowCardinality(Nullable(String))). When this option is enabled (true), non-array violations cause errors during serialization (inserts) and schema creation. Array violations are controlled by ArrowOptions::with_nullable_array_default_empty. Schema creation defaults to strict mode unless ArrowOptions::with_disable_strict_schema_ddl is enabled.

Parameters

• enabled: If true, enforces strict type mappings for non-array types; if false, allows relaxed corrections.

Returns

A new ArrowOptions with the updated setting.

Examples

use clickhouse_arrow::arrow::ArrowOptions;

let arrow_options = ArrowOptions::new()
    .with_strict_schema(true);
println!("Strict schema: {}", arrow_options.strict_schema); // true

pub fn with_disable_strict_schema_ddl(self, enabled: bool) -> Self

Sets whether strict mode is disabled during schema creation.

By default, schema creation (e.g., DDL operations) uses strict type mappings (via ArrowOptions::into_strict_ddl), enforcing ClickHouse invariants and causing errors on violations, including Nullable(Array(...)). When this option is enabled (true), strict mode is disabled for schema creation, using the user’s strict_schema and nullable_array_default_empty settings.

Parameters

• enabled: If true, disables strict mode for schema creation; if false, enables strict mode.

Returns

A new ArrowOptions with the updated setting.

Examples

use clickhouse_arrow::arrow::ArrowOptions;

let arrow_options = ArrowOptions::new()
    .with_disable_strict_schema_ddl(true);
assert!(arrow_options.disable_strict_schema_ddl);

pub fn with_nullable_array_default_empty(self, enabled: bool) -> Self

Sets whether Nullable(Array(...)) types default to empty arrays during inserts and are coerced to non-nullable during DDL.

By default, Nullable(Array(...)) types are mapped to Array(...) with [] for nulls during serialization (inserts) and schema creation (if disable_strict_schema_ddl = true). When this option is disabled (false), Nullable(Array(...)) causes errors, enforcing non-nullable arrays. Schema creation defaults to non-nullable arrays unless ArrowOptions::with_disable_strict_schema_ddl is enabled.

Parameters

• enabled: If true, maps Nullable(Array(...)) to Array(...) with [] for nulls; if false, errors on Nullable(Array(...)).

Returns

A new ArrowOptions with the updated setting.

Examples

use clickhouse_arrow::arrow::ArrowOptions;

let arrow_options = ArrowOptions::new()
    .with_nullable_array_default_empty(false);
assert!(!arrow_options.nullable_array_default_empty);

pub fn with_setting(self, name: &str, value: bool) -> Self

Sets an Arrow option by name and value.

This method updates a specific option identified by name to the given boolean value. Currently supported names are:

• "strings_as_strings": Maps ClickHouse String to Arrow Utf8.
• "use_date32_for_date": Maps Arrow Date32 to ClickHouse Date32.
• "strict_schema": Enforces strict type mappings for non-array types.
• "disable_strict_schema_ddl": Disables strict mode for schema creation.
• "nullable_array_default_empty": Maps Nullable(Array(...)) to Array(...) with [] for nulls.

If an unrecognized name is provided, a warning is logged, and the options are returned unchanged. Use this for dynamic configuration or when options are specified as key-value pairs.

Parameters

• name: The name of the option to set.
• value: The boolean value to set for the option.

Returns

A new ArrowOptions with the updated setting.

Examples

use clickhouse_arrow::arrow::ArrowOptions;

let arrow_options = ArrowOptions::new()
    .with_setting("strings_as_strings", true)
    .with_setting("nullable_array_default_empty", false);
assert!(arrow_options.strings_as_strings);
assert!(!arrow_options.nullable_array_default_empty);

Trait Implementations

impl Clone for ArrowOptions

fn clone(&self) -> ArrowOptions

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ArrowOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ArrowOptions

fn default() -> Self

Creates an ArrowOptions instance with default values.

The default configuration uses relaxed type mappings suitable for most ClickHouse and Arrow use cases:

• ClickHouse String maps to Arrow Binary.
• Arrow Date32 maps to ClickHouse Date.
• Type mappings are relaxed, correcting ClickHouse invariant violations (e.g., mapping Nullable(LowCardinality(String)) to LowCardinality(Nullable(String))).
• Schema creation defaults to strict mode (via ArrowOptions::into_strict_ddl).
• Nullable(Array(...)) defaults to Array(...) with [] for nulls.

Use this as a starting point and customize with methods like ArrowOptions::with_strings_as_strings.

Returns

An ArrowOptions instance with default settings.

Examples

use clickhouse_arrow::arrow::ArrowOptions;

let arrow_options = ArrowOptions::default();
println!("Nullable array default empty: {}", arrow_options.nullable_array_default_empty); // true

impl<'de> Deserialize<'de> for ArrowOptions

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'a, S, I> From<I> for ArrowOptions

where S: AsRef<str> + 'a, I: Iterator<Item = &'a (S, bool)> + 'a,

fn from(value: I) -> Self

Creates an ArrowOptions instance from an iterator of key-value pairs.

This method constructs an ArrowOptions by applying settings from an iterator of (key, value) pairs, where key is a string (e.g., "strict_schema") and value is a boolean. It uses ArrowOptions::with_setting to apply each setting. Unrecognized keys trigger a warning but do not cause an error.

See currently supported keys by inspecting ArrowOptions::with_setting.

Parameters

• value: An iterator of (key, value) pairs, where key is a string-like type and value is a boolean.

Returns

An ArrowOptions instance with the applied settings.

Examples

use clickhouse_arrow::arrow::ArrowOptions;

let settings = vec![("strings_as_strings", true), ("nullable_array_default_empty", false)];
let arrow_options: ArrowOptions = settings.iter().collect();
assert!(arrow_options.strings_as_strings);
assert!(!arrow_options.nullable_array_default_empty);

impl<'a> FromIterator<(&'a str, bool)> for ArrowOptions

fn from_iter<I: IntoIterator<Item = (&'a str, bool)>>(iter: I) -> Self

Creates an ArrowOptions instance from an iterator of string-boolean pairs.

This method constructs an ArrowOptions by applying settings from an iterator of (key, value) pairs, where key is a string slice (e.g., "strict_schema") and value is a boolean. It uses ArrowOptions::with_setting to apply each setting. Unrecognized keys trigger a warning but do not cause an error.

See currently supported keys by inspecting ArrowOptions::with_setting.

Parameters

• iter: An iterator of (key, value) pairs, where key is a string slice and value is a boolean.

Returns

An ArrowOptions instance with the applied settings.

Examples

use clickhouse_arrow::arrow::ArrowOptions;

let settings = vec![("strings_as_strings", true), ("nullable_array_default_empty", false)];
let arrow_options = ArrowOptions::from_iter(settings);
assert!(arrow_options.strings_as_strings);
assert!(!arrow_options.nullable_array_default_empty);

impl PartialEq for ArrowOptions

fn eq(&self, other: &ArrowOptions) -> bool

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for ArrowOptions

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for ArrowOptions

impl Eq for ArrowOptions

impl StructuralPartialEq for ArrowOptions