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 数组概念，以避免开发另一层封送（marshalling）层。

• 避免需要像 Java 和 Python 之间基于 JPype 的有限桥接那样的一对一适配层。

• 在无需对 Arrow 软件项目显式依赖（无论是编译时还是运行时）的情况下实现集成。

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

非目标

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

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

与 Arrow IPC 格式的比较

C 数据接口与 IPC 格式相比的优势

• 不依赖 Flatbuffers。

• 无需重新组装缓冲区（数据已按逻辑 Arrow 格式公开）。

• 设计上支持零拷贝。

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

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

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

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:...	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	大型列表
+vl	列表视图
+vL	大型列表视图
+w:123	定长列表 [123 项]
+s	结构体
+m	映射型 (map)	(2)
+ud:I,J,...	密集联合（dense union），类型 ID 为 I,J…
+us:I,J,...	稀疏联合（sparse union），类型 ID 为 I,J…
+r	游程编码（run-end encoded）	(3)

备注

1. 时区字符串原样追加在冒号 : 之后，不带任何引号。如果时区为空，仍必须包含冒号 :。

2. 按照 Arrow 列式格式规范，映射类型有一个名为 entries 的单一子类型，它本身是一个具有 (key, value) 的双子结构体类型。

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 个值。

建议但不强制要求缓冲区的内存地址至少按照其包含的原始数据类型进行对齐。消费者可以决定不支持未对齐的内存。

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

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 的释放回调，并相应地处理（通常是报错）。

释放回调语义 – 面向消费者

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

无论如何，消费者在调用其释放回调后，不得尝试再访问基础结构，包括其任何相关数据（如其子项）。

释放回调语义 – 面向生产者

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

释放回调不得假设结构将位于其最初产生时的相同内存位置。消费者可以随意移动结构（参见“移动数组”）。

释放回调必须遍历所有子结构（包括可选的字典）并调用它们自己的释放回调。

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

释放回调必须通过将其 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 结构。然后必须将源结构标记为已释放（有关如何操作，请参见上文的“已释放结构”），但不得调用释放回调。这确保了在任何给定时间只有一个活跃的结构副本，并且生命周期正确地传达给生产者。

与往常一样，当不再需要目标结构时，将在其上调用释放回调。

移动子数组

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

其主要用例是仅保持一部分子数组活跃（例如，如果您只对数据的某些列感兴趣），同时释放其他子数组。

注意

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

记录批次

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

可变性

生产者和消费者都应认为导出的数据（即可以通过 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() 分配的数组，通过释放回调将所有权转移给消费者

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
   };
}

以 Arrow 兼容布局导出 C-malloc() 分配的数组作为 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 数据接口之上定义额外的协议。

• Arrow PyCapsule 接口