跳过内容

将 Parquet 文件写入磁盘

来源：R/parquet.R
write_parquet.Rd

Parquet 是一种列式存储文件格式。此函数使您能够从 R 中写入 Parquet 文件。

用法

write_parquet(
  x,
  sink,
  chunk_size = NULL,
  version = "2.4",
  compression = default_parquet_compression(),
  compression_level = NULL,
  use_dictionary = NULL,
  write_statistics = NULL,
  data_page_size = NULL,
  use_deprecated_int96_timestamps = FALSE,
  coerce_timestamps = NULL,
  allow_truncated_timestamps = FALSE
)

参数

x

data.frame、RecordBatch 或 Table

sink

字符串文件路径、连接、URI 或 OutputStream，或文件系统中的路径 (SubTreeFileSystem)

chunk_size

一次写入磁盘的数据行数。这直接对应于 Parquet 中每个行组（row group）包含的行数。如果设为 NULL，系统将基于列数和行数估算出一个最佳大小；但如果数据少于 2.5 亿个单元格（行 x 列），则会使用总行数。

version

Parquet 版本："1.0"、"2.4"（默认）、"2.6" 或 "latest"（目前等同于 2.6）。数值将被强制转换为字符型。

compression

压缩算法。默认为 "snappy"。详见后文。

compression_level

压缩级别。其含义取决于所选的压缩算法。

use_dictionary

逻辑值：是否使用字典编码？默认为 TRUE。

write_statistics

逻辑值：是否包含统计信息？默认为 TRUE。

data_page_size

设置列块（column chunk）内数据页近似编码大小的目标阈值（单位为字节）。默认为 1 MiB。

use_deprecated_int96_timestamps

逻辑值：是否将时间戳写入已弃用的 INT96 Parquet 格式？默认为 FALSE。

coerce_timestamps

将时间戳转换（Cast）为特定分辨率。可以是 NULL、“ms” 或 “us”。默认为 NULL（不进行转换）。

allow_truncated_timestamps

逻辑值：在将时间戳强制转换为特定分辨率时，是否允许数据丢失。例如，如果转换为 “ms” 时微秒或纳秒数据丢失，是否不引发异常。默认为 FALSE。

返回值

隐式返回输入的 x。

详情

由于该格式的特性，Parquet 文件无法进行追加（append）操作。如果您想使用 Parquet 格式但又需要扩展数据集，可以写入额外的 Parquet 文件，然后将整个文件目录视为一个可以查询的 Dataset。有关示例，请参见 dataset 文章。

参数 compression、compression_level、use_dictionary 和 write_statistics 支持多种模式：

  • 默认值 NULL 表示不指定参数，C++ 库将为每一列使用适当的默认值（默认值列于上文）。

  • 单个未命名的值（例如 compression 的单个字符串）将应用于所有列。

  • 一个大小与列数相同的未命名向量，用于按位置顺序为每一列指定值。

  • 一个命名向量，用于为指定的列设定值；未提供的列将使用设置的默认值。

compression 参数可以是以下任意值（不区分大小写）："uncompressed"、"snappy"、"gzip"、"brotli"、"zstd"、"lz4"、"lzo" 或 "bz2"。仅保证 "uncompressed" 可用，但 "snappy" 和 "gzip" 通常也包含在内。请参阅 codec_is_available()。默认使用 "snappy"（若可用），否则使用 "uncompressed"。要禁用压缩，请设置 compression = "uncompressed"。请注意，"uncompressed" 的列仍可能使用字典编码。

另请参阅

ParquetFileWriter 用于更底层的 Parquet 写入接口。

示例

tf1 <- tempfile(fileext = ".parquet")
write_parquet(data.frame(x = 1:5), tf1)

# using compression
if (codec_is_available("gzip")) {
  tf2 <- tempfile(fileext = ".gz.parquet")
  write_parquet(data.frame(x = 1:5), tf2, compression = "gzip", compression_level = 5)
}