Supplement documentation related to TagFilter

src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md

@@ -278,6 +278,23 @@ class TsFileReader {
     int query(const std::string &table_name,
               const std::vector<std::string> &columns_names, int64_t start_time,
               int64_t end_time, ResultSet *&result_set);
+
+    /**
+     * @brief query the tsfile by the table name, columns names, start time
+     * and end time, tag filter. this method is used to query the tsfile by the
+     * table model.
+     *
+     * @param [in] table_name the table name
+     * @param [in] columns_names the columns names
+     * @param [in] start_time the start time
+     * @param [in] end_time the end time
+     * @param [in] tag_filter the tag filter
+     * @param [out] result_set the result set
+     */
+    int query(const std::string& table_name,
+              const std::vector<std::string>& columns_names, int64_t start_time,
+              int64_t end_time, ResultSet*& result_set, Filter* tag_filter);
+
     /**
      * @brief destroy the result set, this method should be called after the
      * query is finished and result_set
@@ -440,4 +457,32 @@ class ResultSetMetadata {
      */
     uint32_t get_column_count();
 };
+```
+### Filter
+#### TagFilterBuilder
+Used to construct tag-based filters for querying data
+```cpp
+class TagFilterBuilder {
+   public:
+    explicit TagFilterBuilder(TableSchema* schema);
+
+    Filter* eq(const std::string& columnName, const std::string& value);
+    Filter* neq(const std::string& columnName, const std::string& value);
+    Filter* lt(const std::string& columnName, const std::string& value);
+    Filter* lteq(const std::string& columnName, const std::string& value);
+    Filter* gt(const std::string& columnName, const std::string& value);
+    Filter* gteq(const std::string& columnName, const std::string& value);
+    Filter* reg_exp(const std::string& columnName, const std::string& value);
+    Filter* not_reg_exp(const std::string& columnName,
+                        const std::string& value);
+    Filter* between_and(const std::string& columnName, const std::string& lower,
+                        const std::string& upper);
+    Filter* not_between_and(const std::string& columnName,
+                            const std::string& lower, const std::string& upper);
+
+    // Logical operations
+    static Filter* and_filter(Filter* left, Filter* right);
+    static Filter* or_filter(Filter* left, Filter* right);
+    static Filter* not_filter(Filter* filter);
+};
 ```

src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md

@@ -160,6 +160,9 @@ Used to query data in tsfile
 interface ITsFileReader extends AutoCloseable {
   // Used to execute queries and return results
   ResultSet query(String tableName, List<String> columnNames, long startTime, long endTime);
+
+  // Used to execute queries and return results
+  ResultSet query(String tableName, List<String> columnNames, long startTime, long endTime, Filter tagFilter);
 
   // Return the schema of the table named tableName in tsfile
   Optional<TableSchema> getTableSchemas(String tableName);
@@ -238,3 +241,57 @@ interface ResultSetMetadata {
   TSDataType getColumnType(int columnIndex);
 }
 ```
+### Filter
+#### TagFilterBuilder
+Used to construct tag-based filters for querying data
+```java
+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);
+}
+```

src/UserGuide/develop/QuickStart/QuickStart-C.md

@@ -50,7 +50,27 @@ Windows:
 ```shell
 mvnw.cmd clean install -P with-cpp -DskipTests
 ```
+### Compilation Options
+TsFile provides build options to control the size of the generated library:
+```shell
+# Minimal build
+mvn clean install -P with-cpp -DskipTests \
+  -Dbuild.test=OFF    \
+  -Denable.snappy=OFF \
+  -Denable.lz4=OFF    \
+  -Denable.lzokay=OFF \
+  -Denable.zlib=OFF   \
+  -Denable.antlr4=OFF
+```
+
+**Option Descriptions**
+- `enable.*=OFF:` Do not compile compression algorithms (reduces library size)
+- `enable.antlr4=OFF:` Do not compile ANTLR4 dependency (reduces library size)
 
+**Library Size Comparison**
+- `Full build:` ~3.2MB
+- `With ANTLR4 disabled:` ~1.9MB
+- `With all compression algorithms disabled:` ~1.7MB
 ### Directory Structure
 
 • **Include Directory**: Located at `tsfile/cpp/target/build/include/cwrapper`, it contains header files for integration. Add this path to the compiler's include path (e.g., using `-I` flag).

src/UserGuide/develop/QuickStart/QuickStart-CPP.md

@@ -41,7 +41,27 @@ mvn clean install -P with-cpp -DskipTests
 ```
 
 Note: If Maven is not installed, you can use mvnw on Linux or mvnw.cmd on Windows.
+### Compilation Options
+TsFile provides build options to control the size of the generated library:
+```shell
+# Minimal build
+mvn clean install -P with-cpp -DskipTests \
+  -Dbuild.test=OFF    \
+  -Denable.snappy=OFF \
+  -Denable.lz4=OFF    \
+  -Denable.lzokay=OFF \
+  -Denable.zlib=OFF   \
+  -Denable.antlr4=OFF
+```
+
+**Option Descriptions**
+- `enable.*=OFF:` Do not compile compression algorithms (reduces library size)
+- `enable.antlr4=OFF:` Do not compile ANTLR4 dependency (reduces library size)
 
+**Library Size Comparison**
+- `Full build:` ~3.2MB
+- `With ANTLR4 disabled:` ~1.9MB
+- `With all compression algorithms disabled:` ~1.7MB
 ### Directory Structure
 
 • **Include Directory**: Located at `tsfile/cpp/target/build/include`, it contains header files for integration. Add this path to the compiler's include path (e.g., using `-I` flag).
@@ -152,8 +172,12 @@ The sample code of using these interfaces is in <https://github.com/apache/tsfil
     columns.emplace_back("id2");
     columns.emplace_back("s1");
 
+    auto table_schema = reader.get_table_schema(table_name);
+    storage::Filter* tag_filter1 = storage::TagFilterBuilder(table_schema.get()).eq("id1", "id1_filed_1");
+    storage::Filter* tag_filter2 = storage::TagFilterBuilder(table_schema.get()).eq("id2", "id1_filed_2");
+    storage::Filter* tag_filter = storage::TagFilterBuilder(table_schema.get()).and_filter(tag_filter1, tag_filter2);
     // Column vector contains the columns you want to select.
-    reader.query(table_name, columns, 0, 100, temp_ret);
+    reader.query(table_name, columns, 0, 100, temp_ret, tag_filter);
 ```
 
 ### Query Data

src/UserGuide/develop/QuickStart/QuickStart-JAVA.md

@@ -129,7 +129,10 @@ ITsFileReader reader =
 ### Construct Query Request
 
 ```shell
-ResultSet resultSet = reader.query(tableName, Arrays.asList("id1", "id2", "s1", "s2"), 2, 8)
+TableSchema schema = reader.getTableSchemas(tableName);
+TagFilterBuilder filterBuilder = new TagFilterBuilder(schema);
+ResultSet resultSet = reader.query(tableName, Arrays.asList("id1", "id2", "s1", "s2"), 
+    2, 8, filterBuilder.eq("id1", "id1_filed_1"));
 ```
 
 ### Query Data

src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md

@@ -278,6 +278,23 @@ class TsFileReader {
     int query(const std::string &table_name,
               const std::vector<std::string> &columns_names, int64_t start_time,
               int64_t end_time, ResultSet *&result_set);
+
+    /**
+     * @brief query the tsfile by the table name, columns names, start time
+     * and end time, tag filter. this method is used to query the tsfile by the
+     * table model.
+     *
+     * @param [in] table_name the table name
+     * @param [in] columns_names the columns names
+     * @param [in] start_time the start time
+     * @param [in] end_time the end time
+     * @param [in] tag_filter the tag filter
+     * @param [out] result_set the result set
+     */
+    int query(const std::string& table_name,
+              const std::vector<std::string>& columns_names, int64_t start_time,
+              int64_t end_time, ResultSet*& result_set, Filter* tag_filter);
+
     /**
      * @brief destroy the result set, this method should be called after the
      * query is finished and result_set
@@ -440,4 +457,32 @@ class ResultSetMetadata {
      */
     uint32_t get_column_count();
 };
+```
+### Filter
+#### TagFilterBuilder
+Used to construct tag-based filters for querying data
+```cpp
+class TagFilterBuilder {
+   public:
+    explicit TagFilterBuilder(TableSchema* schema);
+
+    Filter* eq(const std::string& columnName, const std::string& value);
+    Filter* neq(const std::string& columnName, const std::string& value);
+    Filter* lt(const std::string& columnName, const std::string& value);
+    Filter* lteq(const std::string& columnName, const std::string& value);
+    Filter* gt(const std::string& columnName, const std::string& value);
+    Filter* gteq(const std::string& columnName, const std::string& value);
+    Filter* reg_exp(const std::string& columnName, const std::string& value);
+    Filter* not_reg_exp(const std::string& columnName,
+                        const std::string& value);
+    Filter* between_and(const std::string& columnName, const std::string& lower,
+                        const std::string& upper);
+    Filter* not_between_and(const std::string& columnName,
+                            const std::string& lower, const std::string& upper);
+
+    // Logical operations
+    static Filter* and_filter(Filter* left, Filter* right);
+    static Filter* or_filter(Filter* left, Filter* right);
+    static Filter* not_filter(Filter* filter);
+};
 ```

src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-Java.md

@@ -160,6 +160,9 @@ Used to query data in tsfile
 interface ITsFileReader extends AutoCloseable {
   // Used to execute queries and return results
   ResultSet query(String tableName, List<String> columnNames, long startTime, long endTime);
+
+  // Used to execute queries and return results
+  ResultSet query(String tableName, List<String> columnNames, long startTime, long endTime, Filter tagFilter);
 
   // Return the schema of the table named tableName in tsfile
   Optional<TableSchema> getTableSchemas(String tableName);
@@ -238,3 +241,57 @@ interface ResultSetMetadata {
   TSDataType getColumnType(int columnIndex);
 }
 ```
+### Filter
+#### TagFilterBuilder
+Used to construct tag-based filters for querying data
+```java
+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);
+}
+```

src/UserGuide/latest/QuickStart/QuickStart-C.md

@@ -50,7 +50,27 @@ Windows:
 ```shell
 mvnw.cmd clean install -P with-cpp -DskipTests
 ```
+### Compilation Options
+TsFile provides build options to control the size of the generated library:
+```shell
+# Minimal build
+mvn clean install -P with-cpp -DskipTests \
+  -Dbuild.test=OFF    \
+  -Denable.snappy=OFF \
+  -Denable.lz4=OFF    \
+  -Denable.lzokay=OFF \
+  -Denable.zlib=OFF   \
+  -Denable.antlr4=OFF
+```
+
+**Option Descriptions**
+- `enable.*=OFF:` Do not compile compression algorithms (reduces library size)
+- `enable.antlr4=OFF:` Do not compile ANTLR4 dependency (reduces library size)
 
+**Library Size Comparison**
+- `Full build:` ~3.2MB
+- `With ANTLR4 disabled:` ~1.9MB
+- `With all compression algorithms disabled:` ~1.7MB
 ### Directory Structure
 
 • **Include Directory**: Located at `tsfile/cpp/target/build/include/cwrapper`, it contains header files for integration. Add this path to the compiler's include path (e.g., using `-I` flag).