chronix 0.2.0

Chronix — an embedded, analytics-optimised time-series database.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

//! # Chronix
//!
//! The embedded-first time-series database with analytics built in.
//!
//! One dependency gives you a crash-safe, columnar time-series engine with
//! SQL (DataFusion), PromQL, forecasting and anomaly detection — in
//! process, no server, no sidecar. The same engine runs as the `chronixd`
//! server behind Grafana, Prometheus and Telegraf.
//!
//! ## Quick start
//!
//! ```no_run
//! use chronix::prelude::*;
//!
//! let db = Chronix::open_small("/tmp/mydb")?;
//!
//! let key = SeriesKey::new("cpu", tags! { "host" => "server-01" })?;
//! let point = Point::new(key, fields! { "usage" => 95.5 }, 1_700_000_000_000_000_000)?;
//! db.insert(&point)?;
//!
//! for batch in db.sql("SELECT host, avg(usage) FROM cpu GROUP BY host")? {
//!     println!("{batch:?}");
//! }
//! db.close()?;
//! # Ok::<(), chronix::DbError>(())
//! ```
//!
//! ## Where things are
//!
//! - [`Chronix`] — open, insert, query, [`sql`](Chronix::sql), forecast,
//!   rollups, retention, backup. A cheap-to-clone handle.
//! - [`prelude`] — the types and macros a typical program needs.
//! - [`sql`], [`promql`] — the two query languages, for callers that want
//!   more than [`Chronix::sql`] and [`Chronix::promql`] offer.
//! - [`rollup`], [`retention`], [`export`], [`pipeline`] — background work
//!   and interop.
//! - The engine crates are re-exported under their own names
//!   ([`chronix_core`], [`chronix_engine`], [`chronix_query`],
//!   [`chronix_analytics`], [`chronix_streaming`], [`chronix_security`],
//!   [`chronix_encoding`]) for advanced use.
//!
//! ## Stability
//!
//! Three tiers, and the difference matters when a dependency bumps:
//!
//! 1. **[`Chronix`], [`prelude`] and the types they name** — the supported
//!    surface. Arrow's `RecordBatch` is the only third-party type in it, and
//!    deliberately so: a columnar database that hides its batches is a
//!    database you cannot stream out of.
//! 2. **[`sql`] and [`promql`]** — for callers who want more than
//!    [`Chronix::sql`] and [`Chronix::promql`] offer. `sql` takes and returns
//!    `DataFusion` types, so it moves when `DataFusion` does.
//! 3. **The re-exported engine crates** — no promise beyond their own.
//!
//! Within 0.x none of this is frozen; a breaking change bumps the minor
//! (`CONTRIBUTING.md`). `public_api` pins the tier-1 surface so that a change
//! to it is a deliberate edit rather than a side effect.

#![warn(missing_docs)]
#![deny(unsafe_code)]
#![allow(clippy::module_name_repetitions)]

/// Analytics configuration types for the Rust API.
pub mod analytics;
#[cfg(feature = "object-store")]
pub mod cold_archive;
pub mod db;
pub mod delete;
pub mod error;
pub mod export;
/// Compile-time lock ordering enforcement.
///
/// Internal: the lock hierarchy is an invariant of this crate's own
/// implementation, not a contract with callers, and the wrapper's signatures
/// are `parking_lot`'s.
pub(crate) mod lock_order;
mod maintenance;
#[macro_use]
pub mod macros;
pub mod pipeline;
pub mod promql;
pub mod retention;
pub mod rollup;
#[cfg(feature = "sql")]
pub mod sql;
pub mod timebucket;

// The engine crates, for advanced use. No aliases: a module alias is a
// second name for the same thing, and every one of them was a name the
// docs could not resolve.
pub use chronix_analytics;
pub use chronix_core;
pub use chronix_encoding;
pub use chronix_engine;
pub use chronix_query;
pub use chronix_security;
pub use chronix_streaming;

// Primary export
pub use analytics::{AnomalyConfig, ForecastConfig};
pub use db::BackupManifest;
pub use db::Chronix;
pub use db::DatabaseStatistics;
pub use delete::{DeleteBuilder, DeleteOutcome, DeleteRequest};
pub use error::DbError;
pub use error::InsertResult;
pub use export::{ParquetCompression, ParquetExportConfig};
pub use pipeline::{Pipeline, PipelineConfig};
pub use rollup::{RollupAggFn, RollupBuilder, RollupConfig, RollupRegistry, RollupState};

/// Everything a typical program needs: `use chronix::prelude::*;`.
pub mod prelude {
    pub use chronix_core::{
        ChronixConfig, ChronixConfigBuilder, ChronixError, ColumnDef, ColumnRole, ColumnType,
        CompressionCodec, FieldValue, FloatEncoding, FsyncPolicy, MeasurementSchema, Point,
        SeriesKey, Timestamp,
    };
    pub use chronix_query::{AggFn, QueryBuilder, QueryPlan};

    pub use arrow::record_batch::RecordBatch;

    pub use crate::db::Chronix;
    pub use crate::error::{DbError, InsertResult};
    pub use crate::rollup::{RollupAggFn, RollupBuilder};
    pub use crate::{fields, tags};
}