chronix 0.7.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
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

//! # 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.
//!
//! What actually changed in a release is in the
//! [changelog](https://github.com/hupe1980/chronix/blob/main/CHANGELOG.md).
//! The link is absolute and it is *here*, on the crate's own front page,
//! because this is the page a reader lands on after `cargo update` moved
//! them a minor version. There is one changelog and it lives at the
//! repository root: `cargo package` includes nothing from outside a package
//! directory, so a copy inside this crate would be a second changelog to
//! keep true rather than a copy that stays true.

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

/// Analytics configuration types for the Rust API.
#[cfg(feature = "analytics")]
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;
#[cfg(feature = "pipeline")]
pub mod pipeline;
pub mod promql;
pub mod retention;
pub mod rollup;
#[cfg(feature = "sql")]
pub mod sql;

// 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.
#[cfg(feature = "analytics")]
pub use chronix_analytics;
pub use chronix_core;
pub use chronix_encoding;
pub use chronix_engine;
pub use chronix_query;
#[cfg(feature = "security")]
pub use chronix_security;
#[cfg(feature = "streaming")]
pub use chronix_streaming;

// Primary export
#[cfg(feature = "analytics")]
pub use analytics::{AnomalyConfig, ForecastConfig};
pub use db::BackupManifest;
pub use db::Chronix;
pub use db::DatabaseStatistics;
pub use db::SegmentInfo;
pub use delete::{DeleteBuilder, DeleteOutcome, DeleteRequest};
pub use error::DbError;
pub use error::InsertResult;
pub use export::{ParquetCompression, ParquetExportConfig};
#[cfg(feature = "pipeline")]
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::{
        BucketWidth, ChronixConfig, ChronixConfigBuilder, ChronixError, ColumnDef, ColumnRole,
        ColumnType, CompressionCodec, Decimal, FieldValue, FloatEncoding, FsyncPolicy,
        MeasurementSchema, Point, SeriesKey, TimeBucket, 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};
}