跳到内容

如果您有兴趣为 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 用户可能经常遇到许多这些工厂方法也具有 “snake_case” 别名,以便更熟悉当代 R 用户。 因此,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 参数名称

  • 如果 Arrow 参数在 R 函数中不存在,则允许用户也传入这些选项

  • 在必要时,为 R 中不存在但在 Arrow 中存在的特性向函数签名添加额外的参数(例如,在读取 CSV 数据集时传入模式)