Skip to main content

Crate chtypes

Crate chtypes 

Source
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::Unsupported onto 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::source is source::DEFAULT_GENERATED is stored only if the caller inserts the library’s own output: ask rows for an export in the format you will insert (RowsOptions::export) and insert BatchResult::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_reason vocabulary: the reason spellings a transformation carries, and the lossy fact the description gives each.
source
The value_src vocabulary: where a column’s value came from, and whether the description says it is stored.
status
The call statuses, as the chs_status integers (D3, frozen). A call error carries the raw status; compare it with these.

Structs§

BatchResult
A batch document and its export buffer, from chs_preview_batch.
Block
A body parsed once, to be evaluated by many filters. Clone shares one handle.
BuildInfo
What a library is, from chs_build_info.
CacheFault
What a Error::CacheUnusable names: 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).
CallError
The five fields of one chs_error, verbatim, and nothing synthesized.
Capabilities
What a build supports, from build_info’s capabilities. Every list is ASCII text.
Column
One column of a compiled schema.
CompileOptions
What a compile takes: the profile settings, and the per-call zone.
Computed
One computed (MATERIALIZED) value.
DiscoveredColumn
One column read from a server’s system.columns row.
Discovery
The columns of a table, from chs_discover_columns.
DocFlags
Which groups a rows document carries: values (cols), transformations and defaults. Combine with |.
EngineCell
One cell of a stored row after the engine’s insert-time merge.
ErrorCodeEntry
One entry of the error-code table.
ErrorCodeTable
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.
EvalOptions
What Filter::rows takes: the body’s PARSE settings, never the WHERE’s.
FetchOptions
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. Clone shares one handle.
FilterOptions
What compile_filter takes.
FilterResult
A filter evaluation, from chs_filter_eval_body and chs_filter_eval_block.
FilterRowError
One row’s filter error.
Framing
What the reader decided about the body’s framing. None is unknown (the document wrote JSON null), 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.json reason WORD, EXACTLY (glibc_floor, no_glibc, predicate_malformed, dlopen, not_v1, abi_version, build_info_malformed, fingerprint, build_info_mismatch:<field> or missing_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. reason is what a conformance case compares against scripts/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.
RegistryOptions
What a Registry is constructed with.
Resolved
The result of a successful [ensure], [resolve_installed] or one entry of [list_installed] (plan §1.3).
RowOptions
What row and parse_block take.
RowResult
A row document, from chs_preview_row, and each entry of a batch’s rows.
RowsOptions
What rows takes.
Schema
A compiled table. Immutable; Clone shares one handle.
SchemaDescription
A schema’s columns, from chs_schema_describe.
SetupOptions
The image zone and the default settings, chosen once per process.
Span
A byte range of the input (or of an export): off and len.
Transform
One transformation: a value the library stored differently from the input.
Value
One column’s entry of a row document (cols).

Enums§

DefaultKind
What a column’s DEFAULT clause is. The empty wire value is None.
Error
Every failure this crate returns.
FilterOutcome
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_format integer. The numbers are part of the ABI (frozen) and are never renumbered. Each carries ch_name, ClickHouse’s own name for the format, which is how a build’s capabilities lists 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. answered says which are answers; Error and Decline are 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.

Type Aliases§

Result
A Result whose error is this crate’s Error.