Interface Definitions - Java

Write Interface

ITsFileWriter

Used to write data to tsfile

interface ITsFileWriter extends AutoCloseable {
  /**
   * Write one tablet into TsFile.
   *
   * @param tablet input tablet.
   */
  void write(Tablet tablet);
  
  /**
   * Close writer and flush buffered data.
   */
  void close();
}

TsFileWriterBuilder

Used to construct ITsFileWriter

class TsFileWriterBuilder {
  /**
   * Build writer instance from configured options.
   *
   * @return ITsFileWriter instance.
   */
  public ITsFileWriter build();
  
  /**
   * Set target file.
   *
   * @param file target file.
   * @return builder itself.
   */
  public TsFileWriterBuilder file(File file);
  
  /**
   * Set table schema.
   *
   * @param schema table schema.
   * @return builder itself.
   */
  public TsFileWriterBuilder tableSchema(TableSchema schema);
  
  /**
   * Set memory threshold for internal buffering.
   *
   * @param memoryThreshold threshold in bytes.
   * @return builder itself.
   */
  public TsFileWriterBuilder memoryThreshold(long memoryThreshold);
}

TableSchema

Describe the data structure of the table schema

class TableSchema {
  /**
   * Construct table schema.
   *
   * @param tableName table name.
   * @param columnSchemaList column schema list.
   */
  public TableSchema(String tableName, List<ColumnSchema> columnSchemaList);
}

class ColumnSchema {
  /**
   * Construct one column schema.
   *
   * @param columnName column name.
   * @param dataType column data type.
   * @param columnCategory column category.
   */
  public ColumnSchema(String columnName, TSDataType dataType, ColumnCategory columnCategory);
  
  /**
   * Get column name.
   *
   * @return column name.
   */
  public String getColumnName();
  
  /**
   * Get column data type.
   *
   * @return TSDataType.
   */
  public TSDataType getDataType();
  
  /**
   * Get column category.
   *
   * @return column category.
   */
  public Tablet.ColumnCategory getColumnCategory();
}

class ColumnSchemaBuilder {
  /**
   * Build ColumnSchema object.
   *
   * @return ColumnSchema instance.
   */
  public ColumnSchema build();
  
  /**
   * Set column name.
   *
   * @param columnName column name.
   * @return builder itself.
   */
  public ColumnSchemaBuilder name(String columnName);
  
  /**
   * Set column data type.
   *
   * @param columnType data type.
   * @return builder itself.
   */
  public ColumnSchemaBuilder dataType(TSDataType columnType);
  
  /**
   * Set column category.
   *
   * @param columnCategory column category.
   * @return builder itself.
   */
  public ColumnSchemaBuilder category(ColumnCategory columnCategory);
  
  // Supported types
  enum TSDataType {    
    BOOLEAN,    
    INT32,
    INT64,    
    FLOAT,    
    DOUBLE,    
    TIMESTAMP,   
    TEXT,    
    DATE,    
    BLOB,   
    STRING;  
  }
  
  // Supported column categories
  enum ColumnCategory {    
    TAG,   
    FIELD 
  }
}

Tablet

Write column memory structure

class Tablet {
  /**
   * Construct tablet with default row capacity.
   *
   * @param columnNameList column names.
   * @param dataTypeList column data types.
   */
  public Tablet(List<String> columnNameList, List<TSDataType> dataTypeList);
  /**
   * Construct tablet with explicit row capacity.
   *
   * @param columnNameList column names.
   * @param dataTypeList column data types.
   * @param maxRowNum max row count.
   */
  public Tablet(List<String> columnNameList, List<TSDataType> dataTypeList, int maxRowNum);
  
  /**
   * Set timestamp for one row.
   *
   * @param rowIndex target row index.
   * @param timestamp timestamp value.
   */
  void addTimestamp(int rowIndex, long timestamp);
  
  // Interface for adding values
  // Add values based on column names
  void addValue(int rowIndex, String columnName, int val);
  void addValue(int rowIndex, String columnName, long val);  
  void addValue(int rowIndex, String columnName, float val);  
  void addValue(int rowIndex, String columnName, double val);  
  void addValue(int rowIndex, String columnName, boolean val);  
  void addValue(int rowIndex, String columnName, String val);
  void addValue(int rowIndex, String columnName, byte[] val); 
  void addValue(int rowIndex, String columnName, LocalDate val); 
  // Add values based on index position
  void addValue(int rowIndex, int columnIndex, int val);
  void addValue(int rowIndex, int columnIndex, long val);  
  void addValue(int rowIndex, int columnIndex, float val);  
  void addValue(int rowIndex, int columnIndex, double val);  
  void addValue(int rowIndex, int columnIndex, boolean val); 
  void addValue(int rowIndex, int columnIndex, String val);
  void addValue(int rowIndex, int columnIndex, byte[] val); 
  void addValue(int rowIndex, int columnIndex, LocalDate val);
}

Read Interface

ITsFileReader

Used to query data in tsfile

interface ITsFileReader extends AutoCloseable {
  /**
   * Query table data in time range.
   *
   * @param tableName table name.
   * @param columnNames selected columns.
   * @param startTime start timestamp.
   * @param endTime end timestamp.
   * @return query result set.
   */
  ResultSet query(String tableName, List<String> columnNames, long startTime, long endTime);

  /**
   * Query table data in time range with tag filter.
   *
   * @param tableName table name.
   * @param columnNames selected columns.
   * @param startTime start timestamp.
   * @param endTime end timestamp.
   * @param tagFilter tag filter.
   * @return query result set.
   */
  ResultSet query(String tableName, List<String> columnNames, long startTime, long endTime, Filter tagFilter);
  
  /**
   * Get schema of one table.
   *
   * @param tableName table name.
   * @return optional table schema.
   */
  Optional<TableSchema> getTableSchemas(String tableName);
  
  /**
   * Get schemas of all tables.
   *
   * @return list of table schemas.
   */
  List<TableSchema> getAllTableSchema();
  
  /**
   * Close reader.
   */
  void close();
}

TsFileReaderBuilder

Used to construct ITsFileReader

class TsFileReaderBuilder {
  /**
   * Build reader instance.
   *
   * @return ITsFileReader instance.
   */
  public ITsFileReader build();
  
  /**
   * Set target file.
   *
   * @param file target tsfile.
   * @return builder itself.
   */
  public TsFileReaderBuilder file(File file);
}

ResultSet

The result set of the query

interface ResultSet extends AutoCloseable {  
  /**
   * Move to next row.
   *
   * @return true if next row exists.
   */
  boolean next();  
    
  // Get the value of the current row and a certain column
  int getInt(String columnName);  
  int getInt(int columnIndex);  
  long getLong(String columnName);  
  long getLong(int columnIndex);
  float getFloat(String columnName);
  float getFloat(int columnIndex); 
  double getDouble(String columnName);
  double getDouble(int columnIndex); 
  boolean getBoolean(String columnName);
  boolean getBoolean(int columnIndex);
  String getString(String columnName);
  String getString(int columnIndex);
  LocalDate getDate(String columnName);
  LocalDate getDate(int columnIndex); 
  byte[] getBinary(String columnName);
  byte[] getBinary(int columnIndex);
     
  /**
   * Check if current-row column is NULL.
   *
   * @param columnName column name.
   * @return true if null.
   */
  boolean isNull(String columnName);  
  /**
   * Check if current-row column is NULL.
   *
   * @param columnIndex 1-based column index.
   * @return true if null.
   */
  boolean isNull(int columnIndex);  
    
  /**
   * Close result set.
   */
  void close();
    
  /**
   * Get result-set metadata.
   *
   * @return ResultSetMetadata.
   */
  ResultSetMetadata getMetadata();
}

ResultSetMetadata

Used to obtain metadata for the result set

interface ResultSetMetadata {  
  /**
   * Get column name by index.
   *
   * @param columnIndex 1-based column index.
   * @return column name.
   */
  String getColumnName(int columnIndex);
  
  /**
   * Get column type by index.
   *
   * @param columnIndex 1-based column index.
   * @return TSDataType.
   */
  TSDataType getColumnType(int columnIndex);
}

Filter

TagFilterBuilder

Used to construct tag-based filters for querying data

class TagFilterBuilder {
  // Constructor function
  public TagFilterBuilder(TableSchema tableSchema);
  
  // Equal to filter
  public Filter eq(String columnName, Object value);
  
  // Not equal to filter
  public Filter neq(String columnName, Object value);
  
  // Less than filter
  public Filter lt(String columnName, Object value);
  
  // Less than or equal to filter
  public Filter lteq(String columnName, Object value);
  
  // Greater than filter
  public Filter gt(String columnName, Object value);
  
  // Greater than or equal to filter
  public Filter gteq(String columnName, Object value);
  
  // Between and filter (inclusive)
  public Filter betweenAnd(String columnName, Object value1, Object value2);
  
  // Not between and filter
  public Filter notBetweenAnd(String columnName, Object value1, Object value2);
  
  // Regular expression filter
  public Filter regExp(String columnName, String pattern);
  
  // Not regular expression filter
  public Filter notRegExp(String columnName, String pattern);
  
  // LIKE pattern filter
  public Filter like(String columnName, String pattern);
  
  // NOT LIKE pattern filter
  public Filter notLike(String columnName, String pattern);
  
  // Logical AND filter
  public Filter and(Filter left, Filter right);
  
  // Logical OR filter
  public Filter or(Filter left, Filter right);
  
  // Logical NOT filter
  public Filter not(Filter value);
}