redis_timeseries_go

package module
v0.0.0-...-2a9e7a6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 29, 2022 License: Apache-2.0 Imports: 9 Imported by: 0

README

license CircleCI GitHub issues Codecov GoDoc Go Report Card Total alerts

redistimeseries-go

Forum Discord

Go client for RedisTimeSeries (https://github.com/RedisTimeSeries/redistimeseries), based on redigo.

Client and ConnPool based on the work of dvirsky and mnunberg on https://github.com/RediSearch/redisearch-go

Installing

$ go get github.com/0x090909/redis-timeseries

Running tests

A simple test suite is provided, and can be run with:

$ go test

The tests expect a Redis server with the RedisTimeSeries module loaded to be available at localhost:6379

Example Code

package main 

import (
        "fmt"
        redistimeseries "github.com/0x090909/redis-timeseries"
)

func main() {
	// Connect to localhost with no password
	var dbNumber = 0
	var authPWD = nil
        var client = redistimeseries.NewClient("localhost:6379", "nohelp", authPWD, dbNumber)
        var keyname = "mytest"
        _, haveit := client.Info(keyname)
        if haveit != nil {
			client.CreateKeyWithOptions(keyname, redistimeseries.DefaultCreateOptions)
			client.CreateKeyWithOptions(keyname+"_avg", redistimeseries.DefaultCreateOptions)
			client.CreateRule(keyname, redistimeseries.AvgAggregation, 60, keyname+"_avg")
        }
		// Add sample with timestamp from server time and value 100
        // TS.ADD mytest * 100 
        _, err := client.AddAutoTs(keyname, 100)
        if err != nil {
                fmt.Println("Error:", err)
        }
}

Supported RedisTimeSeries Commands

Command Recommended API and godoc
TS.CREATE CreateKeyWithOptions
TS.ALTER AlterKeyWithOptions
TS.ADD
TS.MADD MultiAdd
TS.INCRBY/TS.DECRBY IncrBy / DecrBy
TS.CREATERULE CreateRule
TS.DELETERULE DeleteRule
TS.RANGE RangeWithOptions
TS.REVRANGE ReverseRangeWithOptions
TS.MRANGE MultiRangeWithOptions
TS.MREVRANGE MultiReverseRangeWithOptions
TS.GET Get
TS.MGET
TS.INFO Info
TS.QUERYINDEX QueryIndex

License

redistimeseries-go is distributed under the Apache-2 license - see LICENSE

Documentation

Index

Constants

View Source 
const (
	CREATE_CMD     string = "TS.CREATE"
	ALTER_CMD      string = "TS.ALTER"
	ADD_CMD        string = "TS.ADD"
	MADD_CMD       string = "TS.MADD"
	INCRBY_CMD     string = "TS.INCRBY"
	DECRBY_CMD     string = "TS.DECRBY"
	CREATERULE_CMD string = "TS.CREATERULE"
	DELETERULE_CMD string = "TS.DELETERULE"
	RANGE_CMD      string = "TS.RANGE"
	REVRANGE_CMD   string = "TS.REVRANGE"
	MRANGE_CMD     string = "TS.MRANGE"
	MREVRANGE_CMD  string = "TS.MREVRANGE"
	GET_CMD        string = "TS.GET"
	MGET_CMD       string = "TS.MGET"
	INFO_CMD       string = "TS.INFO"
	QUERYINDEX_CMD string = "TS.QUERYINDEX"
	DEL_CMD        string = "DEL"
	TS_DEL_CMD     string = "TS.DEL"
)
View Source 
const TimeRangeFull = int64(-1)
View Source 
const TimeRangeMaximum = math.MaxInt64
View Source 
const TimeRangeMinimum = 0

Variables

View Source 
var DefaultCreateOptions = CreateOptions{
	Uncompressed:    false,
	RetentionMSecs:  0,
	Labels:          map[string]string{},
	ChunkSize:       0,
	DuplicatePolicy: "",
}
View Source 
var DefaultMultiGetOptions = MultiGetOptions{
	WithLabels: false,
}

MultiGetOptions are the default options for querying across multiple time-series

View Source 
var DefaultMultiRangeOptions = MultiRangeOptions{
	AggType:          "",
	TimeBucket:       -1,
	Count:            -1,
	WithLabels:       false,
	SelectedLabels:   []string{},
	Align:            -1,
	FilterByTs:       []int64{},
	FilterByValueMin: nil,
	FilterByValueMax: nil,
	GroupBy:          "",
	Reduce:           "",
}

MultiRangeOptions are the default options for querying across multiple time-series

View Source 
var DefaultRangeOptions = *NewRangeOptions()

DefaultRangeOptions are the default options for querying across a time-series range

Functions

func AddCounterArgs 

func AddCounterArgs(key string, timestamp int64, value float64, options CreateOptions) (redis.Args, error)

Add counter args for command TS.INCRBY/TS.DECRBY

func MakeStringPtr 

func MakeStringPtr(s string) *string

Helper function to create a string pointer from a string literal. Useful for calls to NewClient with an auth pass that is known at compile time.

func ParseLabels 

func ParseLabels(res interface{}) (labels map[string]string, err error)

Types

type AggregationType 

type AggregationType string
const (
	AvgAggregation   AggregationType = "AVG"
	SumAggregation   AggregationType = "SUM"
	MinAggregation   AggregationType = "MIN"
	MaxAggregation   AggregationType = "MAX"
	CountAggregation AggregationType = "COUNT"
	FirstAggregation AggregationType = "FIRST"
	LastAggregation  AggregationType = "LAST"
	StdPAggregation  AggregationType = "STD.P"
	StdSAggregation  AggregationType = "STD.S"
	VarPAggregation  AggregationType = "VAR.P"
	VarSAggregation  AggregationType = "VAR.S"
)

type Client 

type Client struct {
	Pool ConnPool
	Name string
}

Client is an interface to time series redis commands

func NewClient 

func NewClient(addr, name string, authPass *string, dbNumber int) *Client

NewClient creates a new client connecting to the redis host, and using the given name as key prefix. Addr can be a single host:port pair, or a comma separated list of host:port,host:port... In the case of multiple hosts we create a multi-pool and select connections at random

func NewClientFromPool 

func NewClientFromPool(pool *redis.Pool, name string) *Client

NewClientFromPool creates a new Client with the given pool and client name

func (*Client) Add 

func (client *Client) Add(key string, timestamp int64, value float64) (storedTimestamp int64, err error)

Add - Append (or create and append) a new sample to the series args: key - time series key name timestamp - time of value value - value

func (*Client) AddAutoTs 

func (client *Client) AddAutoTs(key string, value float64) (storedTimestamp int64, err error)

AddAutoTs - Append (or create and append) a new sample to the series, with DB automatic timestamp (using the system clock) args: key - time series key name value - value

func (*Client) AddAutoTsWithOptions 

func (client *Client) AddAutoTsWithOptions(key string, value float64, options CreateOptions) (storedTimestamp int64, err error)

AddAutoTsWithOptions - Append (or create and append) a new sample to the series, with the specified CreateOptions and DB automatic timestamp (using the system clock) args: key - time series key name value - value options - define options for create key on add

func (*Client) AddWithOptions 

func (client *Client) AddWithOptions(key string, timestamp int64, value float64, options CreateOptions) (storedTimestamp int64, err error)

AddWithOptions - Append (or create and append) a new sample to the series, with the specified CreateOptions args: key - time series key name timestamp - time of value value - value options - define options for create key on add

func (*Client) AddWithRetention 

func (client *Client) AddWithRetention(key string, timestamp int64, value float64, duration int64) (storedTimestamp int64, err error)

AddWithRetention - append a new value to the series with a duration args: key - time series key name timestamp - time of value value - value duration - value Deprecated: This function has been deprecated, use AddWithOptions instead

func (*Client) AggMultiRange 

func (client *Client) AggMultiRange(fromTimestamp int64, toTimestamp int64, aggType AggregationType,
	bucketSizeSec int, filters ...string) (ranges []Range, err error)

AggMultiRange - Query a timestamp range across multiple time-series by filters. args: fromTimestamp - start of range. You can use TimeRangeMinimum to express the minimum possible timestamp. toTimestamp - end of range. You can use TimeRangeFull or TimeRangeMaximum to express the maximum possible timestamp. aggType - aggregation type bucketSizeSec - time bucket for aggregation filters - list of filters e.g. "a=bb", "b!=aa" Deprecated: This function has been deprecated, use MultiRangeWithOptions instead

func (*Client) AggRange 

func (client *Client) AggRange(key string, fromTimestamp int64, toTimestamp int64, aggType AggregationType,
	bucketSizeSec int) (dataPoints []DataPoint, err error)

AggRange - aggregation over a ranged query args: key - time series key name fromTimestamp - start of range. You can use TimeRangeMinimum to express the minimum possible timestamp. toTimestamp - end of range. You can use TimeRangeFull or TimeRangeMaximum to express the maximum possible timestamp. aggType - aggregation type bucketSizeSec - time bucket for aggregation Deprecated: This function has been deprecated, use RangeWithOptions instead

func (*Client) AlterKeyWithOptions 

func (client *Client) AlterKeyWithOptions(key string, options CreateOptions) (err error)

Update the retention, labels of an existing key. The parameters are the same as TS.CREATE.

func (*Client) CreateKey 

func (client *Client) CreateKey(key string, retentionTime time.Duration) (err error)

CreateKey create a new time-series Deprecated: This function has been deprecated, use CreateKeyWithOptions instead

func (*Client) CreateKeyWithOptions 

func (client *Client) CreateKeyWithOptions(key string, options CreateOptions) (err error)

func (*Client) CreateRule 

func (client *Client) CreateRule(sourceKey string, aggType AggregationType, bucketSizeMSec uint, destinationKey string) (err error)

CreateRule - create a compaction rule args: sourceKey - key name for source time series aggType - AggregationType bucketSizeMSec - Time bucket for aggregation in milliseconds destinationKey - key name for destination time series

func (*Client) DecrBy 

func (client *Client) DecrBy(key string, timestamp int64, value float64, options CreateOptions) (int64, error)

Creates a new sample that decrements the latest sample's value

func (*Client) DecrByAutoTs 

func (client *Client) DecrByAutoTs(key string, value float64, options CreateOptions) (int64, error)

Creates a new sample that decrements the latest sample's value with auto timestamp

func (*Client) DeleteRange 

func (client *Client) DeleteRange(key string, fromTimestamp int64, toTimestamp int64) (totalDeletedSamples int64, err error)

DeleteRange - Delete data points for a given timeseries and interval range in the form of start and end delete timestamps. Returns the total deleted datapoints. args: 

key - time series key name
fromTimestamp - start of range. You can use TimeRangeMinimum to express the minimum possible timestamp.
toTimestamp - end of range. You can use TimeRangeFull or TimeRangeMaximum to express the maximum possible timestamp.

func (*Client) DeleteRule 

func (client *Client) DeleteRule(sourceKey string, destinationKey string) (err error)

DeleteRule - delete a compaction rule args: sourceKey - key name for source time series destinationKey - key name for destination time series

func (*Client) DeleteSerie 

func (client *Client) DeleteSerie(key string) (err error)

DeleteSerie - deletes series given the time series key name. This API is sugar coating on top of redis DEL command args: key - time series key name

func (*Client) Get 

func (client *Client) Get(key string) (dataPoint *DataPoint,
	err error)

Get - Get the last sample of a time-series. args: key - time-series key name

func (*Client) IncrBy 

func (client *Client) IncrBy(key string, timestamp int64, value float64, options CreateOptions) (int64, error)

Creates a new sample that increments the latest sample's value

func (*Client) IncrByAutoTs 

func (client *Client) IncrByAutoTs(key string, value float64, options CreateOptions) (int64, error)

Creates a new sample that increments the latest sample's value with an auto timestamp

func (*Client) Info 

func (client *Client) Info(key string) (res KeyInfo, err error)

Returns information and statistics on the time-series. args: key - time-series key name

func (*Client) MultiAdd 

func (client *Client) MultiAdd(samples ...Sample) (timestamps []interface{}, err error)

Append new samples to a list of series.

func (*Client) MultiGet 

func (client *Client) MultiGet(filters ...string) (ranges []Range, err error)

MultiGet - Get the last sample across multiple time-series, matching the specific filters. args: filters - list of filters e.g. "a=bb", "b!=aa"

func (*Client) MultiGetWithOptions 

func (client *Client) MultiGetWithOptions(multiGetOptions MultiGetOptions, filters ...string) (ranges []Range, err error)

MultiGetWithOptions - Get the last samples matching the specific filters. args: multiGetOptions - MultiGetOptions options. You can use the default DefaultMultiGetOptions filters - list of filters e.g. "a=bb", "b!=aa"

func (*Client) MultiRangeWithOptions 

func (client *Client) MultiRangeWithOptions(fromTimestamp int64, toTimestamp int64, mrangeOptions MultiRangeOptions, filters ...string) (ranges []Range, err error)

MultiRangeWithOptions - Query a timestamp range across multiple time-series by filters. args: fromTimestamp - start of range. You can use TimeRangeMinimum to express the minimum possible timestamp. toTimestamp - end of range. You can use TimeRangeFull or TimeRangeMaximum to express the maximum possible timestamp. mrangeOptions - MultiRangeOptions options. You can use the default DefaultMultiRangeOptions filters - list of filters e.g. "a=bb", "b!=aa"

func (*Client) MultiReverseRangeWithOptions 

func (client *Client) MultiReverseRangeWithOptions(fromTimestamp int64, toTimestamp int64, mrangeOptions MultiRangeOptions, filters ...string) (ranges []Range, err error)

MultiReverseRangeWithOptions - Query a timestamp range across multiple time-series by filters, in reverse direction. args: fromTimestamp - start of range. You can use TimeRangeMinimum to express the minimum possible timestamp. toTimestamp - end of range. You can use TimeRangeFull or TimeRangeMaximum to express the maximum possible timestamp. mrangeOptions - MultiRangeOptions options. You can use the default DefaultMultiRangeOptions filters - list of filters e.g. "a=bb", "b!=aa"

func (*Client) QueryIndex 

func (client *Client) QueryIndex(filters ...string) (keys []string, err error)

Get all the keys matching the filter list.

func (*Client) Range 

func (client *Client) Range(key string, fromTimestamp int64, toTimestamp int64) (dataPoints []DataPoint, err error)

Range - ranged query args: key - time series key name fromTimestamp - start of range. You can use TimeRangeMinimum to express the minimum possible timestamp. toTimestamp - end of range. You can use TimeRangeFull or TimeRangeMaximum to express the maximum possible timestamp. Deprecated: This function has been deprecated, use RangeWithOptions instead

func (*Client) RangeWithOptions 

func (client *Client) RangeWithOptions(key string, fromTimestamp int64, toTimestamp int64, rangeOptions RangeOptions) (dataPoints []DataPoint, err error)

RangeWithOptions - Query a timestamp range on a specific time-series args: key - time-series key name fromTimestamp - start of range. You can use TimeRangeMinimum to express the minimum possible timestamp. toTimestamp - end of range. You can use TimeRangeFull or TimeRangeMaximum to express the maximum possible timestamp. rangeOptions - RangeOptions options. You can use the default DefaultRangeOptions

func (*Client) ReverseRangeWithOptions 

func (client *Client) ReverseRangeWithOptions(key string, fromTimestamp int64, toTimestamp int64, rangeOptions RangeOptions) (dataPoints []DataPoint, err error)

ReverseRangeWithOptions - Query a timestamp range on a specific time-series in reverse order args: key - time-series key name fromTimestamp - start of range. You can use TimeRangeMinimum to express the minimum possible timestamp. toTimestamp - end of range. You can use TimeRangeFull or TimeRangeMaximum to express the maximum possible timestamp. rangeOptions - RangeOptions options. You can use the default DefaultRangeOptions

type ConnPool 

type ConnPool interface {
	Get() redis.Conn
	Close() error
}

type CreateOptions 

type CreateOptions struct {
	Uncompressed    bool
	RetentionMSecs  time.Duration
	Labels          map[string]string
	ChunkSize       int64
	DuplicatePolicy DuplicatePolicyType
}

CreateOptions are a direct mapping to the options provided when creating a new time-series Check https://oss.redislabs.com/redistimeseries/1.4/commands/#tscreate for a detailed description

func (*CreateOptions) Serialize 

func (options *CreateOptions) Serialize(args []interface{}) (result []interface{}, err error)

Serialize options to args Deprecated: This function has been deprecated given that DUPLICATE_POLICY and ON_DUPLICATE depend upon the issuing command, use SerializeSeriesOptions instead

func (*CreateOptions) SerializeSeriesOptions 

func (options *CreateOptions) SerializeSeriesOptions(cmd string, args []interface{}) (result []interface{}, err error)

Serialize options to args. Given that DUPLICATE_POLICY and ON_DUPLICATE depend upon the issuing command we need to specify the command for which we are generating the args for

type DataPoint 

type DataPoint struct {
	Timestamp int64
	Value     float64
}

func NewDataPoint 

func NewDataPoint(timestamp int64, value float64) *DataPoint

func ParseDataPoint 

func ParseDataPoint(rawDataPoint interface{}) (dataPoint *DataPoint, err error)

func ParseDataPoints 

func ParseDataPoints(info interface{}) (dataPoints []DataPoint, err error)

type DuplicatePolicyType 

type DuplicatePolicyType string
const (
	BlockDuplicatePolicy DuplicatePolicyType = "block" // an error will occur for any out of order sample
	FirstDuplicatePolicy DuplicatePolicyType = "first" // ignore the new value
	LastDuplicatePolicy  DuplicatePolicyType = "last"  // override with latest value
	MinDuplicatePolicy   DuplicatePolicyType = "min"   // only override if the value is lower than the existing value
	MaxDuplicatePolicy   DuplicatePolicyType = "max"   // only override if the value is higher than the existing value
)

Check https://oss.redislabs.com/redistimeseries/configuration/#duplicate_policy for more inforamtion about duplicate policies

type KeyInfo 

type KeyInfo struct {
	ChunkCount         int64
	MaxSamplesPerChunk int64 // As of RedisTimeseries >= v1.4 MaxSamplesPerChunk is deprecated in favor of ChunkSize
	ChunkSize          int64
	LastTimestamp      int64
	RetentionTime      int64
	Rules              []Rule
	Labels             map[string]string
	DuplicatePolicy    DuplicatePolicyType // Duplicate sample policy
}

func ParseInfo 

func ParseInfo(result interface{}, err error) (info KeyInfo, outErr error)

type MultiGetOptions 

type MultiGetOptions struct {
	WithLabels bool
}

MultiGetOptions represent the options for querying across multiple time-series

func NewMultiGetOptions 

func NewMultiGetOptions() *MultiGetOptions

func (*MultiGetOptions) SetWithLabels 

func (mgetopts *MultiGetOptions) SetWithLabels(value bool) *MultiGetOptions

type MultiHostPool 

type MultiHostPool struct {
	sync.Mutex
	// contains filtered or unexported fields
}

func NewMultiHostPool 

func NewMultiHostPool(hosts []string, authPass *string) *MultiHostPool

func (*MultiHostPool) Close 

func (p *MultiHostPool) Close() (err error)

func (*MultiHostPool) Get 

func (p *MultiHostPool) Get() redis.Conn

type MultiRangeOptions 

type MultiRangeOptions struct {
	AggType          AggregationType
	TimeBucket       int
	Count            int64
	WithLabels       bool
	SelectedLabels   []string
	Align            int64
	FilterByTs       []int64
	FilterByValueMin *float64
	FilterByValueMax *float64
	GroupBy          string
	Reduce           ReducerType
}

MultiRangeOptions represent the options for querying across multiple time-series

func NewMultiRangeOptions 

func NewMultiRangeOptions() *MultiRangeOptions

func (*MultiRangeOptions) SetAggregation 

func (mrangeopts *MultiRangeOptions) SetAggregation(aggType AggregationType, timeBucket int) *MultiRangeOptions

func (*MultiRangeOptions) SetAlign 

func (mrangeopts *MultiRangeOptions) SetAlign(byTimeStamp int64) *MultiRangeOptions

SetAlign sets the time bucket alignment control for AGGREGATION. This will control the time bucket timestamps by changing the reference timestamp on which a bucket is defined.

func (*MultiRangeOptions) SetCount 

func (mrangeopts *MultiRangeOptions) SetCount(count int64) *MultiRangeOptions

func (*MultiRangeOptions) SetFilterByTs 

func (mrangeopts *MultiRangeOptions) SetFilterByTs(filterByTS []int64) *MultiRangeOptions

SetFilterByTs sets the list of timestamps to filter the result by specific timestamps

func (*MultiRangeOptions) SetFilterByValue 

func (mrangeopts *MultiRangeOptions) SetFilterByValue(min, max float64) *MultiRangeOptions

SetFilterByValue filters the result by value using minimum and maximum ( inclusive )

func (*MultiRangeOptions) SetGroupByReduce 

func (mrangeopts *MultiRangeOptions) SetGroupByReduce(byLabel string, reducer ReducerType) *MultiRangeOptions

SetGroupByReduce Aggregates results across different time series, grouped by the provided label name. When combined with AGGREGATION the groupby/reduce is applied post aggregation stage.

func (*MultiRangeOptions) SetSelectedLabels 

func (mrangeopts *MultiRangeOptions) SetSelectedLabels(labels []string) *MultiRangeOptions

SetSelectedLabels limits the series reply labels to provided label names

func (*MultiRangeOptions) SetWithLabels 

func (mrangeopts *MultiRangeOptions) SetWithLabels(value bool) *MultiRangeOptions

type Range 

type Range struct {
	Name       string
	Labels     map[string]string
	DataPoints []DataPoint
}

func ParseRanges 

func ParseRanges(info interface{}) (ranges []Range, err error)

func ParseRangesSingleDataPoint 

func ParseRangesSingleDataPoint(info interface{}) (ranges []Range, err error)

type RangeOptions 

type RangeOptions struct {
	AggType          AggregationType
	TimeBucket       int
	Count            int64
	Align            int64
	FilterByTs       []int64
	FilterByValueMin *float64
	FilterByValueMax *float64
}

MultiRangeOptions represent the options for querying across multiple time-series

func NewRangeOptions 

func NewRangeOptions() *RangeOptions

func (*RangeOptions) SetAggregation 

func (rangeopts *RangeOptions) SetAggregation(aggType AggregationType, timeBucket int) *RangeOptions

func (*RangeOptions) SetAlign 

func (rangeopts *RangeOptions) SetAlign(byTimeStamp int64) *RangeOptions

SetAlign sets the time bucket alignment control for AGGREGATION. This will control the time bucket timestamps by changing the reference timestamp on which a bucket is defined.

func (*RangeOptions) SetCount 

func (rangeopts *RangeOptions) SetCount(count int64) *RangeOptions

func (*RangeOptions) SetFilterByTs 

func (rangeopts *RangeOptions) SetFilterByTs(filterByTS []int64) *RangeOptions

SetFilterByTs sets a list of timestamps to filter the result by specific timestamps

func (*RangeOptions) SetFilterByValue 

func (rangeopts *RangeOptions) SetFilterByValue(min, max float64) *RangeOptions

SetFilterByValue filters result by value using minimum and maximum ( inclusive )

type ReducerType 

type ReducerType string
const (
	SumReducer ReducerType = "SUM"
	MinReducer ReducerType = "MIN"
	MaxReducer ReducerType = "MAX"
)

type Rule 

type Rule struct {
	DestKey       string
	BucketSizeSec int
	AggType       AggregationType
}

func ParseRules 

func ParseRules(ruleInterface interface{}, err error) (rules []Rule, retErr error)

type Sample 

type Sample struct {
	Key       string
	DataPoint DataPoint
}

type SingleHostPool 

type SingleHostPool struct {
	*redis.Pool
}

func NewSingleHostPool 

func NewSingleHostPool(host string, authPass *string, dbNumber int) *SingleHostPool

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.