cpp/src/reader/tsfile_reader.h

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * License); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

#ifndef READER_TSFILE_READER_H
#define READER_TSFILE_READER_H

#include <memory>

#include "common/row_record.h"
#include "common/tsfile_common.h"
#include "expression.h"
#include "file/random_access_read_file.h"
#include "reader/prepared_series.h"
#include "reader/table_query_executor.h"
namespace storage {
class TsFileExecutor;
class ResultSet;
struct MeasurementSchema;
}  // namespace storage

namespace storage {

extern int libtsfile_init();
extern void libtsfile_destroy();
/**
 * @brief TsfileReader provides the ability to query all files with the suffix
 * .tsfile
 *
 * TsfileReader is designed to query .tsfile files, it accepts tree model
 * queries and table model queries, and supports querying metadata such as
 * TableSchema and TimeseriesSchema.
 */
class TsFileReader {
   public:
    TsFileReader();
    ~TsFileReader();
    TsFileReader(const TsFileReader&) = delete;
    TsFileReader& operator=(const TsFileReader&) = delete;
    TsFileReader(TsFileReader&& other) = delete;
    TsFileReader& operator=(TsFileReader&& other) = delete;
    /**
     * @brief open the tsfile
     *
     * @param file_path the path of the tsfile which will be opened
     * @return Returns 0 on success, or a non-zero error code on failure.
     */
    int open(const std::string& file_path);
    /**
     * @brief open an initialized random-access source
     *
     * The reader takes ownership of @p read_file.
     */
    int open(std::unique_ptr<RandomAccessReadFile> read_file);
    /**
     * @brief close the tsfile, this method should be called after the
     * query is finished
     *
     * @return Returns 0 on success, or a non-zero error code on failure.
     */
    int close();
    unsigned char get_file_version() const;
    /**
     * @brief query the tsfile by the query expression,Users can construct
     * their own query expressions to query tsfile
     *
     * @param [in] qe the query expression
     * @param [out] ret_qds the result set
     * @return Returns 0 on success, or a non-zero error code on failure.
     */
    int query(storage::QueryExpression* qe, ResultSet*& ret_qds);
    /**
     * @brief query the tsfile by the path list, start time and end time
     * this method is used to query the tsfile by the tree model.
     *
     * @param [in] path_list the path list
     * @param [in] start_time the start time
     * @param [in] end_time the end time
     * @param [out] result_set the result set
     */
    int query(std::vector<std::string>& path_list, 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. 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 [out] result_set the result set
     * @param [in] batch_size <= 0 means row-by-row return mode,
     *             > 0 means return TsBlock with the specified block size.
     */
    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, int batch_size = -1);

    /**
     * @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,
              int batch_size = 0);

    int query(const std::string& table_name,
              const std::vector<std::string>& columns_names, int64_t start_time,
              int64_t end_time, int offset, int limit, ResultSet*& result_set,
              Filter* tag_filter = nullptr, int batch_size = 0);

    /**
     * @brief Query tree-model time series by row with offset and limit.
     *
     * @param path_list  Full paths (device.measurement) to query.
     * @param offset     Number of leading rows to skip (>= 0).
     * @param limit      Maximum rows to return. < 0 means unlimited.
     * @param[out] result_set  The result set containing query results.
     * @return Returns 0 on success, or a non-zero error code on failure.
     */
    int queryByRow(std::vector<std::string>& path_list, int offset, int limit,
                   ResultSet*& result_set);

    int prepare_series(const FileGeneration& generation,
                       const PreparedLocator& locator,
                       std::shared_ptr<PreparedSeries>& prepared);
    int prepare_series(
        const FileGeneration& generation, const PreparedLocator& locator,
        const std::shared_ptr<PreparedSeries>& aligned_time_owner,
        std::shared_ptr<PreparedSeries>& prepared);
    int query_prepared(const std::shared_ptr<PreparedSeries>& prepared,
                       int64_t start_time, int64_t end_time, int offset,
                       int limit, ResultSet*& result_set);
    int query_prepared_multi(
        const std::vector<std::shared_ptr<PreparedSeries>>& prepared,
        int64_t start_time, int64_t end_time, int offset, int limit,
        ResultSet*& result_set);

    /**
     * @brief Query table-model data by row with offset/limit pushdown.
     *
     * For dense devices (all columns have the same row count),
     * offset/limit is pushed down to chunk/page level via SSI,
     * skipping entire chunks/pages without decoding.
     * For sparse devices, offset/limit is applied at the row-merge level.
     * Entire devices can be skipped when their total row count
     * falls within the offset range.
     *
     * @param table_name     Table to query.
     * @param column_names   Columns to select.
     * @param offset         Number of leading rows to skip (>= 0).
     * @param limit          Maximum rows to return. < 0 means unlimited.
     * @param[out] result_set  The result set containing query results.
     * @return Returns 0 on success, or a non-zero error code on failure.
     */
    int queryByRow(const std::string& table_name,
                   const std::vector<std::string>& column_names, int offset,
                   int limit, ResultSet*& result_set,
                   Filter* tag_filter = nullptr, int batch_size = 0);

    int query_table_on_tree(const std::vector<std::string>& measurement_names,
                            int64_t star_time, int64_t end_time,
                            ResultSet*& result_set);
    /**
     * @brief destroy the result set, this method should be called after the
     * query is finished and result_set
     *
     * @param qds the result set
     */
    void destroy_query_data_set(ResultSet* qds);
    ResultSet* read_timeseries(
        const std::shared_ptr<IDeviceID>& device_id,
        const std::vector<std::string>& measurement_name);
    /**
     * @brief get all devices in the tsfile
     *
     * @note Retained for backward compatibility. This signature cannot report
     * error codes; read failures return an empty list. Avoid this overload in
     * new code: use the error-reporting overload and check its return code.
     *
     * @param table_name the table name
     * @return std::vector<std::shared_ptr<IDeviceID>> the device id list
     */
    std::vector<std::shared_ptr<IDeviceID>> get_all_devices(
        std::string table_name);

    /**
     * Error-reporting table-scoped overload. The output is empty on failure.
     * A missing table or a table without devices returns E_OK and an empty
     * list, matching the legacy overload.
     */
    int get_all_devices(std::string table_name,
                        std::vector<std::shared_ptr<IDeviceID>>& device_ids);

    /**
     * @brief get all devices in the tsfile
     *
     * @return std::vector<std::shared_ptr<IDeviceID>> the device id list
     */
    std::vector<std::shared_ptr<IDeviceID>> get_all_device_ids();

    /**
     * @brief Get all device IDs in the file (same as get_all_device_ids).
     *
     * @return std::vector<std::shared_ptr<IDeviceID>> the device list
     */
    std::vector<std::shared_ptr<IDeviceID>> get_all_devices();

    /** Error-reporting overload. The output is empty on failure. */
    int get_all_devices(std::vector<std::shared_ptr<IDeviceID>>& device_ids);

    /**
     * @brief get the timeseries schema by the device id and measurement name
     *
     * @param [in] device_id the device id
     * @param [out] result std::vector<MeasurementSchema> the measurement schema
     * list
     * @return Returns 0 on success, or a non-zero error code on failure.
     */
    int get_timeseries_schema(std::shared_ptr<IDeviceID> device_id,
                              std::vector<MeasurementSchema>& result);

    /**
     * @brief Get timeseries metadata for specified devices.
     *
     * Only devices that exist in the file are included in the result.
     * If device_ids is empty, returns an empty map.
     *
     * @note Retained for backward compatibility. This signature cannot report
     * error codes; read failures return an empty map. Avoid this overload in
     * new code: use the error-reporting overload and check its return code.
     *
     * @param device_ids device list to query
     * @return map: IDeviceID -> list of timeseries metadata (only existing)
     */
    DeviceTimeseriesMetadataMap get_timeseries_metadata(
        const std::vector<std::shared_ptr<IDeviceID>>& device_ids);

    /** Error-reporting overload. Missing devices are skipped; the output is
     * empty on read failure. Metadata remains valid until the next metadata
     * call or until the reader is closed, as with the legacy overload. */
    int get_timeseries_metadata(
        const std::vector<std::shared_ptr<IDeviceID>>& device_ids,
        DeviceTimeseriesMetadataMap& result);

    /**
     * @brief Get timeseries metadata for all devices in the file.
     *
     * @note Retained for backward compatibility. This signature cannot report
     * error codes; read failures return an empty map. Avoid this overload in
     * new code: use the error-reporting overload and check its return code.
     *
     * @return map: IDeviceID -> list of timeseries metadata
     */
    DeviceTimeseriesMetadataMap get_timeseries_metadata();

    /** Error-reporting overload. The output is empty on failure. */
    int get_timeseries_metadata(DeviceTimeseriesMetadataMap& result);

    /** Return a copy of all file-level properties, preserving null values. */
    TsFileProperties get_tsfile_properties();

    /**
     * @brief get the table schema by the table name
     *
     * @note Retained for backward compatibility. This signature cannot report
     * error codes; both a missing table and a read failure return null. Avoid
     * this overload in new code: use the error-reporting overload and check
     * its return code.
     *
     * @param table_name the table name
     * @return std::shared_ptr<TableSchema> the table schema
     */
    std::shared_ptr<TableSchema> get_table_schema(
        const std::string& table_name);

    /**
     * @brief Get the table schema by table name.
     *
     * @param table_name the table name
     * @param[out] table_schema the resolved schema, null on failure
     * @return Returns 0 on success, E_TABLE_NOT_EXIST when the table is
     *         absent, or a non-zero read error code on metadata failure.
     */
    int get_table_schema(const std::string& table_name,
                         std::shared_ptr<TableSchema>& table_schema);
    /**
     * @brief get all table schemas in the tsfile
     *
     * @note Retained for backward compatibility. This signature cannot report
     * error codes; read failures return an empty list. Avoid this overload in
     * new code: use the error-reporting overload and check its return code.
     *
     * @return std::vector<std::shared_ptr<TableSchema>> the table schema list
     */
    std::vector<std::shared_ptr<TableSchema>> get_all_table_schemas();

    /** Error-reporting overload. The output is empty on failure. */
    int get_all_table_schemas(
        std::vector<std::shared_ptr<TableSchema>>& table_schemas);

   private:
    int open_source(std::unique_ptr<RandomAccessReadFile> read_file,
                    unsigned char file_version);
    int ensure_table_query_executor(int batch_size);
    int get_timeseries_metadata_impl(
        std::shared_ptr<IDeviceID> device_id,
        std::vector<std::shared_ptr<ITimeseriesIndex>>& result);
    int get_all_devices(std::vector<std::shared_ptr<IDeviceID>>& device_ids,
                        std::shared_ptr<MetaIndexNode> index_node,
                        common::PageArena& pa);
    std::unique_ptr<storage::RandomAccessReadFile> read_file_;
    storage::TsFileExecutor* tsfile_executor_;
    storage::TableQueryExecutor* table_query_executor_;
    int table_query_executor_batch_size_ = -1;
    unsigned char file_version_ = 0;
    common::PageArena tsfile_reader_meta_pa_;
    // Test-only hook for the unbounded-arena-growth regression check.
    friend class TsFileReaderMetaArenaTest;
};

}  // namespace storage

#endif  // READER_TSFILE_READER