一元/多元时间序列用户手册

一、数据模型

1、 一元时间序列

时间序列是IoTDB中的核心概念。时间序列可以被看作产生时序数据的传感器的所在完整路径，在IoTDB中所有的时间序列必须以root开始、以传感器作为结尾。一个时间序列也可称为一个全路径。

一元时间序列指的是在同一个时间戳，仅有一个传感器采样，形成的一条时间序列。

2、多元时间序列

在同一个时间戳有多个传感器同时采样，会形成具有相同时间戳的多条时间序列，在 IoTDB 中，这些时间序列成为多元时间序列（学术界的定义为：即包含多个一元时间序列作为分量， 各个一元时间序列的采样时间点相同）

创建多元时间序列时，可以使用关键字 aligned 显式指明。

多元时间序列可以被同时创建，同时插入值，删除时也必须同时删除。不过在查询的时候，可以对于每一个传感器单独查询。

通过使用多元时间序列，在插入数据时，多元序列的时间戳列在内存和磁盘中仅需存储一次，而不是时间序列的条数次。

3、“设备”的定义

设备指的是在实际场景中拥有传感器的装置，即序列（一元/多元）的上一层。

二、应用场景

场景1：一个物理设备具有多个一元序列

// 创建时间序列语句
create timeseries root.turbine.d1.s2(temperature2)
with datatype=FLOAT,
  encoding=RLE,
  compression=SNAPPY
  tags(tag1=v1, tag2=v2)
  attributes(attr1=v1, attr2=v2)


// 创建语句(新语法，后续修改)
create timeseries root.sg.d3.s1 FLOAT 
create timeseries root.sg.d3.s2 FLOAT


// 插入语句
insert into root.sg.d3(time, s1, s2) values(1,1,2

场景2：一个物理设备具有一个多元序列

// 注意：多元的时间序列的压缩方式必须相同
create [aligned] timeseries root.sg1.d1.电表(s1 FLOAT, s2 INT32)


// 可以指定多元时间序列的编码(encoding)和压缩方式(compression)
// 但是暂不支持指定别名(alias)，props, attributes, tags 等
create [aligned] timeseries root.sg1.d1.b(
    s3 FLOAT [encoding=RLE] [compression=SNAPPY],
    s4 INT32 [encoding=Grollia] [compression=SNAPPY]
) compression=SNAPPY

注意：场景2所创建的多元时间序列是可以扩充的。例如，可以向d1下继续添加其他的一元或多元时间序列，将 d1 扩充 d1.c 元序列：

create timeseries root.sg1.d1.c FLOAT

场景3：一个物理设备仅有一个多元序列

// 创建语句
create [aligned] timeseries root.sg.d1(s1 FLOAT, s2 INT32)


// 插入语句
insert into root.sg(time, d1(s1, s2)) values(1,(1,2))

注意：按照场景3的方式创建多元时间序列后，不能进行进一步扩充。

场景4：一个物理设备具有多个多元序列

// 创建语句
create [aligned] timeseries root.sg.d3.陀螺仪(s1 FLOAT, s2 INT32)
create [aligned] timeseries root.sg.d3.GPS(s3 FLOAT, s4 INT32)


// 插入语句
insert into root.sg.d3(time, 陀螺仪(s1, s2), GPS(s3, s4)) values(1, (1, 2),(3,4))
insert into root.sg.d3(time, 陀螺仪(s1, s2)) values(1, (1, 2))


// 查询语句
select s1,s2 from root.sg.d3.陀螺仪
select * from root.sg.d3.陀螺仪
select 陀螺仪.* from root.sg.d3
select 陀螺仪.s1 from root.sg.d3
select d3.* from root.s

注意：场景4所创建的多元时间序列是可以扩充的。例如，可以向d3下继续添加其他的一元或多元时间序列：

create timeseries root.sg.d3.s3 FLOAT

场景5：一个物理设备具有混合的多元序列和一元序列

// 创建语句
create [aligned] timeseries root.sg.d4.GPS(s3 FLOAT, s4 INT32)
create timeseries root.sg.d4.s5 FLOAT


// 插入语句
insert into root.sg.d3(time, GPS(s3, s4), s5) values(1, (3,4), 5)

三、Session API

注意：以下仅展示本次新增的 session API，其他 API 与旧有 API 相同的不在此展示，如：查询语句（executeRawDataQuery）。

1、多元时间序列相关 API

// 创建多元时间序列
void createAlignedTimeseries(
    String prefixPath, // "root.sg.d1.陀螺仪"
    List<String> measurements,
    List<TSDataType> dataTypes,
    List<TSEncoding> encodings,
    CompressionType compressor,
    List<String> measurementAliasList
);

2、插入Record

一个 Record 是一个设备一个时间戳下多个测点的数据，例如：

insert into root.sg.d3(time, 陀螺仪(s1, s2)) values(1,(1,2))

API 如下：

// 服务器需要做类型推断，可能会有额外耗时
void insertAlignedRecord(String prefixPath, long time, List<String> measurements, List<String> values)


// 提供数据类型后，服务器不需要做类型推断，可以提高性能
void insertAlignedRecord(String prefixPath, long time, List<String> measurements, List<TSDataType> types, List<Object> values

应用到上面的例子即：

void insertAlignedRecord(
    "root.sg.d3.陀螺仪",
    1,
    Arrays.asList("s1", "s2"),
    Arrays.asList("1", "2")
)

注意：当前仅支持 record 插入一个多元时间序列。后期将适配如下 SQL（即在同一个 record 中涉及多个多元时间序列、或涉及混合的一元和多元时间序列）

insert into root.sg.d3(time, 陀螺仪(s1, s2), GPS(s3, s4)) values(1, (1, 2),(3,4))

3、插入Tablet

Tablet 是一个设备若干行非空数据块，每一行的列都相同

// 插入一个 Tablet
void insertTablet(Tablet tablet)


// 插入多个 Tablet
void insertTablets(Map<String, Tablet> tablet)

多元时间序列通过 VectorMeasurementSchema 构建 Tablet

List<IMeasurementSchema> schemaList = new ArrayList<>();
schemaList.add(
    new VectorMeasurementSchema(
        new String[] {"s1", "s2"}, new TSDataType[] {TSDataType.INT64, TSDataType.INT32}));


Tablet tablet = new Tablet("root.sg1.d1.GPS", schemaList);