Crate redis_ts

redis_ts provides a small trait with extension functions for the redis crate to allow working with redis time series data that can be installed as a redis module. Time series commands are available as synchronous and asynchronous versions.

The crate is called redis_ts and you can depend on it via cargo. You will also need redis in your dependencies. It has been tested against redis 0.25.2 but should work with versions higher than that.

[dependencies]
redis = "0.25.2"
redis_ts = "0.5.4"

Or via git:

[dependencies.redis_ts]
git = "https://github.com/tompro/redis_ts.git"

With async feature inherited from the redis crate (either: ‘async-std-comp’ or ’tokio-comp):

[dependencies]
redis = "0.25.2"
redis_ts = { version = "0.5.4", features = ['tokio-comp'] }

Synchronous usage

To enable redis time series commands you simply load the redis_ts::TsCommands into the scope. All redis time series commands will then be available on your redis connection.

use redis::Commands;
use redis_ts::{TsCommands, TsOptions};

let client = redis::Client::open("redis://127.0.0.1/")?;
let mut con = client.get_connection()?;

let _:() = con.ts_create("my_ts", TsOptions::default())?;

Asynchronous usage

To enable redis time series async commands you simply load the redis_ts::TsAsyncCommands into the scope. All redis time series commands will then be available on your async redis connection.

use redis::AsyncCommands;
use redis_ts::{AsyncTsCommands, TsOptions};

let client = redis::Client::open("redis://127.0.0.1/")?;
let mut con = client.get_async_connection().await?;

let _:() = con.ts_create("my_ts", TsOptions::default()).await?;

Supported commands

The following examples work with the synchronous and asynchronous API. For simplicity all examples will use the synchronous API. To use them async simply run them whithin an async function and append the .await after the command call.

TS.CREATE

Creates new time series keys. TsOptions can help you build the time series configuration you want to have.

let my_opts = TsOptions::default()
  .retention_time(60000)
  .uncompressed(false)
  .duplicate_policy(TsDuplicatePolicy::Last)
  .label("component", "engine")
  .label("sensor", "temperature");

let _:() = con.ts_create("my_engine", my_opts)?;

TS.ALTER

Modifies existing time series keys. Note: You can not modify the uncompressed option of an existing time series so the flag will be ignored.

let my_opts = TsOptions::default()
  .retention_time(600000)
  .label("component", "spark_plug")
  .label("sensor", "temperature");

let _:() = con.ts_alter("my_engine", my_opts)?;

TS.ADD

Add a value to time series. When providing time series options with the add command the series will be created if it does not yet exist.

/// With a timestamp
let ts:u64 = con.ts_add("my_engine", 123456789, 36.1)?;

/// Auto redis timestamp
let now:u64 = con.ts_add_now("my_engine", 36.2)?;

/// Add with auto create.
let my_opts = TsOptions::default()
  .retention_time(600000)
  .label("component", "spark_plug")
  .label("sensor", "temperature");

let create_ts:u64 = con.ts_add_create("my_engine", "*", 35.7, my_opts)?;

TS.MADD

Add multiple values to one or multiple time series.

let r:Vec<u64> = con.ts_madd(&[
  ("my_engine", 1234, 36.0),
  ("other_engine", 4321, 33.9)
])?;

TS.INCRBY

Increment a time series value.

/// With a timestamp
let ts:u64 = con.ts_incrby("my_engine", 123456789, 2)?;

/// Auto redis timestamp
let now:u64 = con.ts_incrby_now("my_engine", 7.0)?;

/// With auto create.
let my_opts = TsOptions::default()
  .retention_time(600000)
  .label("component", "spark_plug")
  .label("sensor", "temperature");

let create_ts:u64 = con.ts_incrby_create("my_engine", "*", 16.97, my_opts)?;

TS.DECRBY

Decrement a time series value.

/// With a timestamp
let ts:u64 = con.ts_decrby("my_engine", 123456789, 2)?;

/// Auto redis timestamp
let now:u64 = con.ts_decrby_now("my_engine", 7.0)?;

/// With auto create.
let my_opts = TsOptions::default()
  .retention_time(600000)
  .label("component", "spark_plug")
  .label("sensor", "temperature");

let create_ts:u64 = con.ts_decrby_create("my_engine", "*", 16.97, my_opts)?;

TS.CREATERULE

Create time series compaction rules.

let _:() = con.ts_createrule("my_engine", "my_engine_avg", TsAggregationType::Avg(5000))?;

TS.DELETERULE

Delete time series compaction rules.

let _:() = con.ts_deleterule("my_engine", "my_engine_avg")?;

TS.RANGE/TS.REVRANGE

Query for a range of time series data.

fn run() -> redis::RedisResult<()> {
let first_three_avg:TsRange<u64,f64> = con.ts_range(
    "my_engine",
    TsRangeQuery::default()
        .count(3)
        .aggregation_type(TsAggregationType::Avg(5000))
)?;

let range_raw:TsRange<u64,f64> = con.ts_range(
    "my_engine",
    TsRangeQuery::default().from(1234).to(5678)
)?;

let rev_range_raw:TsRange<u64,f64> = con.ts_revrange(
    "my_engine",
    TsRangeQuery::default().from(1234).to(5678)
)?;

TS.MRANGE/TS.MREVRANGE

Batch query multiple ranges of time series data.

let first_three_avg:TsMrange<u64,f64> = con.ts_mrange(
    TsRangeQuery::default().count(3).aggregation_type(TsAggregationType::Avg(5000)),
    TsFilterOptions::default().equals("sensor", "temperature")
)?;

let range_raw:TsMrange<u64,f64> = con.ts_mrange(
    TsRangeQuery::default().from(1234).to(5678),
    TsFilterOptions::default().equals("sensor", "temperature")
)?;

let rev_range_raw:TsMrange<u64,f64> = con.ts_mrevrange(
    TsRangeQuery::default().from(1234).to(5678),
    TsFilterOptions::default().equals("sensor", "temperature")
)?;

TS.GET

Get the most recent value of a time series.

let latest:Option<(u64,f64)> = con.ts_get("my_engine")?;

TS.MGET

Get the most recent value of multiple time series.

let temperature:TsMget<u64,f64> = con.ts_mget(
    TsFilterOptions::default().equals("sensor", "temperature").with_labels(true)
)?;

TS.INFO

Get information about a time series key.

let info:TsInfo = con.ts_info("my_engine")?;

TS.QUERYINDEX

Get the keys of time series filtered by given filter.

let index:Vec<String> = con.ts_queryindex(
    TsFilterOptions::default().equals("sensor", "temperature")
)?;

Structs

TsFilterOptions

Let’s you build redis time series filter query options via a builder pattern. Filters can be used in different commands like TS.MGET, TS.MRANGE and TS.QUERYINDEX.

TsInfo

Provides information about a redis time series key.

TsMget

Represents a TS.MGET redis time series result. The concrete types for timestamp and value eg <u64,f64> can be provided from the call site.

TsMrange

Represents a TS.MRANGE redis time series result with multiple entries. The concrete types for timestamp and value eg <u64,f64> can be provided from the call site.

TsMrangeEntry

Represents a TS.MRANGE redis time series value. The concrete types for timestamp and value eg <u64,f64> can be provided from the call site.

TsOptions

Options for a redis time series key. Can be used in multiple redis time series calls (CREATE, ALTER, ADD, …). The uncompressed option will only be respected in a TS.CREATE.

TsRange

Represents a TS.RANGE redis time series result. The concrete types for timestamp and value eg <u64,f64> can be provided from the call site.

TsRangeQuery

Let’s you build a ts range query with all options via a builder pattern:

Enums

TsAggregationType

Allows you to specify a redis time series aggreation with a time bucket.

TsAlign

A time bucket alignment control for AGGREGATION. It controls the time bucket timestamps by changing the reference timestamp on which a bucket is defined.

TsBucketTimestamp

Bucket timestamp controls how bucket timestamps are reported.

TsDuplicatePolicy

Different options for handling inserts of duplicate values. Block is the behaviour redis time series was using before preventing all inserts of values older or equal to latest value in series. Fist will simply ignore the new value (as opposed to returning an error), Last will use the new value, Min the lower and Max the higher value.

Traits

AsyncTsCommands

Provides a high level synchronous API to work with redis time series data types. Uses some abstractions for easier handling of time series related redis command arguments. All commands are directly available on ConnectionLike types from the redis crate.

TsCommands

Provides a high level synchronous API to work with redis time series data types. Uses some abstractions for easier handling of time series related redis command arguments. All commands are directly available on ConnectionLike types from the redis crate.