開啟多檔案資料集

Arrow 資料集讓您能夠查詢分散在多個檔案中的資料。這種資料分片可能表示分割，這可以加速僅觸及某些分割區（檔案）的查詢。呼叫 open_dataset() 以指向資料檔案目錄並傳回 Dataset，然後使用 dplyr 方法來查詢它。

用法

open_dataset(
  sources,
  schema = NULL,
  partitioning = hive_partition(),
  hive_style = NA,
  unify_schemas = NULL,
  format = c("parquet", "arrow", "ipc", "feather", "csv", "tsv", "text", "json"),
  factory_options = list(),
  ...
)

引數

sources

以下其中一項

• 指向包含資料檔案的目錄的字串路徑或 URI

• 引用包含資料檔案的目錄的 FileSystem (例如 s3_bucket() 傳回的物件)

• 指向單一檔案的字串路徑或 URI

• 指向個別資料檔案的路徑或 URI 的字元向量

• 此函數建立的 Dataset 物件的列表

• dataset_factory() 建立的 DatasetFactory 物件的列表。

當 sources 是檔案 URI 的向量時，它們必須全部使用相同的協定，並且指向位於相同檔案系統且具有相同格式的檔案。

schema

Dataset 的 Schema。如果 NULL (預設值)，則將從資料來源推斷 schema。

partitioning

當 sources 是目錄路徑/URI 時，以下其中一項

• Schema，在這種情況下，將會剖析相對於 sources 的檔案路徑，並且路徑區段將與 schema 欄位比對。

• 定義與這些路徑區段對應的欄位名稱的字元向量 (也就是說，您正在提供與 Schema 對應的名稱，但類型將會自動偵測)

• Partitioning 或 PartitioningFactory，例如 hive_partition() 傳回的物件

• NULL 表示沒有分割

預設值是自動偵測 Hive 樣式分割，除非 hive_style = FALSE。請參閱「分割」章節以了解詳細資訊。當 sources 不是目錄路徑/URI 時，partitioning 會被忽略。

hive_style

邏輯值：partitioning 是否應解譯為 Hive 樣式？預設值為 NA，這表示檢查檔案路徑以尋找 Hive 樣式分割並據此運作。

unify_schemas

邏輯值：是否應掃描所有資料片段 (檔案、Dataset) 以從中建立統一的 schema？如果 FALSE，則只會檢查第一個片段的 schema。當您知道並信任所有片段都具有相同的 schema 時，請使用此快速路徑。當從目錄路徑/URI 或檔案路徑/URI 的向量建立資料集時，預設值為 FALSE (因為可能有很多檔案且掃描可能很慢)，但當 sources 是 Dataset 的列表時，預設值為 TRUE (因為列表中應該只有少數 Dataset 且它們的 Schema 已在記憶體中)。

format

FileFormat 物件，或 x 中檔案格式的字串識別符。當 sources 是 Dataset 物件的列表時，此引數會被忽略。目前支援的值

• "parquet"

• "ipc"/"arrow"/"feather"，彼此的所有別名；對於 Feather，請注意僅支援版本 2 檔案

• "csv"/"text"，相同事物的別名 (因為逗號是文字檔案的預設分隔符號

• "tsv"，相當於傳遞 format = "text", delimiter = "\t"

• "json"，適用於 JSON 格式資料集 注意：目前僅支援換行符號分隔的 JSON (又稱 ND-JSON) 資料集 預設值為 "parquet"，除非也指定了 delimiter，在這種情況下，它會被假定為 "text"。

factory_options

FileSystemFactoryOptions 的選用列表

• partition_base_dir：使用 DirectoryPartitioning 探索分割資訊時要忽略的字串路徑區段前綴。對於 HivePartitioning 沒有意義 (忽略並發出警告)，提供檔案路徑向量時也無效。

• exclude_invalid_files：邏輯值：是否應排除無效的資料檔案？預設值為 FALSE，因為預先檢查所有檔案會產生 I/O，因此速度會較慢，尤其是在遠端檔案系統上。如果為 false 且存在無效檔案，則在掃描時會發生錯誤。這是唯一一個 FileSystemFactoryOption，它在提供目錄路徑以在其中探索檔案以及提供檔案路徑向量時都有效。

• selector_ignore_prefixes：在目錄中探索檔案時要忽略的檔案前綴的字元向量。如果可以透過這種常見的檔案名稱前綴排除無效檔案，您可以避免 exclude_invalid_files 的 I/O 成本。提供檔案路徑向量時無效 (但如果您提供檔案列表，您可以自行篩選無效檔案)。

...

當 sources 是目錄路徑/URI 或檔案路徑/URI 的向量時，傳遞給 dataset_factory() 的其他引數，否則會被忽略。這些可能包括 format 以指示檔案格式，或其他格式特定的選項 (請參閱 read_csv_arrow()、read_parquet() 和 read_feather()，以了解如何指定這些選項)。

值

Dataset R6 物件。使用其上的 dplyr 方法來查詢資料，或呼叫 $NewScan() 以直接建構查詢。

分割

資料通常會根據資料中一或多個欄位的值，分割成多個檔案並巢狀於子目錄中。它可能是查詢中經常引用的欄位，或者可能是基於時間的，舉例來說。以這種方式劃分的資料稱為「分割」，而這些分割欄位的值會編碼到檔案路徑區段中。這些路徑區段實際上是資料集中的虛擬欄位，而且由於它們的值在讀取檔案本身之前就已知，因此我們可以透過完全跳過某些檔案來大幅加速篩選查詢。

Arrow 支援從檔案路徑中讀取分割資訊，有兩種形式

• 「Hive 樣式」，源自 Apache Hive 專案，並且在某些資料庫系統中很常見。分割區編碼為路徑區段中的「key=value」，例如 "year=2019/month=1/file.parquet"。雖然它們作為檔案名稱可能很笨拙，但它們的優點是具有自我描述性。

• 「目錄」分割，它是沒有鍵名的 Hive，例如 "2019/01/file.parquet"。為了使用這些，我們至少需要知道要給予來自路徑區段的虛擬欄位哪些名稱。

open_dataset() 中的預設行為是檢查提供的目錄中包含的檔案路徑，如果它們看起來像 Hive 樣式，則將它們剖析為 Hive。如果您的資料集在檔案路徑中具有 Hive 樣式分割，則您不需要在 partitioning 引數中為 open_dataset() 提供任何內容即可使用它們。如果您確實提供了分割欄位名稱的字元向量，如果它們與偵測到的內容相符，它們將被忽略，如果它們不相符，您將會收到錯誤。(如果您想要重新命名分割欄位，請在使用 select() 或 rename() 開啟資料集後執行此操作。)。如果您提供 Schema 且名稱與偵測到的內容相符，它將使用 Schema 定義的類型。在上面的範例檔案路徑中，您可以提供 Schema 以指定 "month" 應為 int8()，而不是預設情況下剖析為的 int32()。

如果您的檔案路徑看起來不像 Hive 樣式，或者如果您傳遞 hive_style = FALSE，則 partitioning 引數將用於建立目錄分割。建立分割區需要欄位名稱的字元向量；您可以改為提供 Schema 以將這些名稱對應到所需的欄位類型，如上所述。如果兩者都未提供，則不會從檔案路徑中取得分割資訊。

另請參閱

datasets 文章

範例

# Set up directory for examples
tf <- tempfile()
dir.create(tf)
on.exit(unlink(tf))

write_dataset(mtcars, tf, partitioning = "cyl")

# You can specify a directory containing the files for your dataset and
# open_dataset will scan all files in your directory.
open_dataset(tf)
#> FileSystemDataset with 3 Parquet files
#> 11 columns
#> mpg: double
#> disp: double
#> hp: double
#> drat: double
#> wt: double
#> qsec: double
#> vs: double
#> am: double
#> gear: double
#> carb: double
#> cyl: int32
#> 
#> See $metadata for additional Schema metadata

# You can also supply a vector of paths
open_dataset(c(file.path(tf, "cyl=4/part-0.parquet"), file.path(tf, "cyl=8/part-0.parquet")))
#> FileSystemDataset with 2 Parquet files
#> 10 columns
#> mpg: double
#> disp: double
#> hp: double
#> drat: double
#> wt: double
#> qsec: double
#> vs: double
#> am: double
#> gear: double
#> carb: double
#> 
#> See $metadata for additional Schema metadata

## You must specify the file format if using a format other than parquet.
tf2 <- tempfile()
dir.create(tf2)
on.exit(unlink(tf2))
write_dataset(mtcars, tf2, format = "ipc")
# This line will results in errors when you try to work with the data
if (FALSE) { # \dontrun{
open_dataset(tf2)
} # }
# This line will work
open_dataset(tf2, format = "ipc")
#> FileSystemDataset with 1 Feather file
#> 11 columns
#> mpg: double
#> cyl: double
#> disp: double
#> hp: double
#> drat: double
#> wt: double
#> qsec: double
#> vs: double
#> am: double
#> gear: double
#> carb: double
#> 
#> See $metadata for additional Schema metadata

## You can specify file partitioning to include it as a field in your dataset
# Create a temporary directory and write example dataset
tf3 <- tempfile()
dir.create(tf3)
on.exit(unlink(tf3))
write_dataset(airquality, tf3, partitioning = c("Month", "Day"), hive_style = FALSE)

# View files - you can see the partitioning means that files have been written
# to folders based on Month/Day values
tf3_files <- list.files(tf3, recursive = TRUE)

# With no partitioning specified, dataset contains all files but doesn't include
# directory names as field names
open_dataset(tf3)
#> FileSystemDataset with 153 Parquet files
#> 4 columns
#> Ozone: int32
#> Solar.R: int32
#> Wind: double
#> Temp: int32
#> 
#> See $metadata for additional Schema metadata

# Now that partitioning has been specified, your dataset contains columns for Month and Day
open_dataset(tf3, partitioning = c("Month", "Day"))
#> FileSystemDataset with 153 Parquet files
#> 6 columns
#> Ozone: int32
#> Solar.R: int32
#> Wind: double
#> Temp: int32
#> Month: int32
#> Day: int32
#> 
#> See $metadata for additional Schema metadata

# If you want to specify the data types for your fields, you can pass in a Schema
open_dataset(tf3, partitioning = schema(Month = int8(), Day = int8()))
#> FileSystemDataset with 153 Parquet files
#> 6 columns
#> Ozone: int32
#> Solar.R: int32
#> Wind: double
#> Temp: int32
#> Month: int8
#> Day: int8
#> 
#> See $metadata for additional Schema metadata