faucet_sink_clickhouse/lib.rs
1#![cfg_attr(docsrs, feature(doc_cfg))]
2
3//! # faucet-sink-clickhouse
4//!
5//! ClickHouse sink for the
6//! [`faucet-stream`](https://crates.io/crates/faucet-stream) ecosystem, built on
7//! the ClickHouse [HTTP interface](https://clickhouse.com/docs/en/interfaces/http)
8//! via [`reqwest`](https://crates.io/crates/reqwest).
9//!
10//! Writes each page as a batched `INSERT … FORMAT JSONEachRow` request (the
11//! statement travels in the `query` URL parameter, the newline-delimited JSON
12//! rows in the request body). Optionally enables ClickHouse
13//! [asynchronous inserts](https://clickhouse.com/docs/en/optimize/asynchronous-inserts)
14//! (`async_insert`) for high-throughput small-batch ingestion.
15//!
16//! Upsert semantics in ClickHouse are **engine-dependent** (e.g.
17//! `ReplacingMergeTree` collapses duplicate keys at merge time). The sink is
18//! therefore **append-only** ([`WriteMode::Append`](faucet_core::WriteMode)) and
19//! never emulates upsert — model deduplication in the table's engine instead.
20//!
21//! ```no_run
22//! # use faucet_sink_clickhouse::{ClickHouseSink, ClickHouseSinkConfig};
23//! # fn run() -> Result<(), faucet_core::FaucetError> {
24//! let cfg = ClickHouseSinkConfig::new("http://localhost:8123", "events");
25//! let sink = ClickHouseSink::new(cfg)?;
26//! # let _ = sink;
27//! # Ok(())
28//! # }
29//! ```
30
31mod config;
32mod descriptor;
33mod sink;
34#[cfg(feature = "staging")]
35mod staged;
36#[cfg(feature = "staging")]
37mod staged_exec;
38
39pub use config::ClickHouseSinkConfig;
40pub use sink::ClickHouseSink;
41
42// Re-export the shared connection type so users configure the sink without
43// depending on `faucet-common-clickhouse` directly.
44pub use descriptor::DESCRIPTOR;
45pub use faucet_common_clickhouse::ClickHouseConnection;