All Products
Search
Document Center

:TS

最終更新日:Aug 12, 2024

TairTS is a time series data structure that is developed on top of a Redis module. This data structure provides low-latency and high-concurrency in-memory read and write access, supports fast filtering and aggregate queries, and has both storage and computing capabilities. TairTS simplifies the processing of time series data and significantly improves performance.

Overview

Compared with RedisTimeSeries, TairTS provides a richer set of features:

  • Pkey-level aggregation. TairTS introduces the pkey structure as an additional hash layer to facilitate aggregate queries across multiple timelines.

    For example, you can create multiple skeys that are named after metric names and device IDs in the foo pkey. Examples: temperature:1, pressure:1, and distance:1. Then, you can run the EXTS.S.MRANGE command provided by TairTS to retrieve custom monitoring data such as skeys that have a device ID of 1. If you want to implement a similar feature by using RedisTimeSeries, you must insert a large number of aggregate queries into business logic code.

    Figure 1. Comparison between TairTS and RedisTimeSeries TairTS数据结构图

    The following section describes the structure of TairTS data:

    • Pkey: a piece of TairTS data that represents a set of timelines. A pkey can consist of multiple skeys.

    • Skey: a timeline. An skey can consist of multiple chunks that have a fixed capacity. You can attach one or more different labels to each skey. Then, skeys can be filtered by label.

    • Chunk: a data chunk. A chunk can store multiple data points.

      • A chunk can have a custom capacity of up to 256 data points.

      • Chunks serve as the smallest unit for data eviction. A chunk is deleted after all data points in the chunk expire.

    • DataPoint: a piece of time series data that includes a timestamp and a DOUBLE-type value.

  • Aggregate queries in scenarios such as downsampling, attribute filtering, batch query, and the use of multiple numerical functions. This feature integrates batch query and aggregation in a single command to reduce network interaction and provide responses within milliseconds.

  • Update or accumulation of historical time series data.

  • Configuration of time-to-live (TTL) for skeys. A TTL can be configured for each skey, enabling data to be automatically purged and the timeline to advance based on predefined time windows.

  • Efficient compression with the Gorilla algorithm. TairTS uses the Gorilla compression algorithm and specific storage techniques to significantly reduce storage costs.

Typical scenarios

  • Storage and computing of monitoring data

  • Per-second monitoring for application performance management (APM)

  • Data analysis and processing for IoT

  • Risk control in throttling scenarios

  • Caching of hot news

  • Use of time window functions

Best practices

Implement fine-grained monitoring by using TairTS

Prerequisites

The instance that you want to manage is a Tair DRAM-based instance.

If the instance is a DRAM-based instance that is compatible with Redis 5.0, the minor version of the instance must be 1.7.20 or later.

Note

The latest minor version provides more features and higher stability. We recommend that you update the instance to the latest minor version. For more information, see Update the minor version of an instance. If your instance is a cluster instance or read/write splitting instance, we recommend that you update the proxy nodes in the instance to the latest minor version to ensure that all commands can be run as expected.

Precautions

  • The TairTS data that you want to manage is stored on a Tair instance.

  • TairTS supports real-time, high-concurrency writes and queries but provides limited storage capacity. We recommend that you specify TTL for TairTS data to ensure that expired data is deleted in a timely manner.

  • To reduce storage costs, we recommend that you specify the CHUNK_SIZE parameter in the following ways:

    • If an skey contains more than 5,000 data points on average, set CHUNK_SIZE to 256. This is the default value.

    • If an skey contains less than 5,000 data points on average, set CHUNK_SIZE to a value that is calculated by using the following formula: Chunk size = Average number of data points of an skey/20. If an skey contains 1,000 data points on average, set CHUNK_SIZE to 50.

Important

Breaking changes:

On July 22, 2024, the 24.7.0.0 version of Tair DRAM-based instances that are compatible with Redis 6.0 was released. This version introduces a new parameter called ts-auto-del-empty-skey-enable, which is set to yes by default. This indicates that when all data points in an skey expire, the skey is automatically deleted. However, in versions prior to 24.7.0.0 of Tair DRAM-based instances that are compatible with Redis 6.0, skeys whose data points expire are not deleted by default.

Before you use TairTS on a Tair DRAM-based instance that is compatible with Redis 6.0, we recommend that you upgrade the instance to version 24.7.0.0 or later, and confirm and manually adjust the ts-auto-del-empty-skey-enable parameter settings. This can prevent any potential impact on your business due to the change in default behavior.

Supported commands

Table 1. TairTS commands

Type

Command

Syntax

Description

Basic write operations

EXTS.P.CREATE

EXTS.P.CREATE Pkey

Creates a TairTS pkey. If a pkey with the same name already exists, the pkey cannot be created.

EXTS.S.CREATE

EXTS.S.CREATE Pkey Skey [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 label2 val2 ...]

Creates an skey in a specified pkey. If the pkey does not exist, it is automatically created. If an skey with the same name already exists, the skey cannot be created.

Note

You can specify parameters for the skey, such as the expiration time and whether to enable compression.

EXTS.S.ALTER

EXTS.S.ALTER Pkey Skey [DATA_ET time]

Modifies the metadata of a specified skey. Only the DATA_ET time value can be modified.

EXTS.S.ADD

EXTS.S.ADD Pkey Skey ts value [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Inserts a data point into an skey. If the pkey or skey does not exist, the pkey or skey is automatically created. The parameters for the skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

EXTS.S.MADD

EXTS.S.MADD Pkey keynumber Skey ts value [Skey ts value ...] [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Inserts a data point into multiple skeys of a pkey. If the pkey or an skey does not exist, the pkey or skey is automatically created. The parameters for an skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

EXTS.S.INCRBY

EXTS.S.INCRBY Pkey Skey ts value [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Inserts a data point into an skey. If the data point that you want to insert has a positive value, the inserted value is added to the value of the last data point that exists in the skey. If the data point has a negative value, the inserted value is subtracted from the value of the last data point that exists in the skey. If the pkey or skey does not exist, the pkey or skey is automatically created. The default initial value is 0. The parameters for the skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

EXTS.S.MINCRBY

EXTS.S.MINCRBY Pkey keynumber Skey ts value [Skey ts value ...] [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Inserts a data point into multiple skeys of a pkey. If the data point that you want to insert has a positive value, the inserted value is added to the value of the last data point that exists in each skey. If the data point has a negative value, the inserted value is subtracted from the value of the last data point that exists in each skey. If the pkey or an skey does not exist, the pkey or skey is automatically created. The default initial value is 0. The parameters for an skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

EXTS.S.DEL

EXTS.S.DEL Pkey Skey

Deletes an skey and all data points in the skey from a pkey.

Basic read operations

EXTS.S.GET

EXTS.S.GET Pkey Skey

Queries the value of the last data point in a specified skey.

EXTS.S.INFO

EXTS.S.INFO Pkey Skey

Queries the metadata of a specified skey. The metadata includes the number of data points, the timestamp and value of the last data point, and the label information of the skey.

EXTS.S.QUERYINDEX

EXTS.S.QUERYINDEX Pkey filter1 [filter2 ...]

Queries the skeys that meet specified filter conditions in a pkey.

Aggregate operations

EXTS.S.RANGE

EXTS.S.RANGE Pkey Skey fromTs toTs [MAXCOUNT count] [AGGREGATION aggregationType timeBucket]

Queries the number of data points that exist in an skey during a specified time range. The time range is a closed interval.

EXTS.S.MRANGE

EXTS.S.MRANGE Pkey fromTs toTs [MAXCOUNT count] [AGGREGATION aggregationType timeBucket] [WITHLABELS] FILTER filter1 [filter2 ...]

Queries the number of data points that meet specified filter conditions in multiple skeys during a specified time range. The time range is a closed interval.

EXTS.P.RANGE

EXTS.P.RANGE Pkey fromTs toTs pkeyAggregationType pkeyTimeBucket [MAXCOUNT count] [AGGREGATION aggregationType timeBucket] [WITHLABELS] FILTER filter1 [filter2 ...]

Aggregates data points in a pkey that meet specified filter conditions. If you specify one or more skeys for aggregation, the skeys are first aggregated in the same manner as when the EXTS.S.MRANGE command is used. Then, pkeys are aggregated based on the skey aggregation results.

Concurrent write operations

EXTS.S.RAW_MODIFY

EXTS.S.RAW_MODIFY Pkey Skey ts value [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Modifies the value of a data point in a specified skey. If the pkey or skey does not exist, the pkey or skey is automatically created. The parameters for the skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

EXTS.S.RAW_MMODIFY

EXTS.S.RAW_MMODIFY Pkey keynumber Skey ts value [Skey ts value ...] [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Modifies the value of a data point in multiple skeys at a time. If the pkey or an skey does not exist, the pkey or skey is automatically created. The parameters for an skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

EXTS.S.RAW_INCRBY

EXTS.S.RAW_INCRBY Pkey Skey ts value [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Modifies the value of a data point in a specified skey. You can specify an increment or a decrement by which to modify the value. If the pkey or skey does not exist, the pkey or skey is automatically created. The default initial value is 0. The parameters for the skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

EXTS.S.RAW_MINCRBY

EXTS.S.RAW_MINCRBY Pkey keynumber Skey ts value [Skey ts value ...] [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Modifies the value of a data point in multiple skeys at a time. You can specify an increment or a decrement by which to modify the values. If the pkey or an skey does not exist, the pkey or skey is automatically created. The parameters for an skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

General-purpose operations

DEL

DEL key [key ...]

Deletes one or more TairTS keys.

Note

The following list describes the conventions for the command syntax used in this topic:

  • Uppercase keyword: indicates the command keyword.

  • Italic text: indicates variables.

  • [options]: indicates that the enclosed parameters are optional. Parameters that are not enclosed by brackets must be specified.

  • A|B: indicates that the parameters separated by the vertical bars (|) are mutually exclusive. Only one of the parameters can be specified.

  • ...: indicates that the parameter preceding this symbol can be repeatedly specified.

EXTS.P.CREATE

Item

Description

Syntax

EXTS.P.CREATE Pkey

Time complexity

O(1)

Command description

Creates a TairTS pkey. If a pkey with the same name already exists, the pkey cannot be created.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.P.CREATE foo

Sample output:

OK

EXTS.S.CREATE

Item

Description

Syntax

EXTS.S.CREATE Pkey Skey [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 label2 val2 ...]

Time complexity

O(1)

Command description

Creates an skey in a specified pkey. If the pkey does not exist, it is automatically created. If an skey with the same name already exists, the skey cannot be created.

Note

You can specify parameters for the skey, such as the expiration time and whether to enable compression.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • Skey: the name of the skey.

  • DATA_ET time: the relative expiration time of the data point. Unit: milliseconds. This parameter is left empty by default, which indicates that the data point does not expire.

  • CHUNK_SIZE: the number of data points that can be stored in a chunk. Default value: 256. Valid values: 1 to 256.

  • UNCOMPRESSED: specifies that compression is disabled for the skey. This parameter is left empty by default, which indicates that compression is enabled for the skey.

  • LABELS: the labels of the skey. You can specify one or more label-value pairs. Example: LABELS sensor_id 1.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.S.CREATE foo temperature DATA_ET 10000000 LABELS sensor_id 1

Sample output:

OK

EXTS.S.ALTER

Item

Description

Syntax

EXTS.S.ALTER Pkey Skey [DATA_ET time]

Time complexity

O(1)

Command description

Modifies the metadata of a specified skey. Only the DATA_ET time value can be modified.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • Skey: the name of the skey.

  • DATA_ET time: the relative expiration time of the data point. Unit: milliseconds. This parameter is left empty by default, which indicates that the data point does not expire.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.S.ALTER foo temperature DATA_ET 100000

Sample output:

OK

EXTS.S.ADD

Item

Description

Syntax

EXTS.S.ADD Pkey Skey ts value [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Time complexity

O(1)

Command description

Inserts a data point into an skey. If the pkey or skey does not exist, the pkey or skey is automatically created. The parameters for the skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • Skey: the name of the skey.

  • ts: the UNIX timestamp of the data point. Unit: milliseconds. A value of * can be used to specify the timestamp of the current time.

  • value: the value of the data point. The value must be a double-precision floating-point number.

  • DATA_ET time: the relative expiration time of the data point. Unit: milliseconds. This parameter is left empty by default, which indicates that the data point does not expire.

  • CHUNK_SIZE: the number of data points that can be stored in a chunk. Default value: 256. Valid values: 1 to 256.

  • UNCOMPRESSED: specifies that compression is disabled for the skey. This parameter is left empty by default, which indicates that compression is enabled for the skey.

  • LABELS: the labels of the skey. You can specify one or more label-value pairs. Example: LABELS sensor_id 1.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.S.ADD foo temperature * 30.5 DATA_ET 1000000 LABELS sensor_id 1

Sample output:

OK

EXTS.S.MADD

Item

Description

Syntax

EXTS.S.MADD Pkey keynumber Skey ts value [Skey ts value ...] [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Time complexity

O(n), where n indicates the number of skeys.

Command description

Inserts a data point into multiple skeys of a pkey. If the pkey or an skey does not exist, the pkey or skey is automatically created. The parameters for an skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • keynumber: the number of skeys.

  • Skey: the name of the skey.

  • ts: the UNIX timestamp of the data point. Unit: milliseconds. A value of * can be used to specify the timestamp of the current time.

  • value: the value of the data point. The value must be a double-precision floating-point number.

  • DATA_ET time: the relative expiration time of the data point. Unit: milliseconds. This parameter is left empty by default, which indicates that the data point does not expire.

  • CHUNK_SIZE: the number of data points that can be stored in a chunk. Default value: 256. Valid values: 1 to 256.

  • UNCOMPRESSED: specifies that compression is disabled for the skey. This parameter is left empty by default, which indicates that compression is enabled for the skey.

  • LABELS: the labels of the skey. You can specify one or more label-value pairs. Example: LABELS sensor_id 1.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.S.MADD foo 3 temperature * 30.2 pressure * 2.05 distance * 0.5

Sample output:

1) OK
2) OK
3) OK

EXTS.S.INCRBY

Item

Description

Syntax

EXTS.S.INCRBY Pkey Skey ts value [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Time complexity

O(1)

Command description

Inserts a data point into an skey. If the data point that you want to insert has a positive value, the inserted value is added to the value of the last data point that exists in the skey. If the data point has a negative value, the inserted value is subtracted from the value of the last data point that exists in the skey. If the pkey or skey does not exist, the pkey or skey is automatically created. The default initial value is 0. The parameters for the skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • Skey: the name of the skey.

  • ts: the UNIX timestamp of the data point. Unit: milliseconds. A value of * can be used to specify the timestamp of the current time.

  • value: the value that you want to add to the data point value. The value can be negative. In this case, the value is subtracted from the data point value. The value must be a double-precision floating-point number.

  • DATA_ET time: the relative expiration time of the data point. Unit: milliseconds. This parameter is left empty by default, which indicates that the data point does not expire.

  • CHUNK_SIZE: the number of data points that can be stored in a chunk. Default value: 256. Valid values: 1 to 256.

  • UNCOMPRESSED: specifies that compression is disabled for the skey. This parameter is left empty by default, which indicates that compression is enabled for the skey.

  • LABELS: the labels of the skey. You can specify one or more label-value pairs. Example: LABELS sensor_id 1.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Run the EXTS.S.ADD foo temperature 1644310456023 30.0 command in advance.

Sample command:

EXTS.S.INCRBY foo temperature 1644372093031 2

Sample output:

OK

If the EXTS.S.GET foo temperature command is run at this time, the following output is returned:

1) (integer) 1644372093031
2) "32"

EXTS.S.MINCRBY

Item

Description

Syntax

EXTS.S.MINCRBY Pkey keynumber Skey ts value [Skey ts value ...] [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Time complexity

O(n), where n indicates the number of skeys.

Command description

Inserts a data point into multiple skeys of a pkey. If the data point that you want to insert has a positive value, the inserted value is added to the value of the last data point that exists in each skey. If the data point has a negative value, the inserted value is subtracted from the value of the last data point that exists in each skey. If the pkey or an skey does not exist, the pkey or skey is automatically created. The default initial value is 0. The parameters for an skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • keynumber: the number of skeys.

  • Skey: the name of the skey.

  • ts: the UNIX timestamp of the data point. Unit: milliseconds. A value of * can be used to specify the timestamp of the current time.

  • value: the value that you want to add to the data point value. The value can be negative. In this case, the value is subtracted from the data point value. The value must be a double-precision floating-point number.

  • DATA_ET time: the relative expiration time of the data point. Unit: milliseconds. This parameter is left empty by default, which indicates that the data point does not expire.

  • CHUNK_SIZE: the number of data points that can be stored in a chunk. Default value: 256. Valid values: 1 to 256.

  • UNCOMPRESSED: specifies that compression is disabled for the skey. This parameter is left empty by default, which indicates that compression is enabled for the skey.

  • LABELS: the labels of the skey. You can specify one or more label-value pairs. Example: LABELS sensor_id 1.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.S.MINCRBY foo 3 temperature * 0.2 pressure * -0.1 distance * 0.0

Sample output:

1) OK
2) OK
3) OK

EXTS.S.DEL

Item

Description

Syntax

EXTS.S.DEL Pkey Skey

Time complexity

O(1)

Command description

Deletes an skey and all data points in the skey from a pkey.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • Skey: the name of the skey.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.S.DEL foo temperature

Sample output:

OK

EXTS.S.GET

Item

Description

Syntax

EXTS.S.GET Pkey Skey

Time complexity

O(1)

Command description

Queries the value of the last data point in a specified skey.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • Skey: the name of the skey.

Output

  • If the operation is successful, the data point value is returned.

  • If the pkey or skey does not exist, nil is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.S.GET foo temperature

Sample output:

1) (integer) 1644372730150
2) "32.2"

EXTS.S.INFO

Item

Description

Syntax

EXTS.S.INFO Pkey Skey

Time complexity

O(1)

Command description

Queries the metadata of a specified skey. The metadata includes the number of data points, the timestamp and value of the last data point, and the label information of the skey.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • Skey: the name of the skey.

Output

  • If the operation is successful, the metadata of the skey is returned.

  • If the pkey or skey does not exist, nil is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.S.INFO foo temperature

Sample output:

1) totalDataPoints            // The number of data points. 
 2) (integer) 1
 3) maxDataPoints              // The maximum number of data points that can be stored in the skey. The default value is 0, which indicates that no upper limit is imposed. 
 4) (integer) 0
 5) maxDataPointsPerChunk      // The number of data points that can be stored in a chunk. 
 6) (integer) 32
 7) dataPointsExpireTime       // The relative expiration time of the skey. Unit: milliseconds. A value of 0 indicates that the skey does not expire. 
 8) (integer) 0
 9) lastTimestamp              // The timestamp of the last data point. 
10) (integer) 1644389400996
11) chunkCount                 // The number of chunks in the skey. 
12) (integer) 1
13) lastValue                  // The value of the last data point. 
14) (integer) 28
15) labels                     // The label information of the skey. 
16) 1) 1) "sensor_id"
       2) "1"

EXTS.S.QUERYINDEX

Item

Description

Syntax

EXTS.S.QUERYINDEX Pkey filter1 [filter2 ...]

Time complexity

O(n), where n indicates the maximum number of sets involved in filter conditions.

Command description

Queries the skeys that meet specified filter conditions in a pkey.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • filter: the filter conditions. You can filter skeys by label. For more information, see the "Index filtering syntax" section of this topic.

    Note

    When you specify a filter condition, you must use one of the EQ, CONTAINS, and LIST_MATCH logics. Otherwise, filter queries cannot be performed.

Output

  • If the operation is successful, the skeys that meet specified filter conditions are returned.

  • If the pkey or skey does not exist, nil is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.S.QUERYINDEX foo sensor_id=1

Sample output:

1) "temperature"

EXTS.S.RANGE

Item

Description

Syntax

EXTS.S.RANGE Pkey Skey fromTs toTs [MAXCOUNT count] [AGGREGATION aggregationType timeBucket]

Time complexity

O(n), where n indicates the number of chunks to which the data points belong.

Command description

Queries the number of data points that exist in an skey during a specified time range. The time range is a closed interval.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • Skey: the name of the skey.

  • fromTs: the beginning of the time range to query. This value must be a UNIX timestamp. Unit: milliseconds.

  • toTs: the end of the time range to query. This value must be a UNIX timestamp. Unit: milliseconds. A value of * can be used to specify the timestamp of the current time. If this value is equal to the fromTs value, a point in time is used for the query.

  • MAXCOUNT: the number of data points to return. This parameter is left empty by default. The upper limit is 1,000,000 for Tair instances.

  • AGGREGATION:

    • aggregationType: the aggregation type, such as MAX, AVG, or SUM. For more information, see the "Aggregation syntax" section of this topic.

    • timeBucket: the time bucket used to aggregate data. Unit: milliseconds. The lower limit is 1,000.

      Tair aggregates data that exists in multiple time buckets and returns a single result. The points in time returned are the beginning of each time bucket.

    For example, AGGREGATION AVG 5000 returns the average number of data points that exist in each time bucket that lasts for 5,000 milliseconds within the specified time range.

Output

  • If the operation is successful, the number of data points that exist in an skey during a specified time range is returned. If the AGGREGATION parameter is specified in the command, the aggregation result is returned.

    Note

    An additional token value is returned. A value of 0 indicates that all data points that meet specified filter conditions are displayed. A value of 1 indicates that specific data points that meet specified filtered conditions are not displayed. You can retrieve the last data point from the result based on the token value. To implement batch aggregation, you can use the timestamp of the last data point as the beginning of the next time range to query.

  • If the pkey or skey does not exist, nil is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.S.RANGE foo test 1644459031662 * AGGREGATION AVG 10000 MAXCOUNT 2
// The command retrieves the average number of data points that exist in each time bucket that lasts for 10,000 milliseconds within the specified time range and returns two data entries.

Sample output:

1) 1) 1) (integer) 1644459730000
      2) "20.6"
   2) 1) (integer) 1644459790000
      2) "21.2"
2) (integer) 1                    // A value of 0 indicates that all data points that meet specified filter conditions are displayed. A value of 1 indicates that specific data points that meet specified filtered conditions are not displayed.

EXTS.S.MRANGE

Item

Description

Syntax

EXTS.S.MRANGE Pkey fromTs toTs [MAXCOUNT count] [AGGREGATION aggregationType timeBucket] [WITHLABELS] FILTER filter1 [filter2 ...]

Time complexity

O(n), where n indicates the number of chunks to which the data points belong.

Command description

Queries the number of data points that meet specified filter conditions in multiple skeys during a specified time range. The time range is a closed interval.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • fromTs: the beginning of the time range to query. This value must be a UNIX timestamp. Unit: milliseconds.

  • toTs: the end of the time range to query. This value must be a UNIX timestamp. Unit: milliseconds. A value of * can be used to specify the timestamp of the current time. If this value is equal to the fromTs value, a point in time is used for the query.

  • MAXCOUNT: the number of data points to return in an skey. This parameter is left empty by default. The upper limit is 1,000,000 for Tair instances.

  • AGGREGATION:

    • aggregationType: the aggregation type, such as MAX, AVG, or SUM. For more information, see the "Aggregation syntax" section of this topic.

    • timeBucket: the time bucket used to aggregate data. Unit: milliseconds. The lower limit is 1,000.

      Tair aggregates data that exists in multiple time buckets and returns a single result. The points in time returned are the beginning of each time bucket.

  • WITHLABELS: specifies whether to include label information in the output. This parameter is left empty by default, which indicates that label information is not displayed.

  • filter: the filter conditions. You can filter skeys by label. For more information, see the "Index filtering syntax" section of this topic.

    Note

    When you specify a filter condition, you must use one of the EQ, CONTAINS, and LIST_MATCH logics. Otherwise, filter queries cannot be performed.

Output

  • If the operation is successful, the skeys that meet specified filter conditions are returned.

  • If the pkey or skey does not exist, nil is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.S.MRANGE foo 1644451031662 * AGGREGATION MAX 10000 WITHLABELS FILTER sensor_id=1

Sample output:

1) 1) "temperature"
   2) 1) 1) "sensor_id"
         2) "1"
   3) 1) 1) (integer) 1644481000000
         2) "30"
   4) (integer) 0
2) 1) "test"
   2) 1) 1) "sensor_id"
         2) "1"
   3) 1) 1) (integer) 1644459730000
         2) "20"
      2) 1) (integer) 1644459790000
         2) "20"
      3) 1) (integer) 1644460620000
         2) "29"
   4) (integer) 0

EXTS.P.RANGE

Item

Description

Syntax

EXTS.P.RANGE Pkey fromTs toTs pkeyAggregationType pkeyTimeBucket [MAXCOUNT count] [AGGREGATION aggregationType timeBucket] [WITHLABELS] FILTER filter1 [filter2 ...]

Time complexity

O(n), where n indicates the number of chunks to which the data points belong.

Command description

Aggregates data points in a pkey that meet specified filter conditions. If you specify one or more skeys for aggregation, the skeys are first aggregated in the same manner as when the EXTS.S.MRANGE command is used. Then, pkeys are aggregated based on the skey aggregation results.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • fromTs: the beginning of the time range to query. This value must be a UNIX timestamp. Unit: milliseconds.

  • toTs: the end of the time range to query. This value must be a UNIX timestamp. Unit: milliseconds. A value of * can be used to specify the timestamp of the current time. If this value is equal to the fromTs value, a point in time is used for the query.

  • pkeyAggregationType: the aggregation type of the pkey. For more information, see the "Aggregation syntax" section of this topic.

  • pkeyTimeBucket: the time bucket used to aggregate data in the pkey. Unit: milliseconds. The lower limit is 1,000.

    Tair aggregates data that exists in multiple time buckets and returns a single result. The points in time returned are the beginning of each time bucket.

  • MAXCOUNT: the number of data points to return in an skey. This parameter is left empty by default. The upper limit is 1,000,000 for Tair instances.

  • AGGREGATION:

    • aggregationType: the aggregation type of the skey. For more information, see the "Aggregation syntax" section of this topic.

    • timeBucket: the time bucket used to aggregate data in the skey. Unit: milliseconds. The lower limit is 1,000.

      Tair aggregates data that exists in multiple time buckets and returns a single result. The points in time returned are the beginning of each time bucket.

  • WITHLABELS: specifies whether to include label information in the output. This parameter is left empty by default, which indicates that label information is not displayed.

  • filter: the filter conditions. You can filter skeys by label. For more information, see the "Index filtering syntax" section of this topic.

    Note

    When you specify a filter condition, you must use one of the EQ, CONTAINS, and LIST_MATCH logics. Otherwise, filter queries cannot be performed.

Output

  • If the operation is successful, the aggregation results are returned.

  • If the pkey or skey does not exist, nil is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.P.RANGE foo 1644451031662 * SUM 500000 AGGREGATION SUM 10000 FILTER sensor_id=1

Sample output:

1) 1) 1) (integer) 1644459500000
      2) "40"
   2) 1) (integer) 1644460500000
      2) "29"
   3) 1) (integer) 1644481000000
      2) "30"
2) (integer) 0

EXTS.S.RAW_MODIFY

Item

Description

Syntax

EXTS.S.RAW_MODIFY Pkey Skey ts value [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Time complexity

O(1)

Command description

Modifies the value of a data point in a specified skey. If the pkey or skey does not exist, the pkey or skey is automatically created. The parameters for the skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • Skey: the name of the skey.

  • ts: the UNIX timestamp of the data point whose value you want to update. Unit: milliseconds.

  • value: the data point value that you want to update. The value must be a double-precision floating point number.

  • DATA_ET time: the relative expiration time of the data point. Unit: milliseconds. This parameter is left empty by default, which indicates that the data point does not expire.

  • CHUNK_SIZE: the number of data points that can be stored in a chunk. Default value: 256. Valid values: 1 to 256.

  • UNCOMPRESSED: specifies that compression is disabled for the skey. This parameter is left empty by default, which indicates that compression is enabled for the skey.

  • LABELS: the labels of the skey. You can specify one or more label-value pairs. Example: LABELS sensor_id 1.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.S.RAW_MODIFY foo temperature 1644310456023 31.5

Sample output:

OK

EXTS.S.RAW_MMODIFY

Item

Description

Syntax

EXTS.S.RAW_MMODIFY Pkey keynumber Skey ts value [Skey ts value ...] [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Time complexity

O(n), where n indicates the number of skeys.

Command description

Modifies the value of a data point in multiple skeys at a time. If the pkey or an skey does not exist, the pkey or skey is automatically created. The parameters for an skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • keynumber: the number of skeys.

  • Skey: the name of the skey.

  • ts: the UNIX timestamp of the data point whose value you want to update. Unit: milliseconds.

  • value: the data point value that you want to update. The value must be a double-precision floating point number.

  • DATA_ET time: the relative expiration time of the data point. Unit: milliseconds. This parameter is left empty by default, which indicates that the data point does not expire.

  • CHUNK_SIZE: the number of data points that can be stored in a chunk. Default value: 256. Valid values: 1 to 256.

  • UNCOMPRESSED: specifies that compression is disabled for the skey. This parameter is left empty by default, which indicates that compression is enabled for the skey.

  • LABELS: the labels of the skey. You can specify one or more label-value pairs. Example: LABELS sensor_id 1.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.S.RAW_MMODIFY foo 3 temperature 1644565954814 30.2 pressure 1644565954814 2.05 distance 1644565954814 0.5

Sample output:

1) OK
2) OK
3) OK

EXTS.S.RAW_INCRBY

Item

Description

Syntax

EXTS.S.RAW_INCRBY Pkey Skey ts value [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Time complexity

O(1)

Command description

Modifies the value of a data point in a specified skey. You can specify an increment or a decrement by which to modify the value. If the pkey or skey does not exist, the pkey or skey is automatically created. The default initial value is 0. The parameters for the skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • Skey: the name of the skey.

  • ts: the UNIX timestamp of the data point whose value you want to update. Unit: milliseconds.

  • value: the value that you want to add to the data point value. The value can be negative. In this case, the value is subtracted from the data point value. The value must be a double-precision floating-point number.

  • DATA_ET time: the relative expiration time of the data point. Unit: milliseconds. This parameter is left empty by default, which indicates that the data point does not expire.

  • CHUNK_SIZE: the number of data points that can be stored in a chunk. Default value: 256. Valid values: 1 to 256.

  • UNCOMPRESSED: specifies that compression is disabled for the skey. This parameter is left empty by default, which indicates that compression is enabled for the skey.

  • LABELS: the labels of the skey. You can specify one or more label-value pairs. Example: LABELS sensor_id 1.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Run the EXTS.S.ADD foo temperature 1644310456 30.0 command in advance.

Sample command:

EXTS.S.RAW_INCRBY foo temperature 1644310456 3.3

Sample output:

OK

If the EXTS.S.GET foo temperature command is run at this time, the following output is returned:

1) (integer) 1644310456
2) "33.3"

EXTS.S.RAW_MINCRBY

Item

Description

Syntax

EXTS.S.RAW_MINCRBY Pkey keynumber Skey ts value [Skey ts value ...] [DATA_ET time] [CHUNK_SIZE size] [UNCOMPRESSED] [LABELS label1 val1 ...]

Time complexity

O(n), where n indicates the number of skeys.

Command description

Modifies the value of a data point in multiple skeys at a time. You can specify an increment or a decrement by which to modify the values. If the pkey or an skey does not exist, the pkey or skey is automatically created. The parameters for an skey, such as the expiration time and whether to enable compression, take effect only if the skey is automatically created.

Parameter

  • Pkey: the name of the pkey that you want to manage by running this command.

  • keynumber: the number of skeys.

  • Skey: the name of the skey.

  • ts: the UNIX timestamp of the data point whose value you want to update. Unit: milliseconds.

  • value: the value that you want to add to the data point value. The value can be negative. In this case, the value is subtracted from the data point value. The value must be a double-precision floating-point number.

  • DATA_ET time: the relative expiration time of the data point. Unit: milliseconds. This parameter is left empty by default, which indicates that the data point does not expire.

  • CHUNK_SIZE: the number of data points that can be stored in a chunk. Default value: 256. Valid values: 1 to 256.

  • UNCOMPRESSED: specifies that compression is disabled for the skey. This parameter is left empty by default, which indicates that compression is enabled for the skey.

  • LABELS: the labels of the skey. You can specify one or more label-value pairs. Example: LABELS sensor_id 1.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

EXTS.S.RAW_MMODIFY foo 3 temperature 1644565954814 30.2 pressure 1644565954814 2.05 distance 1644565954814 0.5

Sample output:

1) OK
2) OK
3) OK

Index filtering syntax

Skeys can be filtered by label. The following syntax is used for filter conditions.

Note

When you specify a filter condition, you can use one or more of the following commands and you must use one of the EQ, CONTAINS, and LIST_MATCH logics.

Filter command

Description

Logic

L = V

The value of label L equals V.

EQ (equals)

L !=

The value of label L is not NULL, which indicates that the skey contains label L.

CONTAINS

L = (v1,v2,...)

The value of label L matches one of the values in the list, such as v1 or v2.

LIST_TMATCH

L != V

The value of label L does not equal V.

NOEQ (equals)

L =

The value of label L is NULL, which indicates that the skey does not contain label L.

NOCONTAINS

L != (v1,v2,...)

The value of label L does not match any of the values in the list, such as v1 or v2.

LIST_NOTMATCH

Aggregation syntax

In aggregate operations, data that exists in multiple time buckets is aggregated. The following aggregation types are supported:

  • MAX: returns the maximum value.

  • MIN: returns the minimum value.

  • AVG: returns the average value.

  • SUM: returns the sum of all values.

  • FIRST: returns the first value.

  • LAST: returns the last value.

  • RANGE: returns the range from the minimum value to the maximum value.

  • COUNT: returns the number of values.

  • STD.P: returns the population variance.

  • STD.S: returns the sample variance.

  • VAR.P: returns the population standard deviation.

  • VAR.S: returns the sample standard deviation.