diesel_clickhouse/
lib.rs

1//! Diesel query-builder extensions for ClickHouse.
2//!
3//! This crate follows the same shape as small Diesel extension crates such as
4//! `diesel-paradedb`: it adds typed AST nodes for SQL that Diesel does not know
5//! about natively.  The [`ClickHouse`] backend is a lightweight SQL-rendering
6//! backend, so regular Diesel expressions can be rendered with ClickHouse-style
7//! identifiers and placeholders while ClickHouse-only functions, operators and
8//! trailing clauses compose with the usual `select` / `filter` / `order` calls.
9//!
10//! ## Quick start
11//!
12//! ```ignore
13//! use diesel::prelude::*;
14//! use diesel_clickhouse::{
15//!     count_if, format, limit_by_col, quantile, to_start_of_hour, ClickHouse,
16//!     ClickHouseQueryDsl, Format,
17//! };
18//!
19//! let query = events::table
20//!     .select((
21//!         to_start_of_hour(events::created_at),
22//!         count_if(events::success.eq(true)),
23//!         quantile(0.95, events::latency_ms),
24//!     ))
25//!     .filter(events::tenant_id.eq("acme"))
26//!     .group_by(to_start_of_hour(events::created_at))
27//!     .order(to_start_of_hour(events::created_at).desc())
28//!     .limit_by_col(10, "tenant_id")
29//!     .format(Format::JsonEachRow);
30//!
31//! let sql = diesel_clickhouse::to_sql(&query)?;
32//! # Ok::<(), diesel::result::Error>(())
33//! ```
34//!
35//! ## Scope
36//!
37//! This crate focuses on **building ClickHouse SQL from Diesel ASTs** and now
38//! includes an initial HTTP-backed [`ClickHouseConnection`] plus explicit
39//! [`ClickHouseConnectionOptions`] for idiomatic Diesel `load`/`execute`/`batch_execute` workflows. You can still execute rendered SQL through your
40//! ClickHouse client of choice when you need client-specific behavior.
41//!
42//! ## Guides
43//!
44//! Long-form Markdown guides from `./docs/` are rendered under [`docs`] on
45//! docs.rs:
46//!
47//! - [`docs::usage`] for usage guidance.
48//! - [`docs::tutorial`] for the NYC taxi tutorial translated to Diesel.
49//! - [`docs::feature_matrix`] for the implementation checklist.
50//! - [`docs::connection_design`] for connection design notes.
51
52#![cfg_attr(docsrs, feature(doc_cfg))]
53#![doc(html_root_url = "https://docs.rs/diesel-clickhouse/0.1.0")]
54
55mod aggregates;
56mod backend;
57mod cast;
58mod clauses;
59mod connection;
60mod ddl;
61pub mod docs;
62mod functions;
63mod grouping;
64mod higher_order;
65mod joins;
66mod json;
67mod operators;
68mod ordering;
69mod serialize;
70mod types;
71mod vectors;
72mod window;
73
74pub use aggregates::{
75    AggregateBuilder, AggregateCall, AggregateIfArgs, ApproxTopSumItem, ApproxTopSumResult,
76    BinaryParametricAggregate, Histogram, HistogramBucket, NoAggregateArgs, OneAggregateArg,
77    ParametricAggregate, Quantile, TwoAggregateArgs, aggregate, approx_top_sum,
78    approx_top_sum_with_reserved, histogram, quantile, quantile_deterministic, quantile_exact,
79    quantile_tdigest, quantile_timing, quantiles, quantiles_timing, top_k,
80};
81pub use backend::{ClickHouse, ClickHouseQueryBuilder, ClickHouseTypeMetadata, to_sql};
82pub use cast::{
83    CastFunction, accurate_cast, accurate_cast_or_default, accurate_cast_or_null, cast,
84};
85pub use clauses::{
86    ArrayJoin, ArrayJoinKind, ClickHouseQueryDsl, Final, Format, FormattedQuery, IntoOutfileQuery,
87    LimitBy, LimitWithTies, NoSampleOffset, NoWithBindings, OutfileCompression, OutfileMode,
88    Prewhere, Sample, SampleOffset, Setting, SettingValue, SettingsQuery, WithBinding,
89    WithCteBinding, WithQuery, array_join_clause, array_join_clause_as, final_table, format,
90    into_outfile, left_array_join_clause, left_array_join_clause_as, limit_by_col, prewhere,
91    sample, sample_offset, settings, with_alias, with_cte, with_materialized_cte, with_ties,
92};
93pub use connection::{
94    ClickHouseConnection, ClickHouseConnectionOptions, ClickHouseCursor, ClickHouseField,
95    ClickHouseRow, ClickHouseTransactionManager,
96};
97pub use ddl::{
98    AlterTable, BufferEngine, Column, CreateMaterializedView, CreateMaterializedViewBuilder,
99    CreateTable, DataType, DistributedEngine, EngineSetting, EngineSettingValue, IndexType,
100    MergeTree, MutationAssignment, NestedField, PartitionExpr, TableEngine, TableIndex,
101    TableProjection, VectorDistanceFunction, VectorIndexAlgorithm, VectorQuantization,
102    VectorSimilarityIndex, aggregating_merge_tree, all_partitions, alter_table, buffer,
103    collapsing_merge_tree, create_materialized_view, create_table, distributed, merge_tree,
104    mutation_assignment, partition_expr, partition_id, projection, replacing_merge_tree,
105    replacing_merge_tree_with, summing_merge_tree, summing_merge_tree_with,
106    vector_similarity_index, versioned_collapsing_merge_tree,
107};
108pub use functions::{
109    abs, analysis_of_variance, any_last, any_value, arg_max, arg_min, array_concat, array_distinct,
110    array_element, array_join, avg_if, avg_merge, avg_merge_state, avg_state, base64_decode,
111    base64_encode, ceil, city_hash64, concat, corr, cosine_distance, count_if, count_merge,
112    count_merge_state, count_state, covar_pop, covar_pop_stable, covar_samp, covar_samp_stable,
113    cut_query_string, date_diff, date_trunc, domain, domain_without_www, empty, farm_fingerprint64,
114    finalize_aggregation, first_significant_subdomain, floor, greatest, group_array,
115    group_array_if, group_array_merge, group_array_state, has, has_all, has_any, hex, if_, ilike,
116    ilike_escape, int_div, ipv4_num_to_string, ipv4_string_to_num, ipv6_num_to_string,
117    is_ipv4_string, is_ipv6_string, is_not_null, is_null, is_valid_json, json_exists,
118    json_extract_bool, json_extract_float, json_extract_int, json_extract_int_ci, json_extract_raw,
119    json_extract_raw_ci, json_extract_string, json_extract_string_ci, json_extract_uint, json_has,
120    json_length, json_query, json_value, l1_distance, l1_norm, l2_distance, l2_norm, least, length,
121    like, like_escape, linf_distance, linf_norm, lower, mann_whitney_u_test, map_contains,
122    map_from_arrays, map_keys, map_values, max_if, max_merge, max_state, min_if, min_merge,
123    min_state, multi_fuzzy_match_all_indices, multi_fuzzy_match_any, multi_fuzzy_match_any_index,
124    multi_match_all_indices, multi_match_any, multi_match_any_index, not_empty, not_ilike,
125    not_ilike_escape, not_like, not_like_escape, position, regexp_match, replace_all, round,
126    simple_json_extract_float, simple_json_extract_int, simple_json_extract_string,
127    simple_json_has, sip_hash64, stddev_pop, stddev_pop_stable, stddev_samp, stddev_samp_stable,
128    substring, sum_if, sum_merge, sum_merge_state, sum_state, to_bool, to_date, to_date_time,
129    to_date_time64, to_day_of_month, to_float32, to_float64, to_float64_or_null,
130    to_float64_or_zero, to_hour, to_int8, to_int16, to_int32, to_int32_or_null, to_int64,
131    to_int64_or_null, to_int64_or_zero, to_int128, to_int256, to_ipv4, to_ipv6, to_minute,
132    to_month, to_start_of_day, to_start_of_hour, to_start_of_minute, to_start_of_month,
133    to_start_of_year, to_string, to_uint8, to_uint16, to_uint32, to_uint32_or_null, to_uint64,
134    to_uint64_or_null, to_uint64_or_zero, to_uint128, to_uint256, to_unix_timestamp, to_year,
135    top_level_domain, try_base64_decode, unhex, uniq, uniq_exact, uniq_exact_if, uniq_exact_merge,
136    uniq_exact_state, uniq_if, uniq_merge, uniq_state, upper, url_fragment, url_path,
137    url_path_full, url_protocol, url_query_string, var_pop, var_pop_stable, var_samp,
138    var_samp_stable, xx_hash64,
139};
140pub use grouping::{
141    GroupByAll, GroupByModifier, GroupByModifierKind, Grouping, GroupingSets, cube, group_by_all,
142    grouping, grouping_sets, rollup, with_totals,
143};
144pub use higher_order::{
145    HigherOrderFunction, Lambda, array_all, array_count, array_exists, array_filter, array_map,
146    array_map_as, lambda, lambda_params, lambda2, map_apply, map_filter,
147};
148pub use joins::{
149    ClickHouseJoin, ClickHouseJoinBuilder, ClickHouseJoinDsl, JoinKind, JoinModifier, JoinOn,
150    JoinStrictness, JoinUsing, clickhouse_join,
151};
152pub use json::{
153    JsonPathFunction, JsonPathSegment, json_extract_bool_path, json_extract_float_path,
154    json_extract_int_ci_path, json_extract_int_path, json_extract_raw_ci_path,
155    json_extract_raw_path, json_extract_string_ci_path, json_extract_string_path,
156    json_extract_uint_path,
157};
158pub use operators::{
159    ClickHouseTextExpressionMethods, GlobalIn, GlobalInDsl, ILike, NotGlobalIn, NotGlobalInDsl,
160    NotILike,
161};
162pub use ordering::{FillBound, NoFillBound, WithFill, with_fill};
163pub use vectors::{
164    VectorBytes, VectorBytesEncoding, VectorLiteral, vector_f32, vector_f32_binary, vector_f32_hex,
165    vector_f32_le_bytes, vector_f32_le_hex, vector_f64, vector_f64_binary, vector_f64_hex,
166    vector_f64_le_bytes, vector_f64_le_hex,
167};
168pub use window::{
169    NoWindowBindings, NoWindowFrame, NoWindowOrder, NoWindowPartition, Over, OverDsl, OverWindow,
170    QualifyQuery, RowsBetweenUnboundedPrecedingAndCurrentRow, WindowBinding, WindowFrame,
171    WindowFrameBound, WindowFrameUnits, WindowOrder, WindowPartition, WindowQuery, WindowSpec,
172    dense_rank, first_value, lag, lag_in_frame, last_value, lead, lead_in_frame, partition_by,
173    qualify, rank, row_number, window, window_order_by,
174};
175
176/// ClickHouse SQL-type markers for use in `table!` declarations and explicit
177/// `select` type annotations.
178pub mod sql_types {
179    pub use crate::types::{
180        AggregateFunction, Array, BFloat16, DateTime64, Decimal32, Decimal64, Decimal128,
181        Decimal256, Dynamic, Enum8, Enum16, IPv4, IPv6, Int8, Int128, Int256, Json, LowCardinality,
182        Map, Nested, Nothing, Point, Ring, Tuple, UInt8, UInt16, UInt32, UInt64, UInt128, UInt256,
183        Uuid, Variant,
184    };
185}
diesel_clickhouse/lib.rs

diesel_clickhouse/
lib.rs
