Expand description
chtypes — ClickHouse’s own type system, per ClickHouse version, from Rust.
chtypes answers one question, exactly: if this row were inserted into this
ClickHouse table on this ClickHouse version, what would happen? It answers
it by running ClickHouse’s own C++ machinery, vendored per release and
linked behind the chs_* C ABI. Nothing here reimplements a coercion rule,
which is why the answers are exact by construction: this crate is a thin
passthrough, and every public call makes exactly one ABI call.
The language-neutral contract is docs/reference/bindings-v1.md in this
repository; where this crate and that page disagree, the page wins and this
is a bug.
use chtypes::{Format, Registry, RegistryOptions, RowsOptions, CompileOptions};
// Optional, and first: the image zone and the default settings are fixed
// once per process. See `setup`.
chtypes::setup(chtypes::SetupOptions::default())?;
let registry = Registry::new(RegistryOptions::default())?;
let lib = registry.for_version("26.8")?;
let schema = lib.compile_table(
"CREATE TABLE t (ts DateTime, seq UInt8) ENGINE = MergeTree ORDER BY ts",
&CompileOptions::default(),
)?;
let batch = schema.rows(
Format::JsonEachRow,
br#"{"ts":"2026-01-15 10:30:00","seq":256}"#,
&RowsOptions::default(),
)?;
println!("{}", batch.outcome);
for t in &batch.transformed {
// seq: 256 -> 0, overflow_wrap, lossy, and ClickHouse returned success.
println!("row {} {}: {} -> {}", t.row, t.column, t.input, t.stored);
}§What this crate will not do
- Never map
Error::Unsupportedonto a rejection or an acceptance. A decline means “a real server might well have accepted this; this build will not answer”. Mapping it to a rejection manufactures an over-reject; mapping it to an acceptance manufactures an over-accept. - Never treat bytes as text. A column name, a message and a rendered
value are
RawText: the bytes are authoritative and the UTF-8 view is fallible. - Never rewrite a setting. Settings values are strings, and only strings; they cross the boundary as the caller wrote them.
- Never insert the original body when a row carries a generated default.
A value whose
Value::sourceissource::DEFAULT_GENERATEDis stored only if the caller inserts the library’s own output: askrowsfor an export in the format you will insert (RowsOptions::export) and insertBatchResult::payload.
§Threads
Every object is safe to share. Registry and Library (shared as
Arc<Library>) are Send + Sync; Schema, Filter and Block are
Clone + Send + Sync + 'static, and &self methods run concurrently with
no lock. A library is never unloaded: dropping the last Arc<Library>
releases only Rust memory.
§Platform
Unix only: the loader is dlopen. Linux is the shipping target; macOS is a
development floor and not an oracle (its long double is 53-bit, so
float parses diverge from a real server).
Modules§
- reason
- The
transform_reasonvocabulary: the reason spellings a transformation carries, and thelossyfact the description gives each. - source
- The
value_srcvocabulary: where a column’s value came from, and whether the description says it is stored. - status
- The call statuses, as the
chs_statusintegers (D3, frozen). A call error carries the raw status; compare it with these.
Structs§
- Batch
Result - A batch document and its export buffer, from
chs_preview_batch. - Block
- A body parsed once, to be evaluated by many filters.
Cloneshares one handle. - Build
Info - What a library is, from
chs_build_info. - Cache
Fault - What a
Error::CacheUnusablenames: a cache directory or entry the fetch layer could not read or write, or one strict mode refuses (docs/guides/fetch-v1.md§1, the cache faults). - Call
Error - The five fields of one
chs_error, verbatim, and nothing synthesized. - Capabilities
- What a build supports, from
build_info’scapabilities. Every list is ASCII text. - Column
- One column of a compiled schema.
- Compile
Options - What a compile takes: the profile settings, and the per-call zone.
- Computed
- One computed (MATERIALIZED) value.
- Discovered
Column - One column read from a server’s
system.columnsrow. - Discovery
- The columns of a table, from
chs_discover_columns. - DocFlags
- Which groups a
rowsdocument carries: values (cols), transformations and defaults. Combine with|. - Engine
Cell - One cell of a stored row after the engine’s insert-time merge.
- Error
Code Entry - One entry of the error-code table.
- Error
Code Table - This build’s error-code table: every code of the vendored table, read from the library’s own document. An unknown code or name is absent, never synthesized; names match exactly.
- Eval
Options - What
Filter::rowstakes: the body’s PARSE settings, never the WHERE’s. - Fetch
Options - What the fetch layer is configured with, under its own names
(
docs/guides/fetch-v1.md). Every field defaults to the fetch layer’s own default (the environment, then the built-in value); the test hooks of the fetch layer’s own options are not reachable from here. - Filter
- A compiled boolean expression over a schema’s columns.
Cloneshares one handle. - Filter
Options - What
compile_filtertakes. - Filter
Result - A filter evaluation, from
chs_filter_eval_bodyandchs_filter_eval_block. - Filter
RowError - One row’s filter error.
- Framing
- What the reader decided about the body’s framing.
Noneis unknown (the document wrote JSONnull), never false and never empty. - Header
- What a batch’s header line said, when the reader exposes it.
- Library
- One loaded library image.
- RawText
- ClickHouse’s own rendering of a value, as bytes.
- Refusal
- One loader refusal: the
sdk.jsonreason WORD, EXACTLY (glibc_floor,no_glibc,predicate_malformed,dlopen,not_v1,abi_version,build_info_malformed,fingerprint,build_info_mismatch:<field>ormissing_symbol:<name>— never a sentence built around one), the library path, and — where applicable — what was wanted, what was found, and any free-form detail.reasonis what a conformance case compares againstscripts/abi-v1/emit/_stubshared.py’s variant plan verbatim; it is never decorated, so that comparison can be a plain string equality. - Registry
- A request for a version, to a loaded library.
Send + Sync. - Registry
Options - What a
Registryis constructed with. - Resolved
- The result of a successful [
ensure], [resolve_installed] or one entry of [list_installed] (plan §1.3). - RowOptions
- What
rowandparse_blocktake. - RowResult
- A row document, from
chs_preview_row, and each entry of a batch’srows. - Rows
Options - What
rowstakes. - Schema
- A compiled table. Immutable;
Cloneshares one handle. - Schema
Description - A schema’s columns, from
chs_schema_describe. - Setup
Options - The image zone and the default settings, chosen once per process.
- Span
- A byte range of the input (or of an export):
offandlen. - Transform
- One transformation: a value the library stored differently from the input.
- Value
- One column’s entry of a row document (
cols).
Enums§
- Default
Kind - What a column’s DEFAULT clause is. The empty wire value is
None. - Error
- Every failure this crate returns.
- Filter
Outcome - A filter evaluation’s outcome. An unknown value reads as the description’s fallback,
unsupported. - Format
- The input (and export) encoding of a body, as the
chs_formatinteger. The numbers are part of the ABI (frozen) and are never renumbered. Each carriesch_name, ClickHouse’s own name for the format, which is how a build’scapabilitieslists it. - Outcome
- A row’s or a batch’s outcome, as the library’s document states it (already final: the library applies every promotion).
An unknown value reads as the description’s fallback,
unsupported. - Verdict
- One row’s filter verdict.
answeredsays which are answers;ErrorandDeclineare never answers, and a caller enforcing visibility fails closed on both. An unknown value reads as the description’s fallback,d.
Functions§
- setup
- Record the image zone and the default settings, once per process. See the module documentation for the rules.