palicao / php-redis-time-series
Use Redis Time Series in PHP
Installs: 15 693
Dependents: 0
Suggesters: 0
Security: 0
Stars: 28
Watchers: 8
Forks: 13
Open Issues: 8
Requires
- php: >=7.2.0
- ext-redis: *
Requires (Dev)
- phpunit/phpunit: ^8.3
- vimeo/psalm: ^3.5
README
Use Redis Time Series in PHP!
Getting up and running
Install
composer require palicao/php-redis-time-series
Requirements
The library is tested against:
- PHP 7.2, 7.3, 7.4, 8.0
- RedisTimeSeries 1.4.10 (but it should work with any 1.4 version)
In order to use RedisTimeSeries 1.2 please use version 2.1.1 of this library.
Construct
$ts = new TimeSeries(
new RedisClient(
new Redis(),
new RedisConnectionParams($host, $port)
)
);
TimeSeries
methods
create
TimeSeries::create(string $key, ?int $retentionMs = null, array $labels = []): void
Creates a key, optionally setting a retention time (in milliseconds) and some labels.
See https://oss.redislabs.com/redistimeseries/commands/#tscreate.
alter
TimeSeries::alter(string $key, ?int $retentionMs = null, array $labels = []): void
Modifies an existing key's retention time and/or labels.
See https://oss.redislabs.com/redistimeseries/commands/#tsalter.
add
TimeSeries::add(Sample $sample, ?int $retentionMs = null, array $labels = []): Sample
Adds a sample.
If the key was not explicitly create
d, it's possible to set retention and labels.
See https://oss.redislabs.com/redistimeseries/commands/#tsadd.
Examples:
$sample = $ts->add(new Sample('myKey', 32.10), 10, [new Label('myLabel', 'myValue')]);
Adds a sample tomyKey
at the current timestamp (time of the redis server) and returns it (complete with dateTime).$sample = $ts->add(new Sample('myKey', 32.10, new DateTimeImmutable()), 10, [new Label('myLabel', 'myValue')]);
Adds a sample tomyKey
at a given datetime and returns it.
Please notice that RedisTimeSeries only allows to add samples in order (no sample older than the latest is allowed)
addMany
TimeSeries::addMany(array $samples): array
Adds several samples.
As usual, if no timestamp is provided, the redis server current time is used. Added samples are returned in an array.
See https://oss.redislabs.com/redistimeseries/commands/#tsmadd.
incrementBy
and decrementBy
TimeSeries::incrementBy(Sample $sample, ?int $resetMs = null, ?int $retentionMs = null, array $labels = []): void
TimeSeries::decrementBy(Sample $sample, ?int $resetMs = null, ?int $retentionMs = null, array $labels = []): void
Add a sample to a key, incrementing or decrementing the last value by an amount specified in $sample
.
The value can be optionally reset after $resetMs
milliseconds.
Similarly to add
, if the command is used on a non-existing key, it's possible to set retention and labels.
See https://oss.redislabs.com/redistimeseries/commands/#tsincrbytsdecrby.
createRule
TimeSeries::createRule(string $sourceKey, string $destKey, AggregationRule $rule): void
Creates an aggregation rule which applies the given $rule
to $sourceKey
in order to populate $destKey
.
Notice that both key must already exist otherwise the command will fail.
See https://oss.redislabs.com/redistimeseries/commands/#tscreaterule.
Example:
$ts->createRule('source', 'destination', new AggregationRule(AggregationRule::AVG, 10000)
, will populate thedestination
key by averaging the samples contained insource
over 10 second buckets.
deleteRule
TimeSeries::deleteRule(string $sourceKey, string $destKey): void
Deletes an existing aggregation rule.
See https://oss.redislabs.com/redistimeseries/commands/#tsdeleterule.
range
TimeSeries::range(string $key, ?DateTimeInterface $from = null, ?DateTimeInterface $to = null, ?int $count = null, ?AggregationRule $rule = null, bool $reverse = false): Sample[]
Retrieves samples from a key. It's possible to limit the query in a given time frame (passing $from
and $to
),
to limit the retrieved amount of samples (passing $count
), and also to pre-aggregate the results using a $rule
.
The flag $reverse
will return the results in reverse time order.
See https://oss.redislabs.com/redistimeseries/commands/#tsrange.
multiRange
and multiRangeWithLabels
TimeSeries::multiRange(Filter $filter, ?DateTimeInterface $from = null, ?DateTimeInterface $to = null, ?int $count = null, ?AggregationRule $rule = null, bool $reverse = false): Sample[]
TimeSeries::multiRangeWithLabels(Filter $filter, ?DateTimeInterface $from = null, ?DateTimeInterface $to = null, ?int $count = null, ?AggregationRule $rule = null, bool $reverse = false): SampleWithLabels[]
Similar to range
, but instead of querying by key, queries for a specific set of labels specified in $filter
.
multiRangeWithLabels
will return an array of SampleWithLabels
instead of simple Sample
s.
The flag $reverse
will return the results in reverse time order.
See https://oss.redislabs.com/redistimeseries/commands/#tsmrange.
getLastSample
TimeSeries::getLastSample(string $key): Sample
Gets the last sample for a key.
See https://oss.redislabs.com/redistimeseries/commands/#tsget.
getLastSamples
TimeSeries::getLastSamples(Filter $filter): Sample[]
Gets the last sample for a set of keys matching a given $filter
.
See https://oss.redislabs.com/redistimeseries/commands/#tsmget.
info
TimeSeries::info(string $key): Metadata
Gets useful metadata for a given key.
See https://oss.redislabs.com/redistimeseries/commands/#tsinfo.
getKeysByFilter
getKeysByFilter(Filter $filter): string[]
Retrieves the list of keys matching a given $filter
.
See https://oss.redislabs.com/redistimeseries/commands/#tsqueryindex.
Advanced connection parameters
You can manipulate your RedisConnectionParams
using the following methods:
RedisConnectionParams::setPersistentConnection(bool $persistentConnection)
enable/disable a persistent connectionRedisConnectionParams::setTimeout(int $timeout)
connection timeout in secondsRedisConnectionParams::setRetryInterval(int $retryInterval)
retry interval in secondsRedisConnectionParams::setReadTimeout(float $readTimeout)
read timeout in seconds
Building Filters
A Filter
is composed of multiple filtering operations. At least one equality operation must be provided (in the
constructor). Adding filtering operations can be chained using the method add
.
Examples:
$f = (new Filter('label1', 'value1'))->add('label2', Filter::OP_EXISTS);
filters items which have label1 = value1 and have label2.$f = (new Filter('label1', 'value1'))->add('label2', Filter::OP_IN, ['a', 'b', 'c']);
filters items which have label1 = value1 and where label2 is one of 'a', 'b' or 'c'.
Local testing
For local testing you can use the provided docker-compose.yml
file, which will create a PHP container (with the redis
extension pre-installed), and a redis container (with Redis Time Series included).
Contributors
Thanks Mrkisha for the precious contributions.