寫入資料集

此函數讓您可以寫入資料集。透過寫入更有效率的二進位儲存格式，並指定相關的分割，您可以讓讀取和查詢速度更快。

用法

write_dataset(
  dataset,
  path,
  format = c("parquet", "feather", "arrow", "ipc", "csv", "tsv", "txt", "text"),
  partitioning = dplyr::group_vars(dataset),
  basename_template = paste0("part-{i}.", as.character(format)),
  hive_style = TRUE,
  existing_data_behavior = c("overwrite", "error", "delete_matching"),
  max_partitions = 1024L,
  max_open_files = 900L,
  max_rows_per_file = 0L,
  min_rows_per_group = 0L,
  max_rows_per_group = bitwShiftL(1, 20),
  ...
)

引數

dataset

Dataset、 RecordBatch、 Table、 arrow_dplyr_query 或 data.frame。如果為 arrow_dplyr_query，查詢將會被評估，且結果將會被寫入。這表示您可以 select()、 filter()、 mutate() 等等來轉換資料，如果您需要的話，在寫入之前。

path

字串路徑、URI 或 SubTreeFileSystem 參考要寫入的目錄（如果目錄不存在將會建立）

format

檔案格式的字串識別符。預設為使用 "parquet"（請參閱 FileFormat）

partitioning

Partitioning 或字元向量，用於作為分割鍵的欄位（將寫入為路徑區段）。預設為使用目前的 group_by() 欄位。

basename_template

要寫入的檔案名稱的字串範本。必須包含 "{i}"，這將會被替換為自動遞增的整數，以產生資料檔案的基本名稱。例如，"part-{i}.arrow" 將產生 "part-0.arrow", ...。如果未指定，則預設為 "part-{i}.<預設副檔名>"。

hive_style

邏輯值：以 Hive 樣式（key1=value1/key2=value2/file.ext）或僅以裸值寫入分割區段。預設為 TRUE。

existing_data_behavior

當目標目錄中已存在資料時要使用的行為。必須是 "overwrite"、"error" 或 "delete_matching" 之一。

• "overwrite"（預設值）然後任何新建立的檔案將覆寫現有檔案

• "error" 則如果目標目錄不是空的，操作將會失敗

• "delete_matching" 則寫入器將刪除任何現有的分割區，如果資料將被寫入到這些分割區，並且將保留未寫入資料的分割區。

max_partitions

任何批次可以寫入的最大分割區數量。預設值為 1024L。

max_open_files

在寫入操作期間可以保持開啟的最大檔案數量。如果大於 0，則這將限制可以保持開啟的最大檔案數量。如果嘗試開啟過多檔案，則最近最少使用的檔案將被關閉。如果此設定設定得太低，您最終可能會將資料分割成許多小檔案。預設值為 900，這也允許掃描器在達到預設 Linux 限制 1024 之前開啟一些檔案。

max_rows_per_file

每個檔案的最大列數。如果大於 0，則這將限制任何單個檔案中放置的列數。預設值為 0L。

min_rows_per_group

當累積到此列數時，將列群組寫入磁碟。預設值為 0L。

max_rows_per_group

單一群組中允許的最大列數，當超過此列數時，它將被分割，並且下一組列將被寫入到下一個群組。此值必須設定為大於 min_rows_per_group。預設值為 1024 * 1024。

...

其他格式特定的引數。如需可用的 Parquet 選項，請參閱 write_parquet()。可用的 Feather 選項為

• use_legacy_format 邏輯值：寫入格式化的資料，以便 Arrow 程式庫 0.14 及更低版本可以讀取它。預設值為 FALSE。您也可以透過設定環境變數 ARROW_PRE_0_15_IPC_FORMAT=1 來啟用此功能。

• metadata_version：字串，如 "V5" 或等效的整數，表示 Arrow IPC MetadataVersion。預設值 (NULL) 將使用最新版本，除非環境變數 ARROW_PRE_1_0_METADATA_VERSION=1，在這種情況下它將是 V4。

• codec：Codec，將用於壓縮已寫入檔案的本文緩衝區。預設值 (NULL) 將不會壓縮本文緩衝區。

• null_fallback：字元，當使用 Hive 樣式分割時，用於代替遺失值（NA 或 NULL）。請參閱 hive_partition()。

值

輸入的 dataset，不可見地傳回

範例

# You can write datasets partitioned by the values in a column (here: "cyl").
# This creates a structure of the form cyl=X/part-Z.parquet.
one_level_tree <- tempfile()
write_dataset(mtcars, one_level_tree, partitioning = "cyl")
list.files(one_level_tree, recursive = TRUE)
#> [1] "cyl=4/part-0.parquet" "cyl=6/part-0.parquet" "cyl=8/part-0.parquet"

# You can also partition by the values in multiple columns
# (here: "cyl" and "gear").
# This creates a structure of the form cyl=X/gear=Y/part-Z.parquet.
two_levels_tree <- tempfile()
write_dataset(mtcars, two_levels_tree, partitioning = c("cyl", "gear"))
list.files(two_levels_tree, recursive = TRUE)
#> [1] "cyl=4/gear=3/part-0.parquet" "cyl=4/gear=4/part-0.parquet"
#> [3] "cyl=4/gear=5/part-0.parquet" "cyl=6/gear=3/part-0.parquet"
#> [5] "cyl=6/gear=4/part-0.parquet" "cyl=6/gear=5/part-0.parquet"
#> [7] "cyl=8/gear=3/part-0.parquet" "cyl=8/gear=5/part-0.parquet"

# In the two previous examples we would have:
# X = {4,6,8}, the number of cylinders.
# Y = {3,4,5}, the number of forward gears.
# Z = {0,1,2}, the number of saved parts, starting from 0.

# You can obtain the same result as as the previous examples using arrow with
# a dplyr pipeline. This will be the same as two_levels_tree above, but the
# output directory will be different.
library(dplyr)
two_levels_tree_2 <- tempfile()
mtcars %>%
  group_by(cyl, gear) %>%
  write_dataset(two_levels_tree_2)
list.files(two_levels_tree_2, recursive = TRUE)
#> [1] "cyl=4/gear=3/part-0.parquet" "cyl=4/gear=4/part-0.parquet"
#> [3] "cyl=4/gear=5/part-0.parquet" "cyl=6/gear=3/part-0.parquet"
#> [5] "cyl=6/gear=4/part-0.parquet" "cyl=6/gear=5/part-0.parquet"
#> [7] "cyl=8/gear=3/part-0.parquet" "cyl=8/gear=5/part-0.parquet"

# And you can also turn off the Hive-style directory naming where the column
# name is included with the values by using `hive_style = FALSE`.

# Write a structure X/Y/part-Z.parquet.
two_levels_tree_no_hive <- tempfile()
mtcars %>%
  group_by(cyl, gear) %>%
  write_dataset(two_levels_tree_no_hive, hive_style = FALSE)
list.files(two_levels_tree_no_hive, recursive = TRUE)
#> [1] "4/3/part-0.parquet" "4/4/part-0.parquet" "4/5/part-0.parquet"
#> [4] "6/3/part-0.parquet" "6/4/part-0.parquet" "6/5/part-0.parquet"
#> [7] "8/3/part-0.parquet" "8/5/part-0.parquet"