Apache IoTDB Session (0.13) 写入接口介绍

Apache IoTDB 提供多种原生写入接口，包括单设备单行写入 (insertRecord)、多设备多行同时写入 (insertRecords)、单设备多行同时写入(insertRecordsOfOneDevice 与 insertTablet)，用户可根据自己的写入场景和写入负载灵活选择不同的写入接口

写入的基本接口

insertRecord 接口

void insertRecord(String deviceId, long time, List<String> measurements, List<TSDataType> types, List<Object> values)

• 使用场景：插入单设备的单行数据，即某时间点下某设备的多个测点的数据
• 参数介绍
  • deviceId：设备 id
  • time：时间戳
  • measurements：测点列表
  • types：各测点对应的数据类型
  • values：各测点在该时间点下对应的数据

insertRecords 接口

void insertRecords(List<String> deviceIds, List<Long> times, List<List<String>> measurementsList, List<List<TSDataType>> typesList, List<List<Object>> valuesList)

• 使用场景：批量插入多设备的多行数据，类似于 jdbc executeBatch，通过批量打包一些插入请求来减少网络开销
• 参数介绍
  • deviceIds：设备 id 列表
  • times：时间戳列表
  • measurementsList：各设备的测点列表
  • typesList：各设备下各测点对应的数据类型
  • valuesList：各设备下各测点在该时间点下对应的数据

insertRecordsOfOneDevice 接口

void insertRecordsOfOneDevice(String deviceId, List<Long> times, List<List<String>> measurementsList, List<List<TSDataType>> typesList, List<List<Object>> valuesList)

• 使用场景：批量插入单设备的多行数据，网络开销小且写入并发度更高
• 参数介绍
  • deviceId：设备 id
  • times：时间戳列表
  • measurementsList：各设备的测点列表
  • typesList：各设备下各测点对应的数据类型
  • valuesList：各设备下各测点在该时间点下对应的数据
• insertRecordsOfOneDevice vs. insertRecords
  • insertRecords 能包含多个设备的数据，insertRecordsOfOneDevice只能包含一个设备的数据
  • insertRecordsOfOneDevice 的写入效率比 insertRecords 高

insertTablet 接口

void insertTablet(Tablet tablet)

public class Tablet {
  /** deviceId of this tablet */
  public String prefixPath;
  /** the list of measurement schemas for creating the tablet */
  private List<MeasurementSchema> schemas;
  /** timestamps in this tablet */
  public long[] timestamps;
  /** each object is a primitive type array, which represents values of one measurement */
  public Object[] values;
  /** each bitmap represents the existence of each value in the current column. */
  public BitMap[] bitMaps;
  /** the number of rows to include in this tablet */
  public int rowSize;
  /** the maximum number of rows for this tablet */
  private int maxRowNumber;
  /** whether this tablet store data of aligned timeseries or not */
  private boolean isAligned;
}

• 使用场景：批量插入单设备的多行数据，数据需按时间对齐，网络开销较 insertRecordsOfOneDevice 更小

• 参数介绍：关键数据结构 Tablet 类

  • prefixPath：设备 id
  • schemas：测点的 schema 信息
  • timestamps：时间戳列表
  • values：各测点的数据列表，
  • bitMaps：各测点数据列表对应的 BitMap，用于标记空值
  • rowSize：数据行数
  • maxRowNumber：最大数据行数
  • isAligned：是否为对齐时间序列

• insertTablet vs. insertRecordsOfOneDevice

  • 两者均只能包含一个设备的数据
  • insertTablet 的写入效率比 insertRecordsOfOneDevice 高
  • insertTablet 的网络带宽占用比 insertRecordsOfOneDevice 小

insertTablets 接口

void insertTablets(Map<String, Tablet> tablets)

• 使用场景：批量插入多设备的多行数据
• 参数介绍
  • tablets：设备 id 和 Tablet 组成的散列表

带有类型推断的写入接口

类型推断是自动创建元数据的一部分。当数据均是 String 类型时，我们可以使用如下接口，根据 value 的值进行类型推断。例如：value 为 “true” ，就可以自动推断为布尔类型。value 为 “3.2” ，就可以自动推断为数值类型。服务器需要做类型推断，可能会有额外耗时，速度较无需类型推断的写入慢。

insertRecord 接口

void insertRecord(String deviceId, long time, List<String> measurements, List<String> values)

• 使用场景：插入单设备的单行数据且是未知的数据类型需要进行数据类型推断
• 参数介绍
  • deviceId：设备 id
  • time：时间戳
  • measurements：测点列表
  • values：各测点在该时间点下对应的数据

insertRecords 接口

void insertRecords(List<String> deviceIds, List<Long> times, List<List<String>> measurementsList, List<List<String>> valuesList)

• 使用场景：批量插入多设备的多行数据且是未知的数据类型需要进行数据类型推断
• 参数介绍
  • deviceIds：设备 id 列表
  • times：时间戳列表
  • measurementsList：各设备的测点列表
  • valuesList：各设备下各测点在该时间点下对应的数据

insertStringRecordsOfOneDevice 接口

void insertStringRecordsOfOneDevice(String deviceId, List<Long> times, List<List<String>> measurementsList, List<List<String>> valuesList)

• 使用场景：批量插入单设备的多行数据且是未知的数据类型需要进行数据类型推断
• 参数介绍
  • deviceId：设备 id
  • times：时间戳列表
  • measurementsList：各设备的测点列表
  • valuesList：各设备下各测点在该时间点下对应的数据

对齐时间序列的写入接口

对齐时间序列的写入使用 insertAlignedXXX 接口，其余与上述接口类似：

• insertAlignedRecord
• insertAlignedRecords
• insertAlignedRecordsOfOneDevice
• insertAlignedStringRecordsOfOneDevice
• insertAlignedTablet
• insertAlignedTablets