跳到內容

如果您有興趣貢獻 arrow,本文將從高階角度說明我們的方法。在文章末尾,我們加入了連結,以各種方式擴展說明。

套件結構與慣例

首先概述套件的結構會很有幫助。

C++ 是一種物件導向語言,因此 Arrow C++ 函式庫的核心邏輯封裝在類別和方法中。在 arrow R 套件中,這些類別實作為 R6 類別,其中大多數是從命名空間匯出的。

為了符合 C++ 命名慣例,R6 類別以「TitleCase」命名,例如 RecordBatch。這樣可以輕鬆地在 程式碼文件 中查找相關的 C++ 實作。為了簡化 R 中的操作,C++ 函式庫命名空間通常會被刪除或扁平化;也就是說,C++ 函式庫中使用 arrow::io::FileOutputStream 的地方,在 R 套件中就只是 FileOutputStream。檔案讀取器是一個例外,其中命名空間是消除歧義所必需的。因此,arrow::csv::TableReader 變成 CsvTableReader,而 arrow::json::TableReader 變成 JsonTableReader

這些類別中有一些並非旨在直接實例化;它們可能是基底類別或其他類型的輔助程式。對於您應該能夠建立的類別,請使用 $create() 方法來實例化物件。例如,rb <- RecordBatch$create(int = 1:10, dbl = as.numeric(1:10)) 將建立一個 RecordBatch。為了更貼近現代 R 使用者的習慣,R 使用者最常遇到的許多工廠方法也都有一個「snake_case」別名。因此,record_batch(int = 1:10, dbl = as.numeric(1:10)) 的作用與上面的 RecordBatch$create() 相同。

arrow R 套件的典型使用者可能永遠不會直接處理 R6 物件。我們提供更友善 R 的包裝函式,作為 C++ 函式庫的更高階介面。R 使用者可以呼叫 read_parquet(),而無需知道或在意他們是否正在實例化 ParquetFileReader 物件並呼叫其 $ReadFile() 方法。這些類別的存在是為了讓想要精細控制 C++ 函式庫使用方式的進階程式設計師使用。

實作功能的途徑

我們在實作功能時的一般理念是,盡可能符合使用者可能熟悉的現有 R 函式簽名,同時公開透過 Arrow 提供的任何額外功能。目的是讓使用者能夠以最少的變更來使用他們現有的程式碼,或者學習新的程式碼或方法。

我們透過多種方式做到這一點

  • 當實作具有 R 等效函式的函式時,盡可能支援 R 版本中可用的引數 - 使用原始參數名稱,並在函式內部翻譯為 arrow 參數名稱

  • 如果存在 R 函式中不存在的 arrow 參數,則允許使用者也傳入這些選項

  • 在必要時,為 R 中不存在但在 Arrow 中存在的功能新增額外引數到函式簽名中 (例如,在讀取 CSV 資料集時傳入 schema)