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

一、数据模型

1、 一元时间序列

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

一元时间序列指的是在同一个时间戳，仅有一个物理量采样，形成的一条时间序列。

2、多元时间序列

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

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

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

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

3、“设备”的定义

设备指的是在实际场景中拥有物理量的装置，即序列（一元/多元）的上一层，即IoTDB概念中的实体（Entity）。

二、应用场景

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

// 创建一元时间序列的完整语句（v0.12及之前）
create timeseries root.turbine.d1.s2
with datatype=FLOAT,
  encoding=RLE,
  compression=SNAPPY,
  tags(tag1=v1, tag2=v2),
  attributes(attr1=v1, attr2=v2)


// v0.13之后，创建语句的新语法，示例：
create timeseries root.sg.d3.s1 FLOAT [encoding=RLE] [compression=SNAPPY] [tags(tag1=v1, tag2=v2)] [attributes(attr1=v1, attr2=v2)]
create timeseries root.sg.d3.s2 FLOAT [encoding=RLE] [compression=SNAPPY] [tags(tag1=v1, tag2=v2)] [attributes(attr1=v1, attr2=v2)] 


// 插入语句
insert into root.sg.d3(time, s1) values(1,1)
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] , s4 INT32 [encoding=Grollia] [compression=SNAPPY/GZIP/LZ4/UNCOMPRESSED] ) [compression=SNAPPY]

小括号内未制定compression的列，则采用系统默认配置；
小括号外的compression定义时间列压缩方式和未显式声明的列的压缩方式。


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

注意：场景2所创建的多元时间序列所属实体可以扩充一元或多元物理量。

例如，可以向d1下继续添加一元时间序列，为d1 扩充 d1.c 序列：

create timeseries root.sg1.d1.c FLOAT

场景3：（场景2的特例）一个物理设备仅有一个多元序列，可省略多元序列名字

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

// 插入语句
insert into root.sg.d1(time, (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.sg

注意：场景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);

Tablet支持某列的某一行是null？（单元、多元保持统一）