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}