io/types.hpp

转到此文件的文档。

/*
 * 版权所有 (c) 2019-2025, NVIDIA CORPORATION.
 *
 * 根据 Apache 许可证，版本 2.0（“许可证”）获得许可；
 * 您除非遵守许可证的规定，否则不得使用此文件。
 * 您可以在以下位置获取许可证的副本：
 *
 * https://apache.ac.cn/licenses/LICENSE-2.0
 *
 * 除非适用法律要求或书面同意，否则
 * 根据许可证分发的软件按“原样”分发，
 * 不附带任何明示或默示的保证或条件。
 * 请参阅许可证了解管理权限和
 * 限制的特定语言。
 */

#pragma once

#include <cudf/table/table.hpp>
#include <cudf/types.hpp>
#include <cudf/utilities/span.hpp>

#include <map>
#include <memory>
#include <optional>
#include <string>
#include <unordered_map>
#include <utility>
#include <vector>

namespace CUDF_EXPORT cudf {
namespace io {
class data_sink;
class datasource;
} // io 命名空间
} // CUDF_EXPORT cudf 命名空间

namespace CUDF_EXPORT cudf {
namespace io {
enum class compression_type : int32_t {
 NONE,
 AUTO,
 SNAPPY,
 GZIP,
 BZIP2,
 BROTLI,
 ZIP,
 XZ,
 ZLIB,
 LZ4,
 LZO,
 ZSTD
};

enum class io_type : int32_t {
 FILEPATH,
 HOST_BUFFER,
 DEVICE_BUFFER,
 VOID,
 USER_IMPLEMENTED,
};

enum class quote_style : int32_t {
 MINIMAL,
 ALL,
 NONNUMERIC,
 NONE
};

enum statistics_freq : int32_t {
 STATISTICS_NONE = 0,
 STATISTICS_ROWGROUP = 1,
 STATISTICS_PAGE = 2,
 STATISTICS_COLUMN = 3,
};

enum class column_encoding : int32_t {
 // 常见编码：
 USE_DEFAULT = -1,
 DICTIONARY,
 // Parquet 编码：
 PLAIN,
 DELTA_BINARY_PACKED,
 DELTA_LENGTH_BYTE_ARRAY,
 DELTA_BYTE_ARRAY,
 BYTE_STREAM_SPLIT,
 // ORC 编码：
 DIRECT,
 DIRECT_V2,
 DICTIONARY_V2,
};

class writer_compression_statistics {
 public
 writer_compression_statistics() = default;

 /*!
 * \brief 构造新的压缩统计对象。
 *
 * \param num_compressed_bytes 成功压缩的字节数。
 * \param num_failed_bytes 压缩失败的字节数。
 * \param num_skipped_bytes 未压缩的字节数（例如太小）。
 * \param num_compressed_output_bytes 生成的压缩数据的大小。
 */
 writer_compression_statistics(size_t num_compressed_bytes,
 size_t num_failed_bytes,
 size_t num_skipped_bytes,
 /*!
 * \brief 将另一个对象的压缩统计信息添加到此对象。
 *
 * \param other 要添加统计信息的另一个对象。
 * \return 更新了新统计信息的此对象。
 */
 writer_compression_statistics& operator+=(writer_compression_statistics const& other) noexcept
 {
 _num_compressed_bytes += other._num_compressed_bytes;
 /*!
 * \brief 返回成功压缩的字节数。
 /*!
 * \brief 返回压缩失败的字节数。
 /*!
 * \brief 返回未压缩的字节数。
 /*!
 * \brief 返回考虑进行压缩的总输入字节数。
 */
 [[nodiscard]] auto num_total_input_bytes() const noexcept
 {
 /*!
 * \brief 返回总压缩比，即 `num_compressed_bytes / num_compressed_output_bytes`
 *
 * \note 如果 `num_compressed_output_bytes` 为零，则返回 0.0。
 */
 private
 std::size_t _num_compressed_bytes = 0;
 std::size_t _num_failed_bytes = 0;
 std::size_t _num_skipped_bytes = 0;
 std::size_t _num_compressed_output_bytes = 0;
};

/*!
 * \brief 字典编码策略。
 *
 * 这控制何时/是否对字符串列使用字典编码
 * 在写操作期间。
 */
/*!
 * \brief 列的 Schema 信息。
 *
 * 读操作使用此信息提供 Schema 详细信息，写操作使用此信息
 * 覆盖列数据本身提供的 Schema 详细信息。
 */

 /*!
 * \brief 从列名和可选属性构造新实例。
 *
 * \param _name 列名。
 * \param _is_nullable 列的可选可为空性。
 * \param _is_binary 列的可选二进制类型。
 */
 column_name_info() = default;

 /*!
 * \brief 相等比较运算符。
 *
 * \param rhs 要比较的另一个列信息对象。
 * \return 如果对象相等则返回 True，否则返回 False。
 */
};

/*!
 * \brief 表元数据信息。
 */
 /*!< Schema 信息。 */
 /*!< 每个数据源中的行数。 */
 /*!< 任意文件级用户定义键值元数据。 */
 /*!< 每个文件的任意用户定义键值元数据。 */

 // 以下变量目前仅针对 Parquet 读取器计算
 /*!< 读取的总输入行组数（仅限 Parquet）。 */
 std::optional<size_type>
 /*!< 应用统计过滤器后的行组数（仅限 Parquet）。 */
 std::optional<size_type>
 /*!< 应用 Bloom 过滤器后的行组数（仅限 Parquet）。 */
};

/*!
 * \brief 带有附加元数据的表。
 */
};

/*!
 * \brief 主机可访问内存缓冲区的视图。
 * \deprecated 请改用 `cudf::host_span`。
 */
 host_buffer() = default;
 /*!
 * \brief 从指针和大小构造新实例。
 *
 /*!
 * \brief 检查类型 `T` 是否类似于字节（char, int8_t, unsigned char, uint8_t, std::byte）。
 */
 using non_cv_T = std::remove_cv_t<T>;
 return std::is_same_v<non_cv_T, int8_t> || std::is_same_v<non_cv_T, char> ||
 std::is_same_v<non_cv_T, uint8_t> || std::is_same_v<non_cv_T, unsigned char> ||
 std::is_same_v<non_cv_T, std::byte>;
}

/*!
 * \brief 数据源信息。
 */
 /*!
 * \brief 从文件路径列表构造新实例。
 *
 * \param file_paths 文件路径列表。
 */
 /*!
 * \brief 从单个文件路径构造新实例。
 *
 * \param file_path 单个文件路径。
 */
 /*!
 * \brief 从主机缓冲区列表构造新实例。
 *
 * \param host_buffers 主机缓冲区列表。
 */
 explicit source_info(std::vector<host_buffer> const& host_buffers) : _type(io_type::HOST_BUFFER)
 {
 _host_buffers.reserve(host_buffers.size());
 std::transform(host_buffers.begin(),
 host_buffers.end(),
 std::back_inserter(_host_buffers),
 [](auto const hb) {
 /*!
 * \brief 从单个主机缓冲区构造新实例。
 *
 * \param host_data 指向数据的指针。
 * \param size 数据大小（字节）。
 */
 explicit source_info(char const* host_data, size_t size)
 /*!
 * \brief 从主机 span 列表构造新实例。
 *
 * \tparam T 主机 span 的元素类型。必须类似于字节。
 * \param host_buffers 主机 span 列表。
 */
 explicit source_info(cudf::host_span<cudf::host_span<T>> const host_buffers)
 : _type(io_type::HOST_BUFFER)
 {
 if constexpr (not std::is_same_v<std::remove_cv_t<T>, std::byte>) {
 _host_buffers.reserve(host_buffers.size());
 std::transform(host_buffers.begin(),
 host_buffers.end(),
 std::back_inserter(_host_buffers),
 [](auto const s) {
 return cudf::host_span<std::byte const>{
 reinterpret_cast<std::byte const*>(s.data()), s.size()};
 });
 /*!
 * \brief 从单个主机 span 构造新实例。
 *
 * \tparam T 主机 span 的元素类型。必须类似于字节。
 * \param host_data 单个主机 span。
 */
 explicit source_info(cudf::host_span<T> host_data)
 : _type(io_type::HOST_BUFFER),
 /*!
 * \brief 从设备 span 列表构造新实例。
 *
 * \param device_buffers 设备 span 列表。
 */
 /*!
 * \brief 从单个设备缓冲区构造新实例。
 *
 * \param d_buffer 单个设备缓冲区。
 */
 /*!
 * \brief 从用户实现的数据源对象列表构造新实例。
 *
 * \param sources 数据源对象列表。
 */
 /*!
 * \brief 从单个用户实现的数据源对象构造新实例。
 *
 * \param source 单个数据源对象。
 */
 /*!
 /*!
 /*!
 /*!
 /*!
 * \brief 如果类型是 `USER_IMPLEMENTED` ，则返回用户实现的数据源对象列表
 */
 private
 io_type _type = io_type::VOID;
 std::vector<std::string> _filepaths;
 std::vector<cudf::host_span<std::byte const>> _host_buffers;
 std::vector<cudf::device_span<std::byte const>> _device_buffers;
 std::vector<cudf::io::datasource*> _user_sources;
};
/*!
 * \brief 数据目标信息。
 /*!
 * \brief 构造具有特定数量目标的新实例。
 /*!
 * \brief 从文件路径列表构造新实例。
 *
 * \param file_paths 文件路径列表。
 */
 /*!
 * \brief 从单个文件路径构造新实例。
 *
 * \param file_path 单个文件路径。
 */
 /*!
 * \brief 从主机缓冲区列表构造新实例。
 *
 * \param buffers 主机缓冲区列表。
 /*!
 * \brief 从单个主机缓冲区构造新实例。
 /*!
 * \brief 从用户实现的数据目标对象列表构造新实例。
 *
 * \param user_sinks 数据目标对象列表。
 */
 : _type(io_type::USER_IMPLEMENTED),
 _num_sinks(user_sinks.size()),
 /*!
 * \brief 从单个用户实现的数据目标对象构造新实例。
 *
 * \param user_sink 单个数据目标对象。
 */
 /*!
 /*!
 /*!
 /*!
 /*!
 * \brief 如果类型是 `USER_IMPLEMENTED` ，则返回用户实现的数据目标对象列表
 */
 private
 io_type _type = io_type::VOID;
 size_t _num_sinks = 1;
 std::vector<std::string> _filepaths;
 std::vector<std::vector<char>*> _buffers;
 std::vector<cudf::io::data_sink*> _user_sinks;
};

class table_input_metadata;
/*!
 * \brief 写操作期间用于覆盖列 Schema 详细信息的元数据。
 */
 std::optional<bool> _nullable;
 bool _list_column_is_map = false;
 bool _use_int96_timestamp = false;
 bool _output_as_binary = false;
 bool _skip_compression = false;
 std::optional<uint8_t> _decimal_precision;
 std::optional<int32_t> _parquet_field_id;
 std::optional<int32_t> _type_length;
 std::vector<column_in_metadata> children;
 column_encoding _encoding = column_encoding::USE_DEFAULT;

 public
 column_in_metadata() = default;
 /*!
 /*!
 * \brief 向元数据添加一个子列。
 *
 * \param child 子列元数据。
 * \return 此对象用于链式 API 调用。
 */
 /*!
 * \brief 设置列名。
 *
 * \param name 列名。
 * \return 此对象用于链式 API 调用。
 */
 /*!
 * \brief 设置列可为空性。
 *
 * \param nullable 如果可为空则为 True，否则为 False。
 * \return 此对象用于链式 API 调用。
 */
 /*!
 * \brief 设置标志，将 list 列视为 map 列。
 *
 * \return 此对象用于链式 API 调用。
 */
 column_in_metadata& set_list_column_as_map() noexcept
 /*!
 * \brief 请求将时间戳输出为 INT96。
 * Applies only to Parquet.
 * \param req 如果需要 INT96 则为 True，否则为 False。
 * \return 此对象用于链式 API 调用。
 */
 /*!
 * \brief 设置列十进制精度。
 * Applies only to Parquet and ORC.
 * \param precision 列的十进制精度。
 * \return 此对象用于链式 API 调用。
 */
 /*!
 * \brief 设置列类型长度。
 * Applies only to Parquet (fixed-width types).
 * \param length 列的类型长度。
 * \return 此对象用于链式 API 调用。
 */
 /*!
 * \brief 设置列 Parquet 字段 ID。
 * Applies only to Parquet.
 * \param field_id 列的 Parquet 字段 ID。
 * \return 此对象用于链式 API 调用。
 */
 /*!
 * \brief 将列输出类型设置为二进制。仅限 Parquet。
 * \param binary 如果输出应为二进制则为 True，否则为 False。
 * \return 此对象用于链式 API 调用。
 */
 column_in_metadata& set_output_as_binary(bool binary) noexcept
 {
 _output_as_binary = binary;
 if (_output_as_binary and children.size() == 1) {
 children.emplace_back();
 } else if (!_output_as_binary and children.size() == 2) {
 /*!
 * \brief 设置列压缩为禁用。
 * Applies only to Parquet and ORC.
 * \param skip 如果应跳过压缩则为 True，否则为 False。
 * \return 此对象用于链式 API 调用。
 */
 /*!
 * \brief 设置列编码。
 * \note 某些编码仅适用于特定文件格式（例如，Parquet，ORC）。
 * \param encoding 用于该列的编码。
 * \return 此对象用于链式 API 调用。
 */
 /*!

 [[nodiscard]] column_in_metadata const& child(size_type i) const noexcept { return children[i]; }

 [[nodiscard]] std::string const& get_name() const noexcept { return _name; }

 [[nodiscard]] bool is_nullability_defined() const noexcept { return _nullable.has_value(); }

 [[nodiscard]] bool nullable() const { return _nullable.value(); }

 [[nodiscard]] bool is_map() const noexcept { return _list_column_is_map; }

 [[nodiscard]] bool is_enabled_int96_timestamps() const noexcept { return _use_int96_timestamp; }

 [[nodiscard]] bool is_decimal_precision_set() const noexcept
 {
 return _decimal_precision.has_value();
 }

 [[nodiscard]] uint8_t get_decimal_precision() const { return _decimal_precision.value(); }

 [[nodiscard]] bool is_type_length_set() const noexcept { return _type_length.has_value(); }

 [[nodiscard]] uint8_t get_type_length() const { return _type_length.value(); }

 [[nodiscard]] bool is_parquet_field_id_set() const noexcept
 {
 return _parquet_field_id.has_value();
 }

 [[nodiscard]] int32_t get_parquet_field_id() const { return _parquet_field_id.value(); }

 [[nodiscard]] size_type num_children() const noexcept { return children.size(); }

 [[nodiscard]] bool is_enabled_output_as_binary() const noexcept { return _output_as_binary; }

 [[nodiscard]] bool is_enabled_skip_compression() const noexcept { return _skip_compression; }

 [[nodiscard]] column_encoding get_encoding() const { return _encoding; }
};

class table_input_metadata {
 public
 table_input_metadata() = default; // Required by cython

 explicit table_input_metadata(table_view const& table);

 explicit table_input_metadata(table_metadata const& metadata);

 std::vector<column_in_metadata> column_metadata;
};

struct partition_info {
 size_type start_row;
 size_type num_rows;

 partition_info() = default;
 partition_info(size_type start_row, size_type num_rows) : start_row(start_row), num_rows(num_rows)
 {
 }
};

class reader_column_schema {
 // Whether to read binary data as a string column
 bool _convert_binary_to_strings{true};
 int32_t _type_length{0};

 std::vector<reader_column_schema> children;

 public
 reader_column_schema() = default;

 reader_column_schema(size_type number_of_children) { children.resize(number_of_children); }

 reader_column_schema(host_span<reader_column_schema> const& child_span)
 {
 children.assign(child_span.begin(), child_span.end());
 }

 reader_column_schema& add_child(reader_column_schema const& child)
 {
 children.push_back(child);
 return *this;
 }

 [[nodiscard]] reader_column_schema& child(size_type i) { return children[i]; }

 [[nodiscard]] reader_column_schema const& child(size_type i) const { return children[i]; }

 reader_column_schema& set_convert_binary_to_strings(bool convert_to_string)
 {
 _convert_binary_to_strings = convert_to_string;
 return *this;
 }

 reader_column_schema& set_type_length(int32_t type_length)
 {
 _type_length = type_length;
 return *this;
 }

 [[nodiscard]] bool is_enabled_convert_binary_to_strings() const
 {
 return _convert_binary_to_strings;
 }

 [[nodiscard]] int32_t get_type_length() const { return _type_length; }

 [[nodiscard]] size_t get_num_children() const { return children.size(); }
};
 // end of group
} // namespace io
} // namespace CUDF_EXPORT cudf