[−][src]Crate redis_ts

redis_ts proivdes 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.

[dependencies]
redis = "0.16.0"
redis_ts = "*"

Or via git:

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

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)
  .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

Query for a range of time series data.

let first_three_avg:TsRange<u64,f64> = con.ts_range(
    "my_engine", "-", "+", Some(3), Some(TsAggregationType::Avg(5000))
)?;
 
let range_raw:TsRange<u64,f64> = con.ts_range(
    "my_engine", 1234, 5678, None::<usize>, None
)?;

TS.MRANGE

Batch query multiple ranges of time series data.

let first_three_avg:TsMrange<u64,f64> = con.ts_mrange(
    "-", "+", Some(3), Some(TsAggregationType::Avg(5000)), 
    TsFilterOptions::default().equals("sensor", "temperature")
)?;
 
let range_raw:TsMrange<u64,f64> = con.ts_mrange(
    1234, 5678, None::<usize>, None, 
    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.
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.

Enums

TsAggregationType

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

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.