This is an automated email from the ASF dual-hosted git repository. jackietien pushed a commit to branch iotdb in repository https://gitbox.apache.org/repos/asf/tsfile.git
commit c3cea4e69ce7ddef6aa082702af5cb5108345601 Author: Jialin Qiao <[email protected]> AuthorDate: Sun Jun 9 20:30:43 2024 +0800 update readme example (#99) --- java/tsfile/README-zh.md | 152 ++++++++++++++++++++--------------------------- java/tsfile/README.md | 147 ++++++++++++++++++++------------------------- 2 files changed, 129 insertions(+), 170 deletions(-) diff --git a/java/tsfile/README-zh.md b/java/tsfile/README-zh.md index 361578c5..6934a045 100644 --- a/java/tsfile/README-zh.md +++ b/java/tsfile/README-zh.md @@ -71,67 +71,45 @@ mvn install -P with-java -DskipTests ### TsFile Java API -#### 写入 TsFile -TsFile 可以通过以下三个步骤生成，完整的代码参见"写入 TsFile 示例"章节。 +#### 数据写入 -1. 注册元数据 (Schema) +数据写入主要通过 TsFileWriter 完成。 - 创建一个`Schema`类的实例。 - - `Schema`类保存的是一个映射关系，key 是一个 measurement 的名字，value 是 measurement schema. - - 下面是一系列接口： - - ```java +1. 创建 TsFileWriter - /** - * measurementID: 物理量的名称，通常是传感器的名称 - * type: 数据类型，现在支持六种类型：`BOOLEAN`, `INT32`, `INT64`, `FLOAT`, `DOUBLE`, `TEXT` - * encoding: 编码类型 - */ - public MeasurementSchema(String measurementId, TSDataType type, TSEncoding encoding) // 默认使用 LZ4 压缩算法 - - // 使用预定义的 measurement 列表初始化 Schema - public Schema(Map<String, MeasurementSchema> measurements) - - /** - * 构造 TsFileWriter 进行数据写入 - * file : 写入 TsFile 数据的文件 - * schema : 文件的 schemas - */ - public TsFileWriter(File file, Schema schema) throws IOException + ```java + File f = new File("test.tsfile"); + TsFileWriter tsFileWriter = new TsFileWriter(f); ``` -2. 使用 `TsFileWriter` 写入数据。 +2. 注册时间序列 + + ```java + List<MeasurementSchema> schema1 = new ArrayList<>(); + schemas.add(new MeasurementSchema("电压", TSDataType.FLOAT)); + schemas.add(new MeasurementSchema("电流", TSDataType.FLOAT)); + tsFileWriter.registerTimeseries(new Path("太阳能板1"), schema1); + + List<MeasurementSchema> schema2 = new ArrayList<>(); + schemas.add(new MeasurementSchema("电压", TSDataType.FLOAT)); + schemas.add(new MeasurementSchema("电流", TSDataType.FLOAT)); + schemas.add(new MeasurementSchema("风速", TSDataType.FLOAT)); + tsFileWriter.registerTimeseries(new Path("风机1"), schema2); + ``` + +3. 写入数据 ```java - /** - * 使用接口创建一个新的`TSRecord`（时间戳和设备） - */ - public TSRecord(long timestamp, String deviceId) - - /** - * 创建一个`DataPoint`（度量 (measurement) 和值的对应），并使用 addTuple 方法将数据 DataPoint 添加正确的值到 TsRecord。 - */ - for (IMeasurementSchema schema : schemas) { - tsRecord.addTuple( - DataPoint.getDataPoint( - schema.getType(), - schema.getMeasurementId(), - Objects.requireNonNull(DataGenerator.generate(schema.getType(), (int) startValue)) - .toString())); - startValue++; - } - /** - * 写入数据 - */ - public void write(TSRecord record) throws IOException, WriteProcessException - ``` + TSRecord tsRecord = new TSRecord(1, "太阳能板1"); + tsRecord.addTuple(DataPoint.getDataPoint(TSDataType.FLOAT, "电压", 1.1f)); + tsRecord.addTuple(DataPoint.getDataPoint(TSDataType.FLOAT, "电流", 2.2f)); + tsFileWriter.write(tsRecord); + ``` -3. 调用`close`方法来关闭文件，关闭后才能进行查询。 +4. 调用`close`方法来关闭文件，关闭后才能进行查询。 ```java - public void close() throws IOException + tsFileWriter.close(); ``` 写入 TsFile 完整示例 @@ -141,45 +119,45 @@ TsFile 可以通过以下三个步骤生成，完整的代码参见"写入 TsFil [构造 Tablet 来写入数据](../examples/src/main/java/org/apache/tsfile/TsFileWriteAlignedWithTablet.java)。 -#### 读取 TsFile - -* 构造查询条件 -```java -/** - * 构造待读取的时间序列 - * 时间序列由 deviceId.measurementId 的格式组成（deviceId内可以有.） - */ -List<Path> paths = new ArrayList<Path>(); -paths.add(new Path("device_1.sensor_1")); -paths.add(new Path("device_1.sensor_3")); - -/** - * 构造一个时间范围过滤条件 - */ -IExpression timeFilterExpr = BinaryExpression.and( - new GlobalTimeExpression(TimeFilter.gtEq(15L)), - new GlobalTimeExpression(TimeFilter.lt(25L))); // 15 <= time < 25 - -/** - * 构造完整的查询表达式 - */ -QueryExpression queryExpression = QueryExpression.create(paths, timeFilterExpr); -``` +#### 数据查询 -* 读取数据 +数据查询主要通过 TsFileReader 完成。 -```java -/** - * 根据文件路径`filePath`构造一个`ReadOnlyTsFile`实例。 - */ -TsFileSequenceReader reader = new TsFileSequenceReader(filePath); -ReadOnlyTsFile readTsFile = new ReadOnlyTsFile(reader); +1. 创建 TsFileReader -/** - * 查询数据 - */ -public QueryDataSet query(QueryExpression queryExpression) throws IOException -``` + ```java + TsFileSequenceReader reader = new TsFileSequenceReader(path); + TsFileReader tsFileReader = new TsFileReader(reader)； + ``` + +2. 构造查询条件 + + ```java + ArrayList<Path> paths = new ArrayList<>(); + paths.add(new Path("太阳能板1", "电压")); + paths.add(new Path("太阳能板1", "电流")); + + IExpression timeFilter = BinaryExpression.and( + new GlobalTimeExpression(TimeFilterApi.gtEq(1L)), + new GlobalTimeExpression(TimeFilterApi.ltEq(10L))); + + QueryExpression queryExpression = QueryExpression.create(paths, timeFilter); + ``` + +3. 查询数据 + + ```java + QueryDataSet queryDataSet = readTsFile.query(queryExpression); + while (queryDataSet.hasNext()) { + queryDataSet.next(); + } + ``` + +4. 关闭文件 + + ```java + tsFileReader.close(); + ``` 读取 TsFile 完整示例 diff --git a/java/tsfile/README.md b/java/tsfile/README.md index ad638120..a285d1a5 100644 --- a/java/tsfile/README.md +++ b/java/tsfile/README.md @@ -70,67 +70,46 @@ The current release version is `1.0.0` ### TsFile Java API -#### Write TsFile -TsFile can be generated through the following three steps, and the complete code can be found in the "Write TsFile Example" section. +#### Write Data -1. Register Schema +Data written is through TsFileWriter. - you can make an instance of class `Schema` first and pass this to the constructor of class `TsFileWriter` - - The class `Schema` contains a map whose key is the name of one measurement schema, and the value is the schema itself. +1. Construct TsFileWriter - Here are the interfaces: - + ```java - - /** - * measurementID: The name of this measurement, typically the name of the sensor - * type: The data type, now support six types: `BOOLEAN`, `INT32`, `INT64`, `FLOAT`, `DOUBLE`, `TEXT` - * encoding: The data encoding - */ - public MeasurementSchema(String measurementId, TSDataType type, TSEncoding encoding) // default use LZ4 Compression - - // Initialize the schema using a predefined measurement list - public Schema(Map<String, MeasurementSchema> measurements) - - /** - * construct TsFileWriter for write - * file : The TsFile to write - * schema : The file schemas - */ - public TsFileWriter(File file, Schema schema) throws IOException + File f = new File("test.tsfile"); + TsFileWriter tsFileWriter = new TsFileWriter(f); ``` -2. use `TsFileWriter` write data. +2. Register timeseries ```java - /** - * Use this interface to create a new `TSRecord`(a timestamp and device pair) - */ - public TSRecord(long timestamp, String deviceId) - - /** - * Then create a `DataPoint`(a measurement and value pair), and use the addTuple method to add the DataPoint to the correct TsRecord. - */ - for (IMeasurementSchema schema : schemas) { - tsRecord.addTuple( - DataPoint.getDataPoint( - schema.getType(), - schema.getMeasurementId(), - Objects.requireNonNull(DataGenerator.generate(schema.getType(), (int) startValue)) - .toString())); - startValue++; - } - /** - * write data - */ - public void write(TSRecord record) throws IOException, WriteProcessException + List<MeasurementSchema> schema1 = new ArrayList<>(); + schemas.add(new MeasurementSchema("voltage", TSDataType.FLOAT)); + schemas.add(new MeasurementSchema("electricity", TSDataType.FLOAT)); + tsFileWriter.registerTimeseries(new Path("solarpanel1"), schema1); + + List<MeasurementSchema> schema2 = new ArrayList<>(); + schemas.add(new MeasurementSchema("voltage", TSDataType.FLOAT)); + schemas.add(new MeasurementSchema("electricity", TSDataType.FLOAT)); + schemas.add(new MeasurementSchema("windspeed", TSDataType.FLOAT)); + tsFileWriter.registerTimeseries(new Path("turbine1"), schema2); ``` -3. call `close` to finish this writing process，Query can only be performed after close. +3. Write data ```java - public void close() throws IOException + TSRecord tsRecord = new TSRecord(1, "solarpanel1"); + tsRecord.addTuple(DataPoint.getDataPoint(TSDataType.FLOAT, "voltage", 1.1f)); + tsRecord.addTuple(DataPoint.getDataPoint(TSDataType.FLOAT, "electricity", 2.2f)); + tsFileWriter.write(tsRecord); + ``` + +4. Close TsFileWriter, only closed TsFile could be queried. + + ```java + tsFileWriter.close(); ``` Write TsFile Example @@ -142,43 +121,45 @@ Write TsFile Example #### Read TsFile -* Construct Query Expression -```java -/** - * Construct a time series to be read - * The time series is composed of the format deviceId.measurementId (there can be.) - */ -List<Path> paths = new ArrayList<Path>(); -paths.add(new Path("device_1.sensor_1")); -paths.add(new Path("device_1.sensor_3")); - -/** - * Construct Time Filter - */ -IExpression timeFilterExpr = BinaryExpression.and( - new GlobalTimeExpression(TimeFilter.gtEq(15L)), - new GlobalTimeExpression(TimeFilter.lt(25L))); // 15 <= time < 25 - -/** - * Construct Full Query Expression - */ -QueryExpression queryExpression = QueryExpression.create(paths, timeFilterExpr); -``` +Data query is through TsFileReader. -* Read Data +1. Construct TsFileReader + + ```java + TsFileSequenceReader reader = new TsFileSequenceReader(path); + TsFileReader tsFileReader = new TsFileReader(reader)； + ``` + +2. Construct query expression, including predicate and filter + + ```java + ArrayList<Path> paths = new ArrayList<>(); + paths.add(new Path("solarpanel1", "voltage")); + paths.add(new Path("solarpanel1", "electricity")); + + IExpression timeFilter = BinaryExpression.and( + new GlobalTimeExpression(TimeFilterApi.gtEq(1L)), + new GlobalTimeExpression(TimeFilterApi.ltEq(10L))); + + QueryExpression queryExpression = QueryExpression.create(paths, timeFilter); + ``` + +3. Query data + + ```java + QueryDataSet queryDataSet = readTsFile.query(queryExpression); + while (queryDataSet.hasNext()) { + queryDataSet.next(); + } + ``` + +4. Close TsFileReader + + ```java + tsFileReader.close(); + ``` -```java -/** - * Construct an instance of 'ReadOnlyTsFile' based on the file path 'filePath'. - */ -TsFileSequenceReader reader = new TsFileSequenceReader(filePath); -ReadOnlyTsFile readTsFile = new ReadOnlyTsFile(reader); -/** - * Query Data - */ -public QueryDataSet query(QueryExpression queryExpression) throws IOException -``` Read TsFile Example
