Arrow 列式格式#

版本：1.5

另请参阅

自 1.0.0 版本以来 Arrow 列式格式的更新内容

Arrow 列式格式包含一种语言无关的内存中数据结构规范、元数据序列化以及一种用于序列化和通用数据传输的协议。

本文档旨在提供足够的细节，以便在无需现有实现的情况下创建该列式格式的新实现。我们利用 Google 的 Flatbuffers 项目进行元数据序列化，因此在阅读本文档时，有必要参考该项目的 Flatbuffers 协议定义文件。

列式格式具有一些关键特性

  • 用于顺序访问（扫描）的数据邻接性

  • O(1)（常量时间）随机访问 [1]

  • SIMD 和向量化友好

  • 无需“指针修补（pointer swizzling）”即可重定位，允许在共享内存中实现真正的零拷贝访问

Arrow 列式格式以相对昂贵的变异（mutation）操作为代价，提供了分析性能和数据局部性保证。本文档仅关注内存中数据表示和序列化细节；协调数据结构变异等问题留给各个实现来处理。

术语表#

由于不同的项目使用不同的词汇来描述各种概念，这里提供一个小词汇表以消除歧义。

  • 数组（Array） 或 向量（Vector）：具有已知长度且类型相同的值序列。这些术语在不同的 Arrow 实现中可以互换使用，但在本文档中我们使用“数组”。

  • 槽（Slot）：数组中某种特定数据类型的单个逻辑值。

  • 缓冲区（Buffer） 或 连续内存区域（Contiguous memory region）：具有给定长度的顺序虚拟地址空间。任何字节都可以通过小于区域长度的单个指针偏移量访问。

  • 物理布局（Physical Layout）：数组的底层内存布局，不考虑任何值语义。例如，32 位有符号整数数组和 32 位浮点数组具有相同的布局。

  • 数据类型（Data type）：面向应用的语义值类型，使用某种物理布局实现。例如，Decimal128 值以固定大小的二进制布局存储为 16 字节。时间戳可以存储为 64 位固定大小布局。

  • 原始类型（Primitive type）：没有子类型的数据类型。这包括固定位宽、变长二进制和空类型等。

  • 嵌套类型（Nested type）：其完整结构依赖于一个或多个其他子类型的数据类型。当且仅当它们的子类型相等时，两个完全指定的嵌套类型才相等。例如，List<U> 与 List<V> 不同，当且仅当 U 和 V 是不同的类型。

  • 父数组（Parent array） 和 子数组（child array）：用于表达嵌套类型结构中物理值数组之间关系的名称。例如，List<T> 类型父数组有一个 T 类型数组作为其子数组（有关列表的更多信息见下文）。

  • 参数化类型（Parametric type）：需要额外参数才能完全确定其语义的类型。例如，所有嵌套类型在构造上都是参数化的。时间戳也是参数化的，因为它需要单位（如微秒）和时区。

数据类型#

Schema.fbs 文件定义了 Arrow 列式格式支持的内置数据类型。每种数据类型都使用定义明确的物理布局。

Schema.fbs 是描述标准 Arrow 数据类型的权威来源。不过，为了方便起见，我们也提供了下表

类型

类型参数 (1)

物理内存布局

Null

Null

Boolean

固定大小原始类型

整数

  • 位宽

  • 符号性

“（同上）

浮点数

  • 精度

“

Decimal

  • 位宽

  • 精度

  • 精度

“

日期型 (Date)

  • 单位

“

时间

  • 位宽 (2)

  • 单位

“

Timestamp

  • 单位

  • 时区

“

间隔

  • 单位

“

持续时间

  • 单位

“

固定大小二进制

  • 字节宽度

固定大小二进制

Binary

带 32 位偏移量的变长二进制

Utf8 字符串

“

大型二进制

带 64 位偏移量的变长二进制

大字节 UTF8

“

二进制视图

带视图的变长二进制

带视图的 UTF8

“

固定大小列表

  • 值类型

  • 列表大小

固定大小列表

列表

  • 值类型

带 32 位偏移量的变长列表

大型列表

  • 值类型

带 64 位偏移量的变长列表

列表视图

  • 值类型

带 32 位偏移量和大小的变长列表视图

大型列表视图

  • 值类型

带 64 位偏移量和大小的变长列表视图

结构体

  • 子项

结构体

Map

  • 子项

  • 键排序性

变长结构体列表

联合

  • 子项

  • 模式

  • 类型 ID

稀疏或稠密联合类型 (3)

字典

  • 索引类型 (4)

  • 值类型

  • 有序性

字典编码

游程编码

  • 游程结束类型 (5)

  • 值类型

游程编码

  • (1) 斜体列出的类型参数表示数据类型的子类型。

  • (2) 时间类型的位宽参数在技术上是多余的，因为每个单位都强制要求单一的位宽。

  • (3) 联合类型是否使用稀疏或稠密布局由其模式（mode）参数指定。

  • (4) 字典类型的索引类型只能是整数类型，最好是有符号的，位宽为 8 到 64 位。

  • (5) 游程编码类型的游程结束类型只能是位宽为 16 到 64 位的有符号整数类型。

注意

有时，“逻辑类型”一词用于指代 Arrow 数据类型，以将它们与其各自的物理布局区分开来。然而，与 Apache Parquet 等其他类型系统不同，Arrow 类型系统没有物理类型和逻辑类型的单独概念。

Arrow 类型系统独立提供了 扩展类型，允许使用更丰富的面向应用的语义来标注标准 Arrow 数据类型（例如，定义一种建立在标准 String 数据类型之上的“JSON”类型）。

物理内存布局#

数组由少量元数据和数据定义

  • 数据类型。

  • 缓冲区序列。

  • 长度（64 位有符号整数）。实现可以限制为 32 位长度，详见下文。

  • 空值计数（64 位有符号整数）。

  • 可选的字典，用于字典编码数组。

嵌套数组还包含一个或多个此类项的序列，称为子数组。

每种数据类型都有定义明确的物理布局。以下是 Arrow 定义的不同物理布局

  • 原始（固定大小）：一系列值，每个值具有相同的字节或位宽度

  • 变长二进制：一系列值，每个值具有可变的字节长度。支持使用 32 位和 64 位长度编码的两种变体。

  • 变长二进制视图：一系列值，每个值具有可变的字节长度。与变长二进制不同，此布局的值分布在可能多个缓冲区中，而不是密集且顺序地打包在单个缓冲区中。

  • 固定大小列表：一种嵌套布局，其中每个值具有从子数据类型中获取的相同数量的元素。

  • 变长列表：一种嵌套布局，其中每个值是从子数据类型中获取的可变长度值序列。支持使用 32 位和 64 位长度编码的两种变体。

  • 变长列表视图：一种嵌套布局，其中每个值是从子数据类型中获取的可变长度值序列。此布局与变长列表的不同之处在于，它有一个额外的缓冲区，包含每个列表值的大小。这消除了偏移量缓冲区的约束——它不需要是有序的。

  • 结构体（Struct）：一种嵌套布局，由一系列命名的子字段集合组成，每个字段长度相同但类型可能不同。

  • 稀疏 和 稠密联合（Union）：一种嵌套布局，表示一系列值，其中每个值都可以从子数组类型集合中选择。

  • 字典编码：一种布局，由一系列整数（任意位宽）组成，代表指向可能为任何类型的字典的索引。

  • 游程编码（REE）：一种嵌套布局，由两个子数组组成，一个表示值，另一个表示相应值运行结束的逻辑索引。

  • 空（Null）：全为空值序列。

Arrow 列式内存布局仅适用于数据，不适用于元数据。实现可以自由地以对其方便的任何形式在内存中表示元数据。我们使用下述 Flatbuffers 以独立于实现的方式处理元数据序列化。

缓冲区对齐与填充#

建议实现在对齐的地址（8 或 64 字节的倍数）上分配内存，并填充（预分配）到 8 或 64 字节的倍数的长度。当为进程间通信序列化 Arrow 数据时，强制执行这些对齐和填充要求。如果可能，我们建议您优先使用 64 字节对齐和填充。除非另有说明，填充字节不需要具有特定值。

对齐要求遵循优化内存访问的最佳实践

  • 数值数组中的元素将保证通过对齐访问来获取。

  • 在某些体系结构上，对齐有助于限制部分使用的缓存行。

64 字节对齐的建议来自 Intel 性能指南，该指南建议内存对齐以匹配 SIMD 寄存器宽度。选择特定的填充长度是因为它匹配广泛部署的 x86 体系结构（Intel AVX-512）上可用的最大 SIMD 指令寄存器。

推荐的 64 字节填充允许在循环中持续使用 SIMD 指令，而无需额外的条件检查。这应该允许更简单、高效且对 CPU 缓存友好的代码。换句话说，我们可以将整个 64 字节缓冲区加载到 512 位宽的 SIMD 寄存器中，并在打包到 64 字节缓冲区中的所有列值上获得数据级并行性。有保证的填充还可以允许某些编译器直接生成更优化的代码（例如，可以安全地使用 Intel 的 -qopt-assume-safe-padding）。

数组长度#

数组长度在 Arrow 元数据中表示为 64 位有符号整数。不过，即使实现只支持最大 32 位有符号整数的长度，也被认为是有效的。如果在多语言环境中使用 Arrow，我们建议将长度限制为 2 31 - 1 个元素或更少。更大的数据集可以使用多个数组块来表示。

空值计数#

空值槽的数量是物理数组的一个属性，被视为数据结构的一部分。空值计数在 Arrow 元数据中表示为 64 位有符号整数，因为它可以与数组长度一样大。

有效性位图（Validity bitmaps）#

数组中的任何值在语义上都可以为空，无论是原始类型还是嵌套类型。

除联合类型（稍后详述）外，所有数组类型都使用专用的内存缓冲区（称为有效性位图或“空”位图）来编码每个值槽的空与非空状态。有效性位图必须足够大，以便为每个数组槽至少有 1 位。

任何数组槽是否有效（非空）都编码在此位图的相应位中。索引 j 处的 1（置位）表示值不为空，而 0（位未置位）表示它为空。位图应在分配时初始化为全部未置位（这包括填充）。

is_valid[j] -> bitmap[j / 8] & (1 << (j % 8))

我们使用 最低有效位 (LSB) 编号（也称为位字节序）。这意味着在 8 位组中，我们从右向左读取。

values = [0, 1, null, 2, null, 3]

bitmap
j mod 8   7  6  5  4  3  2  1  0
          0  0  1  0  1  0  1  1

空值计数为 0 的数组可以选择不分配有效性位图；如何表示取决于实现（例如，C++ 实现可以使用 NULL 指针表示这种“不存在”的有效性位图）。为方便起见，实现可以选择无论如何总是分配有效性位图。Arrow 数组的消费者应准备好处理这两种可能性。

嵌套类型数组（除上述联合类型外）拥有其自己的顶级有效性位图和空值计数，无论其子数组的空值计数和有效位如何。

空值数组槽不需要具有特定值；任何“掩码”内存都可以具有任何值，且不需要归零，尽管实现通常选择将空值的内存归零。

固定大小原始类型布局#

原始值数组表示一系列值，每个值具有相同的物理槽宽度（通常以字节为单位测量），尽管规范也提供位打包类型（例如以位编码的布尔值）。

在内部，数组包含一个连续的内存缓冲区，其总大小至少等于槽宽度乘以数组长度。对于位打包类型，大小向上取整到最接近的字节。

关联的有效性位图是连续分配的（如上所述），但在内存中不需要与值缓冲区相邻。

示例布局：Int32 数组

例如，一个 int32 的原始数组

[1, null, 2, 4, 8]

看起来如下

* Length: 5, Null count: 1
* Validity bitmap buffer:

  | Byte 0 (validity bitmap) | Bytes 1-63            |
  |--------------------------|-----------------------|
  | 00011101                 | 0 (padding)           |

* Value Buffer:

  | Bytes 0-3   | Bytes 4-7   | Bytes 8-11  | Bytes 12-15 | Bytes 16-19 | Bytes 20-63           |
  |-------------|-------------|-------------|-------------|-------------|-----------------------|
  | 1           | unspecified | 2           | 4           | 8           | unspecified (padding) |

示例布局：非空 int32 数组

[1, 2, 3, 4, 8] 有两种可能的布局

* Length: 5, Null count: 0
* Validity bitmap buffer:

  | Byte 0 (validity bitmap) | Bytes 1-63            |
  |--------------------------|-----------------------|
  | 00011111                 | 0 (padding)           |

* Value Buffer:

  | Bytes 0-3   | Bytes 4-7   | Bytes 8-11  | Bytes 12-15 | Bytes 16-19 | Bytes 20-63           |
  |-------------|-------------|-------------|-------------|-------------|-----------------------|
  | 1           | 2           | 3           | 4           | 8           | unspecified (padding) |

或者省略位图

* Length 5, Null count: 0
* Validity bitmap buffer: Not required
* Value Buffer:

  | Bytes 0-3   | Bytes 4-7   | Bytes 8-11  | bytes 12-15 | bytes 16-19 | Bytes 20-63           |
  |-------------|-------------|-------------|-------------|-------------|-----------------------|
  | 1           | 2           | 3           | 4           | 8           | unspecified (padding) |

变长二进制布局#

此布局中的每个值由 0 或更多字节组成。虽然原始数组有一个值缓冲区，但变长二进制有一个偏移量（offsets）缓冲区和一个数据（data）缓冲区。

偏移量缓冲区包含 length + 1 个有符号整数（取决于数据类型，为 32 位或 64 位），它们编码每个槽在数据缓冲区中的起始位置。每个槽中值的长度是使用该槽索引处的偏移量与后续偏移量之间的差值计算得出的。例如，槽 j 的位置和长度计算如下

slot_position = offsets[j]
slot_length = offsets[j + 1] - offsets[j]  // (for 0 <= j < length)

需要注意的是，空值可能具有正槽长度。也就是说，空值可能占用数据缓冲区中的非空内存空间。当这种情况发生时，相应内存空间的内容是未定义的。

偏移量必须是单调递增的，即对于 0 <= j < length，offsets[j+1] >= offsets[j]，即使对于空槽也是如此。此属性确保所有值的位置都是有效且定义明确的。

通常偏移量数组中的第一个槽为 0，最后一个槽是值数组的长度。序列化此布局时，我们建议将偏移量归一化为从 0 开始。

示例布局：``VarBinary``

['joe', null, null, 'mark']

表示如下

* Length: 4, Null count: 2
* Validity bitmap buffer:

  | Byte 0 (validity bitmap) | Bytes 1-63            |
  |--------------------------|-----------------------|
  | 00001001                 | 0 (padding)           |

* Offsets buffer:

  | Bytes 0-19     | Bytes 20-63           |
  |----------------|-----------------------|
  | 0, 3, 3, 3, 7  | unspecified (padding) |

 * Value buffer:

  | Bytes 0-6      | Bytes 7-63            |
  |----------------|-----------------------|
  | joemark        | unspecified (padding) |

变长二进制视图布局#

注意

Arrow 列式格式 1.4 新增

此布局中的每个值由 0 或更多字节组成。这些字节的位置使用视图（views）缓冲区指出，该缓冲区可能指向可能存在的多个数据（data）缓冲区之一，或者包含内联字符。

视图缓冲区包含 length 个视图结构，布局如下

* Short strings, length <= 12
  | Bytes 0-3  | Bytes 4-15                            |
  |------------|---------------------------------------|
  | length     | data (padded with 0)                  |

* Long strings, length > 12
  | Bytes 0-3  | Bytes 4-7  | Bytes 8-11 | Bytes 12-15 |
  |------------|------------|------------|-------------|
  | length     | prefix     | buf. index | offset      |

在长字符串和短字符串情况下，前四个字节编码字符串的长度，并可用于确定应如何解释视图的其余部分。

在短字符串情况下，字符串的字节被内联——存储在视图本身内部，即长度之后的十二个字节中。字符串本身之后的任何剩余字节都用 0 填充。

在长字符串情况下，缓冲区索引指示哪个数据缓冲区存储了数据字节，偏移量指示数据字节在该缓冲区中开始的位置。缓冲区索引 0 指的是第一个数据缓冲区，即有效性缓冲区和视图缓冲区之后的第一个缓冲区。半开区间 [offset, offset + length) 必须完全包含在指定的缓冲区内。字符串的前四个字节的副本存储在长度之后的内联前缀中。此外，此前缀为字符串比较实现了有利的快速路径，字符串比较通常在前四个字节内确定。

所有整数（长度、缓冲区索引和偏移量）都是有符号的。

此布局改编自慕尼黑工业大学的 UmbraDB。

请注意，此布局在 Arrow C 数据接口 中使用了一个额外的缓冲区来存储变长缓冲区长度。

变长列表布局#

List 是一个嵌套类型，在语义上类似于变长二进制。有两种列表布局变体——“list”和“list-view”——每种变体都可以由 32 位或 64 位偏移量整数分隔。

列表布局#

List 布局由两个缓冲区、一个有效性位图、一个偏移量缓冲区和一个子数组定义。偏移量与变长二进制情况相同，且 32 位和 64 位有符号整数偏移量都是支持的选项。这些偏移量不是引用额外的数据缓冲区，而是引用子数组。

与变长二进制布局类似，空值可能对应于子数组中的非空段。当这种情况发生时，相应段的内容可以是任意的。

列表类型指定为 List<T>，其中 T 是任何类型（原始或嵌套）。在这些示例中，我们使用 32 位偏移量，而 64 位偏移量版本将表示为 LargeList<T>。

示例布局：``List<Int8>`` 数组

我们展示一个长度为 4 且值为的 List<Int8> 示例

[[12, -7, 25], null, [0, -127, 127, 50], []]

将具有以下表示

* Length: 4, Null count: 1
* Validity bitmap buffer:

  | Byte 0 (validity bitmap) | Bytes 1-63            |
  |--------------------------|-----------------------|
  | 00001101                 | 0 (padding)           |

* Offsets buffer (int32)

  | Bytes 0-3  | Bytes 4-7   | Bytes 8-11  | Bytes 12-15 | Bytes 16-19 | Bytes 20-63           |
  |------------|-------------|-------------|-------------|-------------|-----------------------|
  | 0          | 3           | 3           | 7           | 7           | unspecified (padding) |

* Values array (Int8Array):
  * Length: 7,  Null count: 0
  * Validity bitmap buffer: Not required
  * Values buffer (int8)

    | Bytes 0-6                    | Bytes 7-63            |
    |------------------------------|-----------------------|
    | 12, -7, 25, 0, -127, 127, 50 | unspecified (padding) |

示例布局：``List<List<Int8>>``

[[[1, 2], [3, 4]], [[5, 6, 7], null, [8]], [[9, 10]]]

表示如下

* Length 3
* Nulls count: 0
* Validity bitmap buffer: Not required
* Offsets buffer (int32)

  | Bytes 0-3  | Bytes 4-7  | Bytes 8-11 | Bytes 12-15 | Bytes 16-63           |
  |------------|------------|------------|-------------|-----------------------|
  | 0          |  2         |  5         |  6          | unspecified (padding) |

* Values array (`List<Int8>`)
  * Length: 6, Null count: 1
  * Validity bitmap buffer:

    | Byte 0 (validity bitmap) | Bytes 1-63  |
    |--------------------------|-------------|
    | 00110111                 | 0 (padding) |

  * Offsets buffer (int32)

    | Bytes 0-27           | Bytes 28-63           |
    |----------------------|-----------------------|
    | 0, 2, 4, 7, 7, 8, 10 | unspecified (padding) |

  * Values array (Int8):
    * Length: 10, Null count: 0
    * Validity bitmap buffer: Not required

      | Bytes 0-9                     | Bytes 10-63           |
      |-------------------------------|-----------------------|
      | 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 | unspecified (padding) |

ListView 布局#

注意

Arrow 列式格式 1.4 新增

ListView 布局由三个缓冲区定义：一个有效性位图、一个偏移量缓冲区和一个额外的大小缓冲区。大小和偏移量具有相同的位宽，且支持 32 位和 64 位有符号整数选项。

与 List 布局一样，偏移量编码了每个槽在子数组中的起始位置。与 List 布局不同的是，列表长度显式存储在大小缓冲区中，而不是推断出来的。这允许偏移量无序。子数组的元素不必按照它们在父数组的列表元素中逻辑出现的顺序存储。

每个列表视图值（包括空值）都必须保证以下不变量

0 <= offsets[i] <= length of the child array
0 <= offsets[i] + size[i] <= length of the child array

列表视图类型指定为 ListView<T>，其中 T 是任何类型（原始或嵌套）。在这些示例中，我们使用 32 位偏移量和大小，而 64 位版本将表示为 LargeListView<T>。

示例布局：``ListView<Int8>`` 数组

我们展示一个长度为 4 且值为的 ListView<Int8> 示例

[[12, -7, 25], null, [0, -127, 127, 50], []]

它可能具有以下表示

* Length: 4, Null count: 1
* Validity bitmap buffer:

  | Byte 0 (validity bitmap) | Bytes 1-63            |
  |--------------------------|-----------------------|
  | 00001101                 | 0 (padding)           |

* Offsets buffer (int32)

  | Bytes 0-3  | Bytes 4-7   | Bytes 8-11  | Bytes 12-15 | Bytes 16-63           |
  |------------|-------------|-------------|-------------|-----------------------|
  | 0          | 7           | 3           | 0           | unspecified (padding) |

* Sizes buffer (int32)

  | Bytes 0-3  | Bytes 4-7   | Bytes 8-11  | Bytes 12-15 | Bytes 16-63           |
  |------------|-------------|-------------|-------------|-----------------------|
  | 3          | 0           | 4           | 0           | unspecified (padding) |

* Values array (Int8Array):
  * Length: 7,  Null count: 0
  * Validity bitmap buffer: Not required
  * Values buffer (int8)

    | Bytes 0-6                    | Bytes 7-63            |
    |------------------------------|-----------------------|
    | 12, -7, 25, 0, -127, 127, 50 | unspecified (padding) |

示例布局：``ListView<Int8>`` 数组

我们继续使用 ListView<Int8> 类型，但此实例说明了无序偏移量和子数组值的共享。这是一个长度为 5 且具有逻辑值的数组

[[12, -7, 25], null, [0, -127, 127, 50], [], [50, 12]]

它可能具有以下表示

* Length: 5, Null count: 1
* Validity bitmap buffer:

  | Byte 0 (validity bitmap) | Bytes 1-63            |
  |--------------------------|-----------------------|
  | 00011101                 | 0 (padding)           |

* Offsets buffer (int32)

  | Bytes 0-3  | Bytes 4-7   | Bytes 8-11  | Bytes 12-15 | Bytes 16-19 | Bytes 20-63           |
  |------------|-------------|-------------|-------------|-------------|-----------------------|
  | 4          | 7           | 0           | 0           | 3           | unspecified (padding) |

* Sizes buffer (int32)

  | Bytes 0-3  | Bytes 4-7   | Bytes 8-11  | Bytes 12-15 | Bytes 16-19 | Bytes 20-63           |
  |------------|-------------|-------------|-------------|-------------|-----------------------|
  | 3          | 0           | 4           | 0           | 2           | unspecified (padding) |

* Values array (Int8Array):
  * Length: 7,  Null count: 0
  * Validity bitmap buffer: Not required
  * Values buffer (int8)

    | Bytes 0-6                    | Bytes 7-63            |
    |------------------------------|-----------------------|
    | 0, -127, 127, 50, 12, -7, 25 | unspecified (padding) |

固定大小列表布局#

固定大小列表是一种嵌套类型，其中每个数组槽包含一系列固定大小且类型相同的值。

固定大小列表类型指定为 FixedSizeList<T>[N]，其中 T 是任何类型（原始或嵌套），N 是表示列表长度的 32 位有符号整数。

固定大小列表数组由一个值数组表示，该数组是 T 类型的子数组。T 也可以是嵌套类型。固定大小列表数组的槽 j 中的值存储在值数组的 N 长切片中，从 j * N 的偏移量开始。

示例布局：``FixedSizeList<byte>[4]`` 数组

这里我们展示 FixedSizeList<byte>[4]。

对于一个长度为 4 的数组及其相应值

[[192, 168, 0, 12], null, [192, 168, 0, 25], [192, 168, 0, 1]]

将具有以下表示

* Length: 4, Null count: 1
* Validity bitmap buffer:

  | Byte 0 (validity bitmap) | Bytes 1-63            |
  |--------------------------|-----------------------|
  | 00001101                 | 0 (padding)           |

* Values array (byte array):
  * Length: 16,  Null count: 0
  * validity bitmap buffer: Not required

    | Bytes 0-3       | Bytes 4-7   | Bytes 8-15                      |
    |-----------------|-------------|---------------------------------|
    | 192, 168, 0, 12 | unspecified | 192, 168, 0, 25, 192, 168, 0, 1 |

结构体布局#

结构体是一种嵌套类型，由一系列有序的类型（可以是不同的）参数化，称为其字段。每个字段必须具有 UTF8 编码的名称，这些字段名称是类型元数据的一部分。

在物理上，结构体数组为每个字段都有一个子数组。子数组是独立的，不需要在内存中彼此相邻。结构体数组还有一个有效性位图来编码顶级有效性信息。

例如，结构体（此处字段名称显示为字符串以供说明）

Struct <
  name: VarBinary
  age: Int32
>

有两个子数组，一个 VarBinary 数组（使用变长二进制布局）和一个具有 Int32 逻辑类型的 4 字节原始值数组。

示例布局：``Struct<VarBinary, Int32>``

布局为 [{'joe', 1}, {null, 2}, null, {'mark', 4}]，且子数组为 ['joe', null, 'alice', 'mark'] 和 [1, 2, null, 4]，布局将是

* Length: 4, Null count: 1
* Validity bitmap buffer:

  | Byte 0 (validity bitmap) | Bytes 1-63            |
  |--------------------------|-----------------------|
  | 00001011                 | 0 (padding)           |

* Children arrays:
  * field-0 array (`VarBinary`):
    * Length: 4, Null count: 1
    * Validity bitmap buffer:

      | Byte 0 (validity bitmap) | Bytes 1-63            |
      |--------------------------|-----------------------|
      | 00001101                 | 0 (padding)           |

    * Offsets buffer:

      | Bytes 0-19     | Bytes 20-63           |
      |----------------|-----------------------|
      | 0, 3, 3, 8, 12 | unspecified (padding) |

     * Value buffer:

      | Bytes 0-11     | Bytes 12-63           |
      |----------------|-----------------------|
      | joealicemark   | unspecified (padding) |

  * field-1 array (int32 array):
    * Length: 4, Null count: 1
    * Validity bitmap buffer:

      | Byte 0 (validity bitmap) | Bytes 1-63            |
      |--------------------------|-----------------------|
      | 00001011                 | 0 (padding)           |

    * Value Buffer:

      | Bytes 0-3   | Bytes 4-7   | Bytes 8-11  | Bytes 12-15 | Bytes 16-63           |
      |-------------|-------------|-------------|-------------|-----------------------|
      | 1           | 2           | unspecified | 4           | unspecified (padding) |

结构体有效性#

结构体数组有其自己的有效性位图，独立于其子数组的有效性位图。结构体数组的有效性位图可能会在其中一个或多个子数组在相应槽中具有非空值时指示为空；或者相反，子数组可能会在其有效性位图中指示为空，而结构体数组的有效性位图显示为非空。

因此，要了解特定的子项条目是否有效，必须对两个有效性位图（结构体数组的和子数组的）中的相应位进行逻辑与运算。

这在上面的示例中得到了说明，其中一个子数组对于空结构体有一个有效的条目 'alice'，但它被结构体数组的有效性位图“隐藏”了。然而，当独立处理时，子数组的相应条目将是非空的。

联合布局#

联合类型由一系列有序的类型定义；联合中的每个槽都可以具有从这些类型中选择的值。这些类型像结构体的字段一样命名，名称是类型元数据的一部分。

与其他数据类型不同，联合没有自己的有效性位图。相反，每个槽的空状态完全由组成联合的子数组决定。

我们定义了两种不同的联合类型，“稠密”和“稀疏”，它们针对不同的用例进行了优化。

稠密联合#

稠密联合代表一个混合类型的数组，每个值有 5 字节的开销。其物理布局如下

  • 每种类型对应一个子数组

  • 类型缓冲区：一个 8 位有符号整数缓冲区。联合中的每种类型都有一个对应的类型 ID，其值可以在此缓冲区中找到。具有超过 128 种可能类型的联合可以建模为联合的联合。

  • 偏移量缓冲区：一个有符号 Int32 值缓冲区，指示给定槽中该类型的相应子数组中的相对偏移量。每个子值数组的相应偏移量必须按顺序/递增。

示例布局：``DenseUnion<f: Float32, i: Int32>``

对于联合数组

[{f=1.2}, null, {f=3.4}, {i=5}]

将具有以下布局

* Length: 4, Null count: 0
* Types buffer:

  | Byte 0   | Byte 1      | Byte 2   | Byte 3   | Bytes 4-63            |
  |----------|-------------|----------|----------|-----------------------|
  | 0        | 0           | 0        | 1        | unspecified (padding) |

* Offset buffer:

  | Bytes 0-3 | Bytes 4-7   | Bytes 8-11 | Bytes 12-15 | Bytes 16-63           |
  |-----------|-------------|------------|-------------|-----------------------|
  | 0         | 1           | 2          | 0           | unspecified (padding) |

* Children arrays:
  * Field-0 array (f: Float32):
    * Length: 3, Null count: 1
    * Validity bitmap buffer: 00000101

    * Value Buffer:

      | Bytes 0-11     | Bytes 12-63           |
      |----------------|-----------------------|
      | 1.2, null, 3.4 | unspecified (padding) |


  * Field-1 array (i: Int32):
    * Length: 1, Null count: 0
    * Validity bitmap buffer: Not required

    * Value Buffer:

      | Bytes 0-3 | Bytes 4-63            |
      |-----------|-----------------------|
      | 5         | unspecified (padding) |

稀疏联合#

稀疏联合与稠密联合结构相同，但省略了偏移量数组。在这种情况下，子数组的长度均等于联合的长度。

虽然稀疏联合与稠密联合相比可能占用显著更多的空间，但它具有在某些用例中可能需要的优点

  • 在某些用例中，稀疏联合更适合向量化表达式求值。

  • 等长数组可以通过仅定义类型数组来解释为联合。

示例布局：``SparseUnion<i: Int32, f: Float32, s: VarBinary>``

对于联合数组

[{i=5}, {f=1.2}, {s='joe'}, {f=3.4}, {i=4}, {s='mark'}]

将具有以下布局

* Length: 6, Null count: 0
* Types buffer:

 | Byte 0     | Byte 1      | Byte 2      | Byte 3      | Byte 4      | Byte 5       | Bytes  6-63           |
 |------------|-------------|-------------|-------------|-------------|--------------|-----------------------|
 | 0          | 1           | 2           | 1           | 0           | 2            | unspecified (padding) |

* Children arrays:

  * i (Int32):
    * Length: 6, Null count: 4
    * Validity bitmap buffer:

      | Byte 0 (validity bitmap) | Bytes 1-63            |
      |--------------------------|-----------------------|
      | 00010001                 | 0 (padding)           |

    * Value buffer:

      | Bytes 0-3   | Bytes 4-7   | Bytes 8-11  | Bytes 12-15 | Bytes 16-19 | Bytes 20-23  | Bytes 24-63           |
      |-------------|-------------|-------------|-------------|-------------|--------------|-----------------------|
      | 5           | unspecified | unspecified | unspecified | 4           |  unspecified | unspecified (padding) |

  * f (Float32):
    * Length: 6, Null count: 4
    * Validity bitmap buffer:

      | Byte 0 (validity bitmap) | Bytes 1-63            |
      |--------------------------|-----------------------|
      | 00001010                 | 0 (padding)           |

    * Value buffer:

      | Bytes 0-3    | Bytes 4-7   | Bytes 8-11  | Bytes 12-15 | Bytes 16-19 | Bytes 20-23 | Bytes 24-63           |
      |--------------|-------------|-------------|-------------|-------------|-------------|-----------------------|
      | unspecified  | 1.2         | unspecified | 3.4         | unspecified | unspecified | unspecified (padding) |

  * s (`VarBinary`)
    * Length: 6, Null count: 4
    * Validity bitmap buffer:

      | Byte 0 (validity bitmap) | Bytes 1-63            |
      |--------------------------|-----------------------|
      | 00100100                 | 0 (padding)           |

    * Offsets buffer (Int32)

      | Bytes 0-3  | Bytes 4-7   | Bytes 8-11  | Bytes 12-15 | Bytes 16-19 | Bytes 20-23 | Bytes 24-27 | Bytes 28-63            |
      |------------|-------------|-------------|-------------|-------------|-------------|-------------|------------------------|
      | 0          | 0           | 0           | 3           | 3           | 3           | 7           | unspecified (padding)  |

    * Values buffer:

      | Bytes 0-6  | Bytes 7-63            |
      |------------|-----------------------|
      | joemark    | unspecified (padding) |

仅考虑数组中对应于类型索引的槽。所有“未选中”的值都将被忽略，并且可以是任何语义正确的数组值。

空布局#

我们为 Null 数据类型提供了一种简化的内存高效布局，其中所有值都为空。在这种情况下，不分配内存缓冲区。

字典编码布局#

字典编码是一种数据表示技术，通过引用字典（通常由唯一值组成）的整数来表示值。当您有大量重复值的数据时，它非常有效。

任何数组都可以进行字典编码。字典作为数组的可选属性存储。当字段被字典编码时，值由非负整数数组表示，这些整数表示值在字典中的索引。字典编码数组的内存布局与原始整数布局相同。字典作为具有各自布局的单独列式数组处理。

例如，您可以有以下数据

type: VarBinary

['foo', 'bar', 'foo', 'bar', null, 'baz']

以字典编码形式，这可能显示为

data VarBinary (dictionary-encoded)
   index_type: Int32
   values: [0, 1, 0, 1, null, 2]

dictionary
   type: VarBinary
   values: ['foo', 'bar', 'baz']

请注意，字典允许包含重复值或空值

data VarBinary (dictionary-encoded)
   index_type: Int32
   values: [0, 1, 3, 1, 4, 2]

dictionary
   type: VarBinary
   values: ['foo', 'bar', 'baz', 'foo', null]

此类数组的空值计数仅由其索引的有效性位图决定，与字典中的任何空值无关。

由于无符号整数在某些情况下（例如在 JVM 中）可能更难处理，我们建议在表示字典索引时优先使用有符号整数而不是无符号整数。此外，除非应用程序需要，我们建议避免使用 64 位无符号整数索引。

我们在下文中讨论与序列化相关的字典编码。

游程编码布局#

注意

Arrow 列式格式 1.3 新增

游程编码 (REE) 是游程长度编码 (RLE) 的一种变体。这些编码非常适合表示包含相同值序列（称为游程）的数据。在游程编码中，每个游程表示为一个值和一个给出游程结束位置索引的整数。

任何数组都可以进行游程编码。游程编码数组本身没有缓冲区，但有两个子数组。第一个子数组称为游程结束数组，保存 16、32 或 64 位有符号整数。每个游程的实际值保存在第二个子数组中。为了确定字段名称和模式，这些子数组被指定为 run_ends 和 values 的标准名称。

第一个子数组中的值代表从第一个游程到当前游程的累计长度，即当前游程结束的逻辑索引。这允许使用二分查找从逻辑索引进行相对高效的随机访问。单个游程的长度可以通过减去两个相邻的值来确定。（这与游程长度编码形成对比，后者直接表示游程长度，且随机访问效率较低。）

注意

由于 run_ends 子数组不能有空值，因此考虑为什么 run_ends 是子数组而不是像 变长列表布局 的偏移量那样的缓冲区是合理的。此布局已被考虑过，但决定使用子数组。

子数组允许我们保持与父数组关联的“逻辑长度”（解码长度）和与子数组关联的“物理长度”（游程结束的数量）。如果 run_ends 是父数组中的缓冲区，那么缓冲区的大小将与数组长度无关，这会令人困惑。

游程的长度必须至少为 1。这意味着游程结束数组中的值都是正数且严格递增。游程结束不能为 null。

REE 父项没有有效性位图，其空值计数域应始终为 0。空值被编码为值为 null 的游程。

例如，您可以有以下数据

type: Float32
[1.0, 1.0, 1.0, 1.0, null, null, 2.0]

在游程编码形式中，这可能显示为

* Length: 7, Null count: 0
* Child Arrays:

  * run_ends (Int32):
    * Length: 3, Null count: 0 (Run Ends cannot be null)
    * Validity bitmap buffer: Not required (if it exists, it should be all 1s)
    * Values buffer

      | Bytes 0-3   | Bytes 4-7   | Bytes 8-11  | Bytes 12-63           |
      |-------------|-------------|-------------|-----------------------|
      | 4           | 6           | 7           | unspecified (padding) |

  * values (Float32):
    * Length: 3, Null count: 1
    * Validity bitmap buffer:

      | Byte 0 (validity bitmap) | Bytes 1-63            |
      |--------------------------|-----------------------|
      | 00000101                 | 0 (padding)           |

    * Values buffer

      | Bytes 0-3   | Bytes 4-7   | Bytes 8-11  | Bytes 12-63           |
      |-------------|-------------|-------------|-----------------------|
      | 1.0         | unspecified | 2.0         | unspecified (padding) |

每种布局的缓冲区列表#

为了避免歧义，我们提供了每种布局的内存缓冲区顺序和类型的列表。

缓冲区布局#

布局类型

缓冲区 0

缓冲区 1

缓冲区 2

变长缓冲区

原生

有效性

数据

变长二进制

有效性

偏移量

数据

变长二进制视图

有效性

视图

数据

列表

有效性

偏移量

列表视图

有效性

偏移量

大小

固定大小列表

有效性

结构体

有效性

稀疏联合

类型 ID

密集联合体

类型 ID

偏移量

Null

字典编码

有效性

数据（索引）

游程编码 (Run-end encoded)

序列化与进程间通信 (IPC)#

列式格式中序列化数据的原始单位是“记录批次（record batch）”。在语义上，记录批次是数组的有序集合，称为其字段，每个字段长度相同但数据类型可能不同。记录批次的字段名称和类型共同构成了批次的模式（schema）。

在本节中，我们定义了一种将记录批次序列化为二进制有效负载流，并从这些有效负载重建记录批次而无需内存拷贝的协议。

列式 IPC 协议利用这些类型的二进制消息的单向流

  • Schema

  • RecordBatch

  • DictionaryBatch

我们定义了一种所谓的封装 IPC 消息格式，其中包含序列化的 Flatbuffer 类型以及可选的消息体。我们在描述如何序列化每个组成的 IPC 消息类型之前定义此消息格式。

封装消息格式#

对于简单的流式和基于文件的序列化，我们为进程间通信定义了一种“封装”消息格式。此类消息可以通过仅检查消息元数据来“反序列化”为内存中的 Arrow 数组对象，而无需复制或移动任何实际数据。

封装的二进制消息格式如下

  • 32 位连续性指示符。值 0xFFFFFFFF 表示有效消息。此组件在 0.15.0 版本中引入，部分是为了解决 Flatbuffers 的 8 字节对齐要求。

  • 指示元数据大小的 32 位小端长度前缀

  • 使用 Message.fbs 中定义的 Message 类型的消息元数据

  • 到 8 字节边界的填充字节

  • 消息体，其长度必须是 8 字节的倍数

从示意图上看，我们有

<continuation: 0xFFFFFFFF>
<metadata_size: int32>
<metadata_flatbuffer: bytes>
<padding>
<message body>

完整的序列化消息必须是 8 字节的倍数，以便消息可以在流之间重定位。否则，元数据和消息体之间的填充量可能是非确定性的。

metadata_size 包括 Message 的大小加上填充。metadata_flatbuffer 包含序列化的 Message Flatbuffer 值，它在内部包括

  • 版本号

  • 特定的消息值（Schema、RecordBatch 或 DictionaryBatch 之一）

  • 消息体的大小

  • 用于任何应用程序提供的元数据的 custom_metadata 字段

当从输入流读取时，通常首先解析和验证 Message 元数据以获取体大小。然后可以读取该体。

Schema 消息#

Flatbuffers 文件 Schema.fbs 包含所有内置数据类型的定义以及表示给定记录批次模式的 Schema 元数据类型。模式由字段的有序序列组成，每个字段都有名称和类型。序列化的 Schema 不包含任何数据缓冲区，仅包含类型元数据。

Field Flatbuffers 类型包含单个数组的元数据。这包括

  • 字段的名称

  • 字段的数据类型

  • 字段在语义上是否可为空。虽然这对数组的物理布局没有影响，但许多系统区分可为空和不可为空的字段，我们希望允许它们保留此元数据以实现忠实的模式往返。

  • 嵌套类型的子 Field 值集合

  • dictionary 属性，指示字段是否经过字典编码。如果是，则分配一个字典“id”，以允许将后续字典 IPC 消息与相应的字段匹配。

我们还提供了模式级和字段级的 custom_metadata 属性，允许系统插入自己的应用程序定义元数据以自定义行为。

RecordBatch 消息#

RecordBatch 消息包含对应于由模式确定的物理内存布局的实际数据缓冲区。此消息的元数据提供了每个缓冲区的位置和大小，允许使用指针运算重建数组数据结构，从而无需内存拷贝。

记录批次的序列化形式如下

  • data header，在 Message.fbs 中定义为 RecordBatch 类型。

  • body，一个扁平的内存缓冲区序列，端到端写入，并带有适当的填充，以确保至少 8 字节的对齐。

数据头包含以下内容

  • 记录批次中每个扁平化字段的长度和空值计数

  • 记录批次体中每个组成 Buffer 的内存偏移量和长度

字段和缓冲区是通过对记录批次中的字段进行前序深度优先遍历进行扁平化的。例如，让我们考虑模式

col1: Struct<a: Int32, b: List<item: Int64>, c: Float64>
col2: Utf8

扁平化的版本是

FieldNode 0: Struct name='col1'
FieldNode 1: Int32 name='a'
FieldNode 2: List name='b'
FieldNode 3: Int64 name='item'
FieldNode 4: Float64 name='c'
FieldNode 5: Utf8 name='col2'

对于产生的缓冲区，我们将有以下内容（参考上表）

buffer 0: field 0 validity
buffer 1: field 1 validity
buffer 2: field 1 values
buffer 3: field 2 validity
buffer 4: field 2 offsets
buffer 5: field 3 validity
buffer 6: field 3 values
buffer 7: field 4 validity
buffer 8: field 4 values
buffer 9: field 5 validity
buffer 10: field 5 offsets
buffer 11: field 5 data

Buffer Flatbuffers 值描述了一块内存的位置和大小。通常这些是相对于下面定义的封装消息格式进行解释的。

Buffer 的 size 字段不需要考虑填充字节。由于此元数据可用于在库之间传达内存指针地址，建议将 size 设置为实际内存大小而不是填充大小。

变长缓冲区（Variadic buffers）#

注意

Arrow 列式格式 1.4 新增

一些类型（如 Utf8View）使用可变数量的缓冲区表示。对于预排序的扁平化逻辑模式中的每个此类 Field，variadicBufferCounts 中都会有一个条目，以指示在该 RecordBatch 中属于该 Field 的变长缓冲区数量。

例如，考虑模式

col1: Struct<a: Int32, b: BinaryView, c: Float64>
col2: Utf8View

这有两个带有变长缓冲区的字段，因此 variadicBufferCounts 在每个 RecordBatch 中将有两个条目。对于具有 variadicBufferCounts = [3, 2] 的此模式的 RecordBatch，扁平化的缓冲区将是

buffer 0:  col1    validity
buffer 1:  col1.a  validity
buffer 2:  col1.a  values
buffer 3:  col1.b  validity
buffer 4:  col1.b  views
buffer 5:  col1.b  data
buffer 6:  col1.b  data
buffer 7:  col1.b  data
buffer 8:  col1.c  validity
buffer 9:  col1.c  values
buffer 10: col2    validity
buffer 11: col2    views
buffer 12: col2    data
buffer 13: col2    data

压缩#

记录批次体缓冲区有三种不同的压缩选项：缓冲区可以是未压缩的，缓冲区可以用 lz4 压缩编解码器压缩，或者缓冲区可以用 zstd 压缩编解码器压缩。消息体扁平序列中的缓冲区必须使用相同的编解码器单独压缩。压缩缓冲区序列中的特定缓冲区可以保持未压缩状态（例如，如果压缩这些特定缓冲区不能显著减小其大小）。

所使用的压缩类型定义在 RecordBatch 消息 的 data header 中，在可选的 compression 字段中，默认为未压缩。

注意

lz4 压缩编解码器意味着 LZ4 帧格式，不应与 “原始”（也称为“块”）格式 混淆。

序列化形式中压缩缓冲区和未压缩缓冲区之间的区别如下

  • 如果 RecordBatch 消息 中的缓冲区是压缩的

    • data header 包括记录批次体中每个压缩缓冲区的长度和内存偏移量，以及压缩类型

    • body 包括一个压缩缓冲区的扁平序列，以及作为序列中每个缓冲区前 8 个字节存储的 64 位小端有符号整数的未压缩缓冲区长度。此未压缩长度可以设置为 -1 以指示该特定缓冲区保持未压缩状态。

  • 如果 RecordBatch 消息 中的缓冲区是未压缩的

    • data header 包括记录批次体中每个未压缩缓冲区的长度和内存偏移量

    • body 包括一个未压缩缓冲区的扁平序列。

注意

一些 Arrow 实现缺乏使用上述一个或两个编解码器生成和消费带有压缩缓冲区的 IPC 数据支持。详情请参阅 实现状态。

一些应用程序可能会在其用于存储或传输 Arrow IPC 数据的协议中应用压缩。（例如，HTTP 服务器可能会提供 gzip 压缩的 Arrow IPC 流。）已经在其存储或传输协议中使用压缩的应用程序应避免使用缓冲区压缩。双重压缩通常会降低性能，并且不会实质性提高压缩比。

字节顺序 (Endianness)#

Arrow 格式默认采用小端序。

序列化的 Schema 元数据有一个字节序字段，指示 RecordBatch 的字节序。通常这是生成 RecordBatch 的系统的字节序。主要用例是在具有相同字节序的系统之间交换 RecordBatch。起初，当尝试读取字节序与底层系统不匹配的 Schema 时，我们将返回错误。参考实现专注于小端序并为其提供测试。最终我们可能会通过字节交换提供自动转换。

IPC 流式格式#

我们为记录批次提供了一种流式协议或“格式”。它呈现为封装消息的序列，每个消息都遵循上述格式。Schema 在流中首先出现，并且对于随后出现的所有记录批次都是相同的。如果 Schema 中的任何字段是字典编码的，则将包含一个或多个 DictionaryBatch 消息。DictionaryBatch 和 RecordBatch 消息可以交错，但在 RecordBatch 中使用任何字典键之前，它应该在 DictionaryBatch 中定义。

<SCHEMA>
<DICTIONARY 0>
...
<DICTIONARY k - 1>
<RECORD BATCH 0>
...
<DICTIONARY x DELTA>
...
<DICTIONARY y DELTA>
...
<RECORD BATCH n - 1>
<EOS [optional]: 0xFFFFFFFF 0x00000000>

注意

当记录批次包含完全为空的字典编码数组时，会发生交错字典和记录批次的极端情况。在这种情况下，编码列的字典可能会在第一个记录批次之后出现。

当流读取器实现正在读取流时，在每条消息之后，它可能会读取接下来的 8 个字节，以确定流是否继续以及随后的消息元数据的大小。读取消息 flatbuffer 后，您就可以读取消息体。

流写入器可以通过写入包含 4 字节连续性指示符 (0xFFFFFFFF) 后跟 0 元数据长度 (0x00000000) 的 8 个字节，或者关闭流接口来发出流结束 (EOS) 信号。我们建议流式格式使用 “.arrows” 文件扩展名，尽管在许多情况下这些流永远不会作为文件存储。

IPC 文件格式#

我们定义了一种支持随机访问的“文件格式”，它是流格式的扩展。文件以魔术字符串 ARROW1（加上填充）开始和结束。文件中随后出现的内容与流格式相同。在文件末尾，我们写入一个页脚（footer），其中包含 Schema 的冗余副本（它是流格式的一部分）以及文件中每个数据块的内存偏移量和大小。这使得能够对文件中的任何记录批次进行随机访问。请参阅 File.fbs 以获取文件页脚的精确细节。

从示意图上看，我们有

<magic number "ARROW1">
<empty padding bytes [to 8 byte boundary]>
<STREAMING FORMAT with EOS>
<FOOTER>
<FOOTER SIZE: int32>
<magic number "ARROW1">

在文件格式中，不要求在 RecordBatch 中使用字典键之前，必须在 DictionaryBatch 中定义它们，只要这些键在文件中的某处定义即可。此外，每个字典 ID 拥有多个非增量字典批次是无效的（即不支持字典替换）。增量字典按照它们在文件页脚中出现的顺序应用。我们建议使用该格式创建的文件使用 “.arrow” 扩展名。请注意，以此格式创建的文件有时被称为 “Feather V2” 或带有 “.feather” 扩展名，该名称和扩展名源自 “Feather (V1)”，它是 Arrow 项目早期为 Python (pandas) 和 R 进行语言无关的快速数据帧存储的概念验证。

字典消息#

字典在流和文件格式中被写为一系列记录批次，每个批次都有一个字段。因此，一系列记录批次的完整语义模式由 Schema 以及所有字典组成。字典类型在 Schema 中找到，因此必须先读取 Schema 以确定字典类型，以便可以正确解释字典。

table DictionaryBatch {
  id: long;
  data: RecordBatch;
  isDelta: boolean = false;
}

消息元数据中的字典 id 可以在 Schema 中引用一次或多次，以便字典甚至可以用于多个字段。有关字典编码数据语义的更多信息，请参阅 字典编码布局 部分。

字典 isDelta 标志允许扩展现有字典以供未来的记录批次具体化。设置了 isDelta 的字典批次表明其向量应与之前具有相同 id 的任何批次的向量连接。在对一列进行编码的流中，字符串列表 ["A", "B", "C", "B", "D", "C", "E", "A"]，使用增量字典批次可以采取以下形式

<SCHEMA>
<DICTIONARY 0>
(0) "A"
(1) "B"
(2) "C"

<RECORD BATCH 0>
0
1
2
1

<DICTIONARY 0 DELTA>
(3) "D"
(4) "E"

<RECORD BATCH 1>
3
2
4
0
EOS

或者，如果 isDelta 设置为 false，则字典将替换相同 ID 的现有字典。使用与上述相同的示例，替代编码可以是

<SCHEMA>
<DICTIONARY 0>
(0) "A"
(1) "B"
(2) "C"

<RECORD BATCH 0>
0
1
2
1

<DICTIONARY 0>
(0) "A"
(1) "C"
(2) "D"
(3) "E"

<RECORD BATCH 1>
2
1
3
0
EOS

自定义应用程序元数据#

我们在三个级别提供 custom_metadata 字段，为开发人员提供了一种在 Arrow 协议消息中传递特定于应用程序的元数据的机制。这包括 Field、Schema 和 Message。

冒号符号 : 将用作命名空间分隔符。它可以在一个键中多次使用。

ARROW 模式是保留的命名空间，供 Arrow 内部在 custom_metadata 字段中使用。例如，ARROW:extension:name。

扩展类型#

用户定义的“扩展”类型可以通过在 Field 元数据结构的 custom_metadata 中设置某些 KeyValue 对来定义。这些扩展键是

  • 'ARROW:extension:name' 用于标识自定义数据类型的字符串名称。我们建议您为扩展类型名称使用“命名空间”样式的后缀，以最大限度地减少与同一应用程序中多个 Arrow 读取器和写入器发生冲突的可能性。例如，使用 myorg.name_of_type 而不仅仅是 name_of_type

  • 'ARROW:extension:metadata' 用于表示重构自定义类型所必需的 ExtensionType 的序列化表示

注意

以 arrow. 开头的扩展名称保留用于 规范扩展类型，不应用于第三方扩展类型。

此扩展元数据可以标注任何内置的 Arrow 逻辑类型。例如，Arrow 指定了一种规范扩展类型，将 UUID 表示为 FixedSizeBinary(16)。Arrow 实现不需要支持规范扩展，因此不支持此 UUID 类型的一个实现将简单地将其解释为 FixedSizeBinary(16) 并在后续 Arrow 协议消息中传递 custom_metadata。

扩展类型可能使用也可能不使用 'ARROW:extension:metadata' 字段。让我们考虑一些示例扩展类型

  • uuid 表示为具有空元数据的 FixedSizeBinary(16)

  • latitude-longitude 表示为 struct<latitude: double, longitude: double>，且元数据为空

  • tensor（多维数组）存储为 Binary 值，并具有指示每个值的数据类型和形状的序列化元数据。这可能是类似于 {'type': 'int8', 'shape': [4, 5]} 的 JSON，用于 4x5 单元张量。

  • trading-time 表示为 Timestamp，带有序列化的元数据，指示数据对应于市场交易日历

另请参阅

规范扩展类型

实现指南#

执行引擎（或框架、UDF 执行器、存储引擎等）可以在以下约束条件下仅实现 Arrow 规范的子集和/或对其进行扩展

实现规范的子集#

  • 如果仅产生（不消费）arrow 向量：可以实现向量规范及其相应元数据的任何子集。

  • 如果消费和产生向量：需要支持向量的最小子集。产生向量及其相应元数据的子集总是可以的。消费向量时应至少将不受支持的输入向量转换为支持的子集（例如 Timestamp.millis 到 timestamp.micros，或者 int32 到 int64）。

可扩展性#

执行引擎实现者也可以在内部扩展其内存表示，只要它们从未被暴露即可。在将数据发送到期望 Arrow 数据的另一个系统之前，这些自定义向量应转换为 Arrow 规范中存在的类型。