TS.CREATE
TS.CREATE key [RETENTION retentionPeriod] [ENCODING <COMPRESSED|UNCOMPRESSED>] [CHUNK_SIZE size] [DUPLICATE_POLICY policy] [IGNORE ignoreMaxTimediff ignoreMaxValDiff] [LABELS [label value ...]]
- Available in:
- Redis Stack / TimeSeries 1.0.0
- Time complexity:
- O(1)
创建一个新的时间序列
必需的参数
key
是时间序列的键名。
- 如果键已经存在,你会收到一个Redis错误回复,
TSDB: key already exists
。你可以使用EXISTS
命令来检查键是否存在。 - 其他命令在调用时如果使用不存在的键也会创建新的时间序列,包括
TS.ADD
、TS.INCRBY
和TS.DECRBY
。
可选参数
RETENTION retentionPeriod
是与最高报告时间戳相比的样本最大年龄,以毫秒为单位。样本的过期仅基于其时间戳与后续使用此键的TS.ADD
、TS.MADD
、TS.INCRBY
和TS.DECRBY
调用传递的时间戳之间的差异。
当设置为0时,样本永不过期。如果未指定,该选项将设置为数据库的全局RETENTION_POLICY配置,默认值为0。
ENCODING enc
指定系列样本的编码格式为以下值之一:
COMPRESSED
,对序列样本应用压缩。UNCOMPRESSED
,将原始样本保存在内存中。添加此标志以保持数据未压缩的形式。
COMPRESSED
几乎总是正确的选择。压缩不仅节省内存,而且由于减少了内存访问次数,通常还能提高性能。它可以使内存减少约90%。例外情况是高度不规则的时间戳或值,这种情况很少发生。
当未指定时,选项设置为COMPRESSED
。
CHUNK_SIZE size
是每个新块数据部分的初始分配大小,以字节为单位。实际块可能会消耗更多内存。更改chunkSize(使用TS.ALTER
)不会影响现有块。
必须是范围 [48 .. 1048576] 内的8的倍数。如果未指定,则设置为数据库的全局 CHUNK_SIZE_BYTES 配置,默认值为4096(单个内存页)。
注意:在v1.6.10之前没有强制执行最小值。在v1.6.10到v1.6.17之间以及v1.8.0中,最小值为128。自v1.8.1以来,最小值为48。
每个键中的数据以块的形式存储。每个块包含给定时间段的头和数据。索引包含所有块。迭代在每个块内部进行。根据您的使用情况,考虑这些权衡以确定块的大小是更小还是更大:
- 插入性能:较小的块会导致插入速度变慢(需要创建更多的块)。
- 查询性能:当数据块非常大时,查询一小部分数据的性能较慢,因为我们需要遍历整个数据块来找到所需的数据。
- 当你有大量的键和每个键的样本很少时,较大的块可能会占用更多的内存,或者当每个键有很多样本时,可能会占用更少的内存。
如果您不确定您的使用场景,请选择默认选项。
DUPLICATE_POLICY policy
是处理具有相同时间戳的多个样本插入(TS.ADD
和 TS.MADD
)的策略,具有以下值之一:
BLOCK
: 忽略任何新报告的值并回复错误FIRST
: 忽略任何新报告的值LAST
: 使用新报告的值进行覆盖MIN
: 仅当值低于现有值时覆盖MAX
: 仅当值高于现有值时才覆盖SUM
: 如果存在先前的样本,将新样本添加到其中,使更新后的值等于(先前 + 新)。如果不存在先前的样本,则将更新后的值设置为新值。
当未指定时:设置为数据库的全局DUPLICATE_POLICY配置(默认情况下为BLOCK
)。
BLOCK
通常用于避免意外的更改。当可能存在重复报告时,FIRST
可以用作优化。当报告更新时,可以使用 LAST
。SUM
用于计数器(例如,当有多个报告计数设备时,每分钟进入停车场的汽车数量)。MIN
和 MAX
可以用于存储每分钟的最小/最大股票价格(而不是存储所有样本并定义压缩规则)。
IGNORE ignoreMaxTimediff ignoreMaxValDiff
是处理重复样本的策略。如果满足以下条件,新样本将被视为重复并被忽略:
- 时间序列不是压缩的;
- 时间序列的
DUPLICATE_POLICY
是LAST
; - 样本按顺序添加(
timestamp ≥ max_timestamp
); - 当前时间戳与前一个时间戳的差值(
timestamp - max_timestamp
)小于或等于IGNORE_MAX_TIME_DIFF
; - 当前值与上一个最大时间戳处的值的绝对差值(
abs(value - value_at_max_timestamp
)小于或等于IGNORE_MAX_VAL_DIFF
。
其中 max_timestamp
是时间序列中具有最大时间戳的样本的时间戳,而 value_at_max_timestamp
是 max_timestamp
处的值。
当未指定时:设置为全局的IGNORE_MAX_TIME_DIFF和IGNORE_MAX_VAL_DIFF,默认情况下,两者都设置为0。
LABELS {label value}...
是一组标签-值对,表示键的元数据标签,并作为二级索引。
TS.MGET
、TS.MRANGE
和 TS.MREVRANGE
命令基于标签对多个时间序列进行操作。TS.QUERYINDEX
命令返回所有基于标签匹配给定过滤器的时间序列键。
返回值
返回以下回复之一:
- Simple string reply -
OK
如果正确执行 - [] 出错时(无效参数,键已存在等)
示例
Create a temperature time series
127.0.0.1:6379> TS.CREATE temperature:2:32 RETENTION 60000 DUPLICATE_POLICY MAX LABELS sensor_id 2 area_id 32
OK
另请参阅
TS.ADD
| TS.INCRBY
| TS.DECRBY
| TS.MGET
| TS.MRANGE
| TS.MREVRANGE
| TS.QUERYINDEX