Arrow C 数据接口#

基本原理#

Apache Arrow 被设计为用于表示表格（“列式”）数据的通用内存中格式。但是，某些项目可能在依赖于快速发展项目（如 Arrow C++ 库）或重新实现数据交换适配器之间面临艰难的选择，这可能需要大量的重复开发工作。

Arrow C 数据接口定义了一组非常小且稳定的 C 定义，这些定义可以轻松地复制到任何项目的源代码中，并用于以 Arrow 格式交换列式数据。对于非 C/C++ 语言和运行时，将 C 定义转换为相应的 C FFI 声明几乎同样容易。

因此，应用程序和库可以在没有必要使用 Arrow 库或重新发明轮子的情况下使用 Arrow 内存。开发人员可以选择与 Arrow软件项目紧密集成（得益于例如 Apache Arrow 的 C++ 或 Java 实现所公开的越来越多的功能，但需要依赖项）或仅与 Arrow格式进行最小集成。

目标#

  • 公开一个 ABI 稳定的接口。

  • 使第三方项目能够轻松地实现支持（包括部分支持，如果足够的话），且初始投资很少。

  • 允许在同一进程中运行的独立运行时和组件之间零拷贝共享 Arrow 数据。

  • 将 Arrow 数组概念与之紧密匹配，以避免开发另一个编组层。

  • 避免需要一对一适配层，例如 Java 和 Python 之间基于 JPype 的有限桥梁。

  • 启用集成，而无需显式依赖（在编译时或运行时）Arrow 软件项目。

理想情况下，Arrow C 数据接口可以成为在运行时共享列式数据的低级通用语言，并将 Arrow 建立为列式处理生态系统中的通用构建块。

非目标#

  • 公开一个模拟高级运行时（例如 C++、Java 等）中可用操作的 C API。

  • 不同进程之间的数据共享或存储持久性。

与 Arrow IPC 格式的比较#

C 数据接口相对于 IPC 格式的优点

  • 不依赖 Flatbuffers。

  • 没有缓冲区重新组装（数据已以逻辑 Arrow 格式公开）。

  • 零拷贝设计。

  • 易于从头开始重新实现。

  • 最小的 C 定义，可以轻松地复制到其他代码库中。

  • 通过自定义释放回调进行资源生命周期管理。

IPC 格式相对于数据接口的优点

  • 跨进程和机器工作。

  • 允许数据存储和持久化。

  • 作为可流式格式，IPC 格式有空间用于组合更多功能（如完整性检查、压缩等）。

  • 不需要显式 C 数据访问。

数据类型描述 - 格式字符串#

数据类型使用格式字符串描述。格式字符串仅编码有关顶层类型的信息；对于嵌套类型，子类型将单独描述。此外，元数据在单独的字符串中编码。

格式字符串旨在易于解析，即使是从 C 等语言解析也是如此。最常见的原始格式具有一个字符的格式字符串。

格式字符串

Arrow 数据类型

注释

n

null

b

boolean

c

int8

C

uint8

s

int16

S

uint16

i

int32

I

uint32

l

int64

L

uint64

e

float16

f

float32

g

float64

格式字符串

Arrow 数据类型

注释

z

binary

Z

large binary

vz

binary view

u

utf-8 string

U

large utf-8 string

vu

utf-8 view

d:19,10

decimal128 [精度 19，比例 10]

d:19,10,NNN

decimal 位宽 = NNN [精度 19，比例 10]

w:42

固定宽度二进制 [42 字节]

时间类型具有以 t 开头的多字符格式字符串。

格式字符串

Arrow 数据类型

注释

tdD

date32 [天]

tdm

date64 [毫秒]

tts

time32 [秒]

ttm

time32 [毫秒]

ttu

time64 [微秒]

ttn

time64 [纳秒]

tss:...

带时区“...”的 timestamp [秒]

(1)

tsm:...

带时区“...”的 timestamp [毫秒]

(1)

tsu:...

带时区“...”的 timestamp [微秒]

(1)

tsn:...

带时区“...”的 timestamp [纳秒]

(1)

tDs

duration [秒]

tDm

duration [毫秒]

tDu

duration [微秒]

tDn

duration [纳秒]

tiM

interval [月]

tiD

interval [天，时间]

tin

interval [月，日，纳秒]

字典编码类型没有特定的格式字符串。相反，基础数组的格式字符串表示字典索引类型，并且值类型可以从依赖字典数组中读取（见下文“字典编码数组”）。

嵌套类型具有以 + 开头的多字符格式字符串。子字段的名称和类型从子数组中读取。

格式字符串

Arrow 数据类型

注释

+l

list

+L

large list

+vl

list-view

+vL

large list-view

+w:123

固定大小列表 [123 项]

+s

struct

+m

map

(2)

+ud:I,J,...

具有类型 ID I、J 等的密集联合

+us:I,J,...

具有类型 ID I、J 等的稀疏联合

+r

运行结束编码

(3)

注释

  1. 时区字符串在冒号 : 字符后按原样追加，没有任何引号。如果时区为空，则冒号 : 仍然必须包含。

  2. 如 Arrow 列式格式中所指定，map 类型具有一个名为 entries 的子类型，它本身是一个 (key, value) 的 2 个子结构类型。

  3. 如 Arrow 列式格式中所指定，运行结束编码类型有两个子类型，第一个是（整数）run_ends，第二个是 values。

示例#

  • 具有 int16 索引的字典编码 decimal128(precision = 12, scale = 5) 数组的格式字符串为 s，其依赖字典数组的格式字符串为 d:12,5。

  • 一个 list<uint64> 数组的格式字符串为 +l，其单个子类型的格式字符串为 L。

  • 一个 large_list_view<uint64> 数组的格式字符串为 +vL，其单个子类型的格式字符串为 L。

  • 一个 struct<ints: int32, floats: float32> 的格式字符串为 +s；其两个子类型分别名为 ints 和 floats，格式字符串分别为 i 和 f。

  • 一个 map<string, float64> 数组的格式字符串为 +m；其单个子类型名为 entries，格式字符串为 +s；其两个孙子类型分别名为 key 和 value，格式字符串分别为 u 和 g。

  • 具有类型 ID 4, 5 的 sparse_union<ints: int32, floats: float32> 的格式字符串为 +us:4,5；其两个子类型分别名为 ints 和 floats，格式字符串分别为 i 和 f。

  • 一个 run_end_encoded<int32, float32> 的格式字符串为 +r；其两个子类型分别名为 run_ends 和 values，格式字符串分别为 i 和 f。

结构定义#

以下独立定义足以在您的项目中支持 Arrow C 数据接口。与 Arrow 项目的其余部分一样，它们在 Apache License 2.0 下可用。

#ifndef ARROW_C_DATA_INTERFACE
#define ARROW_C_DATA_INTERFACE

#define ARROW_FLAG_DICTIONARY_ORDERED 1
#define ARROW_FLAG_NULLABLE 2
#define ARROW_FLAG_MAP_KEYS_SORTED 4

struct ArrowSchema {
  // Array type description
  const char* format;
  const char* name;
  const char* metadata;
  int64_t flags;
  int64_t n_children;
  struct ArrowSchema** children;
  struct ArrowSchema* dictionary;

  // Release callback
  void (*release)(struct ArrowSchema*);
  // Opaque producer-specific data
  void* private_data;
};

struct ArrowArray {
  // Array data description
  int64_t length;
  int64_t null_count;
  int64_t offset;
  int64_t n_buffers;
  int64_t n_children;
  const void** buffers;
  struct ArrowArray** children;
  struct ArrowArray* dictionary;

  // Release callback
  void (*release)(struct ArrowArray*);
  // Opaque producer-specific data
  void* private_data;
};

#endif  // ARROW_C_DATA_INTERFACE

注意

规范保护 ARROW_C_DATA_INTERFACE 旨在避免如果两个项目在其自己的头文件中复制 C 数据接口定义，而第三方项目从这两个项目中包含，则会发生重复定义。因此，在复制这些定义时，务必将此保护保留为原样。

ArrowSchema 结构#

ArrowSchema 结构描述了导出数组或记录批次的类型和元数据。它具有以下字段

const char *ArrowSchema.format#

必需。一个以 NULL 结尾的、UTF8 编码的字符串，描述数据类型。如果数据类型是嵌套的，则子类型不会在这里编码，而是在 ArrowSchema.children 结构中编码。

使用者可以决定不支持所有数据类型，但应记录此限制。

const char *ArrowSchema.name#

可选。一个以 NULL 结尾的、UTF8 编码的字符串，用于表示字段或数组名称。这主要用于重建嵌套类型的子字段。

生产者可以决定不提供此信息，使用者可以决定忽略此信息。如果省略，可以为 NULL 或空字符串。

const char *ArrowSchema.metadata#

可选。一个二进制字符串，描述类型的元数据。如果数据类型是嵌套的，则子类型不会在这里编码，而是在 ArrowSchema.children 结构中编码。

此字符串不是以 NULL 结尾的，而是遵循特定的格式。

int32: number of key/value pairs (noted N below)
int32: byte length of key 0
key 0 (not null-terminated)
int32: byte length of value 0
value 0 (not null-terminated)
...
int32: byte length of key N - 1
key N - 1 (not null-terminated)
int32: byte length of value N - 1
value N - 1 (not null-terminated)

整数以本机字节序存储。例如，元数据 [('key1', 'value1')] 在小端机器上编码为

\x01\x00\x00\x00\x04\x00\x00\x00key1\x06\x00\x00\x00value1

在大端机器上，同一个示例将编码为

\x00\x00\x00\x01\x00\x00\x00\x04key1\x00\x00\x00\x06value1

如果省略，此字段必须为 NULL（而不是空字符串）。

消费者可以选择忽略此信息。

int64_t ArrowSchema.flags#

可选。一个用于丰富类型描述的标志位字段。它的值是通过按位或运算各个标志值来计算的。以下标志可用

  • ARROW_FLAG_NULLABLE：此字段在语义上是否可以为空（无论它是否实际包含空值）。

  • ARROW_FLAG_DICTIONARY_ORDERED：对于字典编码类型，字典索引的顺序是否在语义上具有意义。

  • ARROW_FLAG_MAP_KEYS_SORTED：对于映射类型，每个映射值中的键是否已排序。

如果省略，必须为 0。

消费者可以选择忽略部分或所有标志。即使这样，他们也应该保留此值以便将其信息传播给自己的消费者。

int64_t ArrowSchema.n_children#

必需。此类型具有的子类型数量。

ArrowSchema **ArrowSchema.children#

可选。指向此类型每个子类型的指针的 C 数组。必须有 ArrowSchema.n_children 个指针。

仅当 ArrowSchema.n_children 为 0 时，才可以为 NULL。

ArrowSchema *ArrowSchema.dictionary#

可选。指向字典值的类型的指针。

如果 ArrowSchema 表示字典编码类型，则必须存在。否则必须为 NULL。

void (*ArrowSchema.release)(struct ArrowSchema*)#

必需。指向生产者提供的释放回调的指针。

有关内存管理和释放回调语义，请参见下文。

void *ArrowSchema.private_data#

可选。指向生产者提供的私有数据的指针。

消费者不应处理此成员。此成员的生命周期由生产者处理，尤其是由释放回调处理。

ArrowArray 结构#

ArrowArray 描述了导出数组或记录批次的数据。为了解释 ArrowArray 结构的类型，必须预先知道数组类型或记录批次模式。这可以通过约定实现——例如，始终生成相同数据类型的生产者 API——或者通过从侧面传递 ArrowSchema 实现。

它具有以下字段

int64_t ArrowArray.length#

必需。数组的逻辑长度（即它的项数）。

int64_t ArrowArray.null_count#

必需。数组中空项的数量。如果尚未计算，可以为 -1。

int64_t ArrowArray.offset#

必需。数组内的逻辑偏移量（即从物理起始位置到缓冲区的项数）。必须为 0 或正数。

生产者可以选择指定他们将只生成 0 偏移量数组以简化消费者代码的实现。消费者可以选择不支持非 0 偏移量数组，但他们应该记录这种限制。

int64_t ArrowArray.n_buffers#

必需。支持此数组的物理缓冲区数量。缓冲区数量是数据类型的函数，如 列式格式规范 中所述，但二进制或 UTF-8 视图类型除外，它比列式格式规范多一个缓冲区（请参阅 二进制视图数组）。

子数组的缓冲区不包括在内。

const void **ArrowArray.buffers#

必需。指向支持此数组的每个物理缓冲区起始位置的 C 数组。每个 void* 指针都是一个连续缓冲区的物理起始位置。必须有 ArrowArray.n_buffers 个指针。

生产者必须确保每个连续缓冲区都足够大，可以根据 列式格式规范 表示 length + offset 个编码的值。

建议（但不是必需）缓冲区的内存地址至少应根据它们包含的原始数据的类型进行对齐。消费者可以选择不支持未对齐的内存。

缓冲区指针仅在以下两种情况下可以为 null

  1. 对于空位图缓冲区，如果 ArrowArray.null_count 为 0；

  2. 对于任何缓冲区，如果相应缓冲区的大小（以字节为单位）为 0。

子数组的缓冲区不包括在内。

int64_t ArrowArray.n_children#

必需。此数组具有的子类型数量。子类型数量是数据类型的函数，如 列式格式规范 中所述。

ArrowArray **ArrowArray.children#

可选。指向此数组每个子数组的指针的 C 数组。必须有 ArrowArray.n_children 个指针。

仅当 ArrowArray.n_children 为 0 时，才可以为 NULL。

ArrowArray *ArrowArray.dictionary#

可选。指向字典值基础数组的指针。

如果 ArrowArray 表示字典编码数组，则必须存在。否则必须为 NULL。

void (*ArrowArray.release)(struct ArrowArray*)#

必需。指向生产者提供的释放回调的指针。

有关内存管理和释放回调语义，请参见下文。

void *ArrowArray.private_data#

可选。指向生产者提供的私有数据的指针。

消费者不应处理此成员。此成员的生命周期由生产者处理，尤其是由释放回调处理。

字典编码数组#

对于字典编码数组，ArrowSchema.format 字符串编码了索引类型。字典值类型可以从 ArrowSchema.dictionary 结构中读取。

对于 ArrowArray 结构也是如此：父结构指向索引数据，而 ArrowArray.dictionary 指向字典值数组。

扩展数组#

对于扩展数组，ArrowSchema.format 字符串编码了存储类型。关于扩展类型的信息在 ArrowSchema.metadata 字符串中进行编码，类似于 IPC 格式。具体而言，元数据键 ARROW:extension:name 编码了扩展类型名称，元数据键 ARROW:extension:metadata 编码了扩展类型的特定于实现的序列化（对于参数化扩展类型）。

从扩展数组导出的 ArrowArray 结构只是指向扩展数组的存储数据。

二进制视图数组#

对于二进制或 UTF-8 视图数组，会追加一个额外的缓冲区，该缓冲区将每个可变数据缓冲区的长度存储为 int64_t。此缓冲区是必需的，因为这些缓冲区长度不能从二进制或 UTF-8 视图类型的数组中的其他数据中轻松提取。

语义#

内存管理#

ArrowSchema 和 ArrowArray 结构遵循相同的内存管理约定。下面的术语“基本结构”指的是在生产者和消费者之间传递的 ArrowSchema 或 ArrowArray——而不是其任何子结构。

成员分配#

基本结构旨在由消费者在栈或堆上分配。在这种情况下，生产者 API 应获取指向消费者分配的结构的指针。

但是，结构指向的任何数据都必须由生产者分配和维护。这包括格式和元数据字符串、缓冲区和子指针数组等等。

因此，消费者不应尝试干预生产者对这些成员生命周期的处理。消费者影响数据生命周期的唯一方法是调用基本结构的 release 回调。

已释放的结构#

已释放的结构通过将其 release 回调设置为 NULL 来指示。在读取和解释结构的数据之前，消费者应该检查 NULL 释放回调，并相应地进行处理（可能通过报错）。

发布回调语义 - 针对消费者#

消费者 MUST 在不再使用基本结构时调用其发布回调，但它们 MUST 不调用其任何子级的发布回调（包括可选字典）。生产者负责释放子级。

在任何情况下，消费者 MUST 不再尝试在调用其发布回调后访问基本结构 - 包括任何关联数据，例如其子级。

发布回调语义 - 针对生产者#

如果生产者需要额外的生命周期处理信息（例如，C++ 生产者可能希望使用 shared_ptr 来管理数组和缓冲区的生命周期），它们 MUST 使用 private_data 成员来定位所需的簿记信息。

发布回调 MUST 不假设结构将位于与最初生产时相同的内存位置。消费者可以自由地移动结构（参见“移动数组”）。

发布回调 MUST 遍历所有子结构（包括可选字典）并调用它们自己的发布回调。

发布回调 MUST 释放结构直接拥有的任何数据区域（例如缓冲区和子成员）。

发布回调 MUST 通过将其 release 成员设置为 NULL，将结构标记为已释放。

下面是实现发布回调的良好起点，其中 TODO 区域必须填充生产者特定的释放代码

static void ReleaseExportedArray(struct ArrowArray* array) {
  // This should not be called on already released array
  assert(array->release != NULL);

  // Release children
  for (int64_t i = 0; i < array->n_children; ++i) {
    struct ArrowArray* child = array->children[i];
    if (child->release != NULL) {
      child->release(child);
      assert(child->release == NULL);
    }
  }

  // Release dictionary
  struct ArrowArray* dict = array->dictionary;
  if (dict != NULL && dict->release != NULL) {
    dict->release(dict);
    assert(dict->release == NULL);
  }

  // TODO here: release and/or deallocate all data directly owned by
  // the ArrowArray struct, such as the private_data.

  // Mark array released
  array->release = NULL;
}

移动数组#

消费者可以通过按位复制或浅层成员复制来移动 ArrowArray 结构。然后它 MUST 将源结构标记为已释放（有关如何操作，请参见上面的“已释放结构”），但不调用发布回调。这确保了在任何给定时间只有一个有效的结构副本处于活动状态，并且生命周期正确地传递给生产者。

像往常一样，当不再需要目标结构时，将调用其发布回调。

移动子数组#

还可以移动一个或多个子数组，但父 ArrowArray 结构 MUST 立即释放，因为它不再指向有效的子数组。

此操作的主要用例是仅使子数组的子集保持活动状态（例如，如果您只对数据的某些列感兴趣），而释放其他子数组。

注意

为了使移动正常工作，ArrowArray 结构必须是平凡的可重新定位的。因此，ArrowArray 结构（包括 private_data）内的指针成员 MUST 不指向结构本身。此外，生产者 MUST 不单独存储指向结构的外部指针。相反，生产者 MUST 使用 private_data 成员来记住任何必要的簿记信息。

记录批次#

记录批次可以简单地视为等效的结构数组。在这种情况下，顶层 ArrowSchema 的元数据可用于记录批次的模式级元数据。

可变性#

生产者和消费者 SHOULD 都认为导出的数据（即，通过 ArrowArray 的 buffers 成员可访问的数据）是不可变的，因为否则任何一方都可能在另一方对其进行变异时看到不一致的数据。

示例用例#

C++ 数据库引擎希望提供以 Arrow 格式交付结果的选项，但不会强加对 Arrow 软件库的依赖。使用 Arrow C 数据接口，引擎可以让人员传递指向 ArrowArray 结构的指针，并用下一块结果填充它。

它可以在不包含 Arrow C++ 头文件或链接到 Arrow DLL 的情况下做到这一点。此外，数据库引擎的 C API 可以通过例如 C FFI 层，让其他了解 Arrow C 数据接口的运行时和库从中受益。

C 生产者示例#

导出简单的 int32 数组#

导出具有空元数据的不可为空的 int32 类型。在这种情况下，所有 ArrowSchema 成员都指向静态分配的数据，因此发布回调很简单。

static void release_int32_type(struct ArrowSchema* schema) {
   // Mark released
   schema->release = NULL;
}

void export_int32_type(struct ArrowSchema* schema) {
   *schema = (struct ArrowSchema) {
      // Type description
      .format = "i",
      .name = "",
      .metadata = NULL,
      .flags = 0,
      .n_children = 0,
      .children = NULL,
      .dictionary = NULL,
      // Bookkeeping
      .release = &release_int32_type
   };
}

导出与 Arrow 数组类型相同的 C-malloc()ed 数组，通过发布回调将所有权转移给消费者

static void release_int32_array(struct ArrowArray* array) {
   assert(array->n_buffers == 2);
   // Free the buffers and the buffers array
   free((void *) array->buffers[1]);
   free(array->buffers);
   // Mark released
   array->release = NULL;
}

void export_int32_array(const int32_t* data, int64_t nitems,
                        struct ArrowArray* array) {
   // Initialize primitive fields
   *array = (struct ArrowArray) {
      // Data description
      .length = nitems,
      .offset = 0,
      .null_count = 0,
      .n_buffers = 2,
      .n_children = 0,
      .children = NULL,
      .dictionary = NULL,
      // Bookkeeping
      .release = &release_int32_array
   };
   // Allocate list of buffers
   array->buffers = (const void**) malloc(sizeof(void*) * array->n_buffers);
   assert(array->buffers != NULL);
   array->buffers[0] = NULL;  // no nulls, null bitmap can be omitted
   array->buffers[1] = data;
}

导出 struct<float32, utf8> 数组#

将数组类型导出为具有 C-malloc()ed 子级的 ArrowSchema

static void release_malloced_type(struct ArrowSchema* schema) {
   int i;
   for (i = 0; i < schema->n_children; ++i) {
      struct ArrowSchema* child = schema->children[i];
      if (child->release != NULL) {
         child->release(child);
      }
      free(child);
   }
   free(schema->children);
   // Mark released
   schema->release = NULL;
}

void export_float32_utf8_type(struct ArrowSchema* schema) {
   struct ArrowSchema* child;

   //
   // Initialize parent type
   //
   *schema = (struct ArrowSchema) {
      // Type description
      .format = "+s",
      .name = "",
      .metadata = NULL,
      .flags = 0,
      .n_children = 2,
      .dictionary = NULL,
      // Bookkeeping
      .release = &release_malloced_type
   };
   // Allocate list of children types
   schema->children = malloc(sizeof(struct ArrowSchema*) * schema->n_children);

   //
   // Initialize child type #0
   //
   child = schema->children[0] = malloc(sizeof(struct ArrowSchema));
   *child = (struct ArrowSchema) {
      // Type description
      .format = "f",
      .name = "floats",
      .metadata = NULL,
      .flags = ARROW_FLAG_NULLABLE,
      .n_children = 0,
      .dictionary = NULL,
      .children = NULL,
      // Bookkeeping
      .release = &release_malloced_type
   };

   //
   // Initialize child type #1
   //
   child = schema->children[1] = malloc(sizeof(struct ArrowSchema));
   *child = (struct ArrowSchema) {
      // Type description
      .format = "u",
      .name = "strings",
      .metadata = NULL,
      .flags = ARROW_FLAG_NULLABLE,
      .n_children = 0,
      .dictionary = NULL,
      .children = NULL,
      // Bookkeeping
      .release = &release_malloced_type
   };
}

将以 Arrow 兼容布局的 C-malloc()ed 数组导出为 Arrow 结构数组，将所有权转移给消费者

static void release_malloced_array(struct ArrowArray* array) {
   int i;
   // Free children
   for (i = 0; i < array->n_children; ++i) {
      struct ArrowArray* child = array->children[i];
      if (child->release != NULL) {
         child->release(child);
      }
      free(child);
   }
   free(array->children);
   // Free buffers
   for (i = 0; i < array->n_buffers; ++i) {
      free((void *) array->buffers[i]);
   }
   free(array->buffers);
   // Mark released
   array->release = NULL;
}

void export_float32_utf8_array(
      int64_t nitems,
      const uint8_t* float32_nulls, const float* float32_data,
      const uint8_t* utf8_nulls, const int32_t* utf8_offsets, const uint8_t* utf8_data,
      struct ArrowArray* array) {
   struct ArrowArray* child;

   //
   // Initialize parent array
   //
   *array = (struct ArrowArray) {
      // Data description
      .length = nitems,
      .offset = 0,
      .null_count = 0,
      .n_buffers = 1,
      .n_children = 2,
      .dictionary = NULL,
      // Bookkeeping
      .release = &release_malloced_array
   };
   // Allocate list of parent buffers
   array->buffers = malloc(sizeof(void*) * array->n_buffers);
   array->buffers[0] = NULL;  // no nulls, null bitmap can be omitted
   // Allocate list of children arrays
   array->children = malloc(sizeof(struct ArrowArray*) * array->n_children);

   //
   // Initialize child array #0
   //
   child = array->children[0] = malloc(sizeof(struct ArrowArray));
   *child = (struct ArrowArray) {
      // Data description
      .length = nitems,
      .offset = 0,
      .null_count = -1,
      .n_buffers = 2,
      .n_children = 0,
      .dictionary = NULL,
      .children = NULL,
      // Bookkeeping
      .release = &release_malloced_array
   };
   child->buffers = malloc(sizeof(void*) * child->n_buffers);
   child->buffers[0] = float32_nulls;
   child->buffers[1] = float32_data;

   //
   // Initialize child array #1
   //
   child = array->children[1] = malloc(sizeof(struct ArrowArray));
   *child = (struct ArrowArray) {
      // Data description
      .length = nitems,
      .offset = 0,
      .null_count = -1,
      .n_buffers = 3,
      .n_children = 0,
      .dictionary = NULL,
      .children = NULL,
      // Bookkeeping
      .release = &release_malloced_array
   };
   child->buffers = malloc(sizeof(void*) * child->n_buffers);
   child->buffers[0] = utf8_nulls;
   child->buffers[1] = utf8_offsets;
   child->buffers[2] = utf8_data;
}

为什么有两个不同的结构？#

在许多情况下，相同的类型或模式描述适用于多个，可能很短的数据批次。为了避免为每个批次导出和导入类型描述的成本，ArrowSchema 可以单独传递一次，在生产者和消费者之间的对话开始时。

在其他情况下，数据类型由生产者 API 固定，可能根本不需要传递。

但是，如果生产者专注于一次性数据交换，它可以在同一个 API 调用中传递 ArrowSchema 和 ArrowArray 结构。

更新此规范#

一旦此规范在官方 Arrow 版本中得到支持，C ABI 就被冻结。这意味着 ArrowSchema 和 ArrowArray 结构定义不应该以任何方式更改 - 包括添加新成员。

允许向后兼容的更改，例如新的 ArrowSchema.flags 值或 ArrowSchema.format 字符串的扩展可能性。

任何不兼容的更改都应包含在新规范中，例如“Arrow C 数据接口 v2”。

灵感#

Arrow C 数据接口的灵感来自 Python 缓冲协议，该协议已被证明在允许各种 Python 库交换数值数据方面取得了巨大成功，而无需彼此了解，并且适应成本接近于零。

特定于语言的协议#

一些语言可能会在 Arrow C 数据接口之上定义额外的协议。

本页内容
在 GitHub 上编辑