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 数据接口可以成为运行时共享列式数据的底层通用语言（lingua franca），并将 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	大二进制
vz	二进制视图
u	utf-8 字符串
U	大 utf-8 字符串
vu	utf-8 视图
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:...	带时区“...”的时间戳 [秒]	(1)
tsm:...	带时区“...”的时间戳 [毫秒]	(1)
tsu:...	带时区“...”的时间戳 [微秒]	(1)
tsn:...	带时区“...”的时间戳 [纳秒]	(1)
tDs	duration [秒]
tDm	duration [毫秒]
tDu	duration [微秒]
tDn	duration [纳秒]
tiM	interval [月]
tiD	interval [天, 时间]
tin	interval [月, 日, 纳秒]

字典编码的类型没有特定的格式字符串。相反，基本数组的格式字符串代表字典索引类型，值类型可以从相关的字典数组中读取（参见下文“字典编码数组”）。

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

格式字符串	Arrow 数据类型	备注
+l	列表型 (list)
+L	大列表
+vl	列表视图
+vL	大列表视图
+w:123	固定大小列表 [123 个元素]
+s	结构体
+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 许可证 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

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

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

const char *ArrowSchema.name

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

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

const char *ArrowSchema.metadata

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

此字符串不是空终止的，但遵循特定格式

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

可选。一个位域标志，用于丰富类型描述。其值是通过对标志值进行 OR 运算得到的。以下标志可用

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

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

• ARROW_FLAG_MAP_KEYS_SORTED：对于 map 类型，每个 map 值内的键是否已排序。

如果省略，则必须为 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，可以指示该结构体已被释放。在读取和解释结构体数据之前，消费者**应该**检查 release 回调是否为 NULL，并相应地处理（可能通过报错退出）。

Release 回调语义——面向消费者

当消费者不再使用基结构体时，**必须**调用其 release 回调函数，但**不得**调用其任何子项的 release 回调函数（包括可选的字典）。生产者负责释放子项。

在任何情况下，消费者在调用基结构体的 release 回调后，**不得**再尝试访问该基结构体——包括任何相关数据，例如其子项。

Release 回调语义——面向生产者

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

Release 回调**不得**假定结构体将位于与最初生产时相同的内存位置。消费者可以自由移动结构体（参见“移动数组”）。

Release 回调**必须**遍历所有子结构体（包括可选的字典）并调用它们各自的 release 回调函数。

Release 回调**必须**释放结构体直接拥有的任何数据区域（例如缓冲区和子项成员）。

Release 回调**必须**通过将其 release 成员设置为 NULL 来标记结构体已释放。

下面是一个实现 release 回调的良好起点，其中 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 结构体。然后，它**必须**将源结构体标记为已释放（请参阅上文“已释放的结构体”了解如何操作），但**不**调用 release 回调。这确保了在任何给定时间只有一个该结构体的活动副本，并且生命周期被正确地传达给生产者。

像往常一样，当目标结构体不再需要时，将调用其 release 回调函数。

移动子数组

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

这主要的用例是只保留子数组的一个子集（例如，如果您只对数据的某些列感兴趣），同时释放其他列。

注意

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

记录批次

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

可变性

生产者和消费者都**应该**认为导出的数据（即可以通过 ArrowArray 的 buffers 成员访问的数据）是不可变的，因为否则任何一方在另一方修改数据时都可能看到不一致的数据。

用例示例

一个 C++ 数据库引擎希望提供以 Arrow 格式交付结果的选项，但又不想强迫自己依赖 Arrow 软件库。通过 Arrow C 数据接口，该引擎可以允许调用者传入一个 ArrowArray 结构体的指针，并用结果的下一块数据填充它。

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

C 生产者示例

导出简单的 int32 数组

导出没有 Null 值的 int32 类型，并具有空元数据。在这种情况下，所有 ArrowSchema 成员都指向静态分配的数据，因此 release 回调是微不足道的。

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() 分配的数组，通过 release 回调将所有权转移给消费者

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() 分配的子项的 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
   };
}

将 C-malloc() 分配的、Arrow 兼容布局的数组导出为 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;
}

为什么有两种不同的结构体？

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

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

然而，如果生产者专注于一次性数据交换，它可以将 ArrowSchema 和 ArrowArray 结构体在同一个 API 调用中通信。

更新此规范

一旦此规范在官方 Arrow 版本中得到支持，C ABI 将被冻结。这意味着 ArrowSchema 和 ArrowArray 结构体的定义在任何方面都不应改变——包括添加新成员。

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

任何不兼容的更改都应作为新规范的一部分，例如“Arrow C 数据接口 v2”。

灵感

Arrow C 数据接口的灵感来源于 Python buffer protocol，该协议已被证明非常成功，它允许各种 Python 库在彼此之间交换数值数据，且几乎没有适应成本。

特定于语言的协议

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

• Arrow PyCapsule 接口