Skip to main content

chtypes/
lib.rs

1//! chtypes — ClickHouse's own type system, per ClickHouse version, from Rust.
2//!
3//! chtypes answers one question, exactly: **if this row were inserted into this
4//! ClickHouse table on this ClickHouse version, what would happen?** It answers
5//! it by running ClickHouse's own C++ machinery, vendored per release and
6//! linked behind the `chs_*` C ABI. Nothing here reimplements a coercion rule,
7//! which is why the answers are exact by construction: this crate is a thin
8//! passthrough, and every public call makes exactly one ABI call.
9//!
10//! The language-neutral contract is `docs/reference/bindings-v1.md` in this
11//! repository; where this crate and that page disagree, the page wins and this
12//! is a bug.
13//!
14//! ```no_run
15//! use chtypes::{Format, Registry, RegistryOptions, RowsOptions, CompileOptions};
16//!
17//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
18//! // Optional, and first: the image zone and the default settings are fixed
19//! // once per process. See `setup`.
20//! chtypes::setup(chtypes::SetupOptions::default())?;
21//!
22//! let registry = Registry::new(RegistryOptions::default())?;
23//! let lib = registry.for_version("26.8")?;
24//! let schema = lib.compile_table(
25//!     "CREATE TABLE t (ts DateTime, seq UInt8) ENGINE = MergeTree ORDER BY ts",
26//!     &CompileOptions::default(),
27//! )?;
28//!
29//! let batch = schema.rows(
30//!     Format::JsonEachRow,
31//!     br#"{"ts":"2026-01-15 10:30:00","seq":256}"#,
32//!     &RowsOptions::default(),
33//! )?;
34//! println!("{}", batch.outcome);
35//! for t in &batch.transformed {
36//!     // seq: 256 -> 0, overflow_wrap, lossy, and ClickHouse returned success.
37//!     println!("row {} {}: {} -> {}", t.row, t.column, t.input, t.stored);
38//! }
39//! # Ok(()) }
40//! ```
41//!
42//! # What this crate will not do
43//!
44//! * **Never map [`Error::Unsupported`] onto a rejection or an acceptance.** A
45//!   decline means "a real server might well have accepted this; this build will
46//!   not answer". Mapping it to a rejection manufactures an over-reject;
47//!   mapping it to an acceptance manufactures an over-accept.
48//! * **Never treat bytes as text.** A column name, a message and a rendered
49//!   value are [`RawText`]: the bytes are authoritative and the UTF-8 view is
50//!   fallible.
51//! * **Never rewrite a setting.** Settings values are strings, and only
52//!   strings; they cross the boundary as the caller wrote them.
53//! * **Never insert the original body when a row carries a generated default.**
54//!   A value whose [`Value::source`] is [`source::DEFAULT_GENERATED`] is stored
55//!   only if the caller inserts the library's own output: ask `rows` for an
56//!   export in the format you will insert ([`RowsOptions::export`]) and insert
57//!   [`BatchResult::payload`].
58//!
59//! # Threads
60//!
61//! Every object is safe to share. [`Registry`] and [`Library`] (shared as
62//! `Arc<Library>`) are `Send + Sync`; [`Schema`], [`Filter`] and [`Block`] are
63//! `Clone + Send + Sync + 'static`, and `&self` methods run concurrently with
64//! no lock. A library is never unloaded: dropping the last `Arc<Library>`
65//! releases only Rust memory.
66//!
67//! # Platform
68//!
69//! Unix only: the loader is `dlopen`. Linux is the shipping target; macOS is a
70//! development floor and **not** an oracle (its `long double` is 53-bit, so
71//! float parses diverge from a real server).
72
73#![deny(missing_docs)]
74#![warn(clippy::undocumented_unsafe_blocks)]
75
76#[cfg(not(unix))]
77compile_error!("chtypes loads artifacts with dlopen and supports unix targets only");
78
79mod abi1;
80mod decode;
81mod error;
82mod library;
83// The fetch layer's own documentation is its module docs; its record types are
84// re-exported below, undocumented field by field.
85#[allow(missing_docs)]
86mod ocifetch;
87mod raw;
88mod registry;
89mod result;
90mod schema;
91mod setup;
92
93pub use abi1::vocab_gen::{
94    DefaultKind, DocFlags, FilterOutcome, Format, Outcome, Verdict, reason, source, status,
95};
96pub use error::{CacheFault, CallError, Error, Refusal, Result};
97pub use library::Library;
98pub use ocifetch::ensure::Resolved;
99pub use raw::RawText;
100pub use registry::{FetchOptions, Registry, RegistryOptions};
101pub use result::{
102    BatchResult, BuildInfo, Capabilities, Column, Computed, DiscoveredColumn, Discovery,
103    EngineCell, ErrorCodeEntry, ErrorCodeTable, FilterResult, FilterRowError, Framing, Header,
104    RowResult, SchemaDescription, Span, Transform, Value,
105};
106pub use schema::{
107    Block, CompileOptions, EvalOptions, Filter, FilterOptions, RowOptions, RowsOptions, Schema,
108};
109pub use setup::{SetupOptions, setup};
110
111#[cfg(test)]
112mod thread_contract {
113    use super::*;
114
115    fn clone_send_sync_static<T: Clone + Send + Sync + 'static>() {}
116    fn send_sync<T: Send + Sync>() {}
117
118    #[test]
119    fn every_object_is_safe_to_share() {
120        send_sync::<Registry>();
121        send_sync::<Library>();
122        send_sync::<std::sync::Arc<Library>>();
123        clone_send_sync_static::<Schema>();
124        clone_send_sync_static::<Filter>();
125        clone_send_sync_static::<Block>();
126        // Results, errors and BuildInfo are plain values.
127        send_sync::<RowResult>();
128        send_sync::<BatchResult>();
129        send_sync::<FilterResult>();
130        send_sync::<Error>();
131        send_sync::<BuildInfo>();
132    }
133}