Arrow 列式格式#

版本：1.5

另请参阅

自 1.0.0 版本以来 Arrow 列式格式的 additions

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

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

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

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

  • O(1)（常数时间）随机访问

  • SIMD 和向量化友好

  • 无需“指针转换”即可重定位，允许在共享内存中进行真正的零拷贝访问

Arrow 列式格式以相对更昂贵的修改操作为代价，提供了分析性能和数据局部性保证。本文档仅关注内存数据表示和序列化细节；诸如协调数据结构修改之类的问题留给实现来处理。

术语#

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

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

  • 槽：数组中具有特定数据类型的单个逻辑值

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

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

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

  • 基本类型：没有子类型的数据类型。这包括固定位宽、可变大小二进制和空类型等类型。

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

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

  • 参数化类型：需要附加参数才能完全确定其语义的类型。例如，所有嵌套类型都是通过构造进行参数化的。时间戳也是参数化的，因为它需要一个单位（例如微秒）和一个时区。

数据类型#

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

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

类型

类型参数(1)

物理内存布局

空

空

布尔值

固定大小基本类型

整数

  • 位宽

  • 符号

“（同上）

浮点数

  • 精度

“

十进制

  • 位宽

  • 比例

  • 精度

“

日期

  • 单位

“

时间

  • 位宽(2)

  • 单位

“

时间戳

  • 单位

  • 时区

“

间隔

  • 单位

“

持续时间

  • 单位

“

固定大小二进制

  • 字节宽度

固定大小二进制

二进制

具有 32 位偏移量的可变大小二进制

Utf8

“

大型二进制

具有 64 位偏移量的可变大小二进制

大型 Utf8

“

二进制视图

可变大小二进制视图

Utf8 视图

“

固定大小列表

  • 值类型

  • 列表大小

固定大小列表

列表

  • 值类型

具有 32 位偏移量的可变大小列表

大型列表

  • 值类型

具有 64 位偏移量的可变大小列表

列表视图

  • 值类型

具有 32 位偏移量和大小的可变大小列表视图

大型列表视图

  • 值类型

具有 64 位偏移量和大小的可变大小列表视图

结构体

  • 子级

结构体

映射

  • 子级

  • 键排序

结构体的可变大小列表

联合

  • 子级

  • 模式

  • 类型 ID

密集或稀疏联合(3)

字典

  • 索引类型(4)

  • 值类型

  • 有序性

字典编码

游程编码

  • 游程结束类型 (5)

  • 值类型

游程编码

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

  • (2) 时间类型的*位宽*参数在技术上是多余的，因为每个*单位*都规定了单个位宽。

  • (3) 联合类型是使用稀疏还是密集布局由其*模式*参数表示。

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

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

注意

有时，“逻辑类型”一词用于表示 Arrow 数据类型，并将它们与其各自的物理布局区分开来。但是，与其他类型系统（例如 Apache Parquet）不同，Arrow 类型系统没有物理类型和逻辑类型的单独概念。

Arrow 类型系统单独提供了扩展类型，它允许使用更丰富的面向应用程序的语义来注释标准 Arrow 数据类型（例如，在标准字符串数据类型上定义“JSON”类型）。

物理内存布局#

数组由几部分元数据和数据定义

  • 数据类型。

  • 缓冲区序列。

  • 长度为 64 位有符号整数。允许实现限制为 32 位长度，请参阅下文了解更多信息。

  • 空计数作为 64 位有符号整数。

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

嵌套数组还具有一或多个这些项目集的序列，称为**子数组**。

每种数据类型都有一个定义良好的物理布局。以下是 Arrow 定义的不同物理布局

  • **基本类型（固定大小）**：一系列值，每个值都具有相同的字节或位宽

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

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

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

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

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

  • **结构体**：一种嵌套布局，由一组命名的子**字段**组成，每个字段都具有相同的长度，但可能具有不同的类型。

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

  • **字典编码**：一种布局，由一系列整数（任何位宽）组成，这些整数表示字典中的索引，字典可以是任何类型。

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

  • 空值：一个全部为空值的序列。

Arrow 列式内存布局仅适用于数据，而不适用于元数据。实现可以自由选择任何方便的形式在内存中表示元数据。我们使用 FlatBuffers 以独立于实现的方式处理元数据序列化，详见下文。

缓冲区对齐和填充#

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

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

  • 保证可以通过对齐访问来检索数值数组中的元素。

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

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

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

数组长度#

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

空值计数#

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

有效性位图#

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

除联合类型（稍后将详细介绍）外，所有数组类型都使用专用的内存缓冲区（称为有效性（或“空”）位图）来编码每个值槽的空值或非空值。有效性位图必须足够大，以至少为每个数组槽包含 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 个或多个字节组成。基本数组只有一个值缓冲区，而可变大小二进制数组有一个偏移量缓冲区和一个数据缓冲区。

偏移量缓冲区包含 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 个或多个字节组成。这些字节的位置使用视图缓冲区指示，该缓冲区可能指向潜在的多个数据缓冲区之一，也可能内联包含字符。

视图缓冲区包含具有以下布局的 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      |

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

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

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

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

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

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

可变大小列表布局#

列表是一种嵌套类型，语义上类似于可变大小的二进制数据。列表布局有两种变体——“列表”和“列表视图”——每种变体都可以由 32 位或 64 位偏移量整数分隔。

列表布局#

列表布局由两个缓冲区定义：一个有效性位图和一个偏移量缓冲区，以及一个子数组。偏移量与可变大小二进制情况下的偏移量相同，并且支持 32 位和 64 位有符号整数偏移量作为偏移量的选项。这些偏移量不引用额外的数据库，而是引用子数组。

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

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

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

我们用一个长度为 4 且值为

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

的 List<Int8> 示例来说明

* 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) |

将具有以下表示形式

[[[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) |

列表视图布局#

Arrow 版本新增： 列式格式 1.4

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

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

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

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 且值为

[[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: 4, 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]]

的 List<Int8> 示例来说明

* 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，其值在此缓冲区中找到。具有超过 127 种可能类型的联合可以建模为联合的联合。

  • 偏移量缓冲区：一个有符号 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) |

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

空布局#

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

字典编码布局#

字典编码是一种数据表示技术，通过引用通常由唯一值组成的**字典**的整数来表示值。当您拥有包含许多重复值的数据时，它可能非常有效。

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

例如，您可以拥有以下数据

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

偏移量

空

字典编码

有效性

数据（索引）

行程结束编码

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

列式格式中序列化数据的基本单位是“记录批”。语义上，记录批是有序的数组集合，称为其**字段**，每个数组的长度彼此相同，但数据类型可能不同。记录批的字段名称和类型共同构成批的**模式**。

在本节中，我们定义了一个协议，用于将记录批序列化为二进制负载流，并从这些负载重建记录批，而无需进行内存复制。

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

  • 模式

  • 记录批

  • 字典批

我们指定了一种所谓的*封装 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 元数据以获取正文大小。然后可以读取正文。

模式消息#

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

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

  • 字段的名称

  • 字段的数据类型

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

  • 用于嵌套类型的子 Field 值的集合

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

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

记录批消息#

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 设置为实际内存大小而不是填充大小。

可变缓冲区#

Arrow 版本新增： 列式格式 1.4

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

例如，考虑以下模式

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

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

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

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

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

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

注意

某些 Arrow 实现缺乏对使用上述一种或两种编解码器生成和使用具有压缩缓冲区的 IPC 数据的支持。有关详细信息，请参阅 实现状态。

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

字节顺序（字节序）#

Arrow 格式默认为小端序。

序列化 Schema 元数据具有一个字节序字段，指示 RecordBatches 的字节序。通常，这是生成 RecordBatch 的系统的字节序。主要用例是在具有相同字节序的系统之间交换 RecordBatches。最初，当尝试读取字节序与底层系统不匹配的 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 个字节或关闭流接口来 segnal end-of-stream (EOS)。我们建议对流格式使用“.arrows”文件扩展名，尽管在许多情况下这些流永远不会存储为文件。

IPC 文件格式#

我们定义了一种支持随机访问的“文件格式”，它是流格式的扩展。文件以魔术字符串 ARROW1（加上填充）开头和结尾。文件中接下来的内容与流格式相同。在文件末尾，我们写入一个*页脚*，其中包含 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 中找到，因此有必要读取 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 模式是 custom_metadata 字段中 Arrow 内部使用的保留命名空间。例如，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 值，并具有序列化元数据，指示每个值的数据类型和形状。 对于 4x5 单元格张量，这可以是类似 {'type': 'int8', 'shape': [4, 5]} 的 JSON。

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

另请参阅

规范扩展类型

实现指南#

执行引擎（或框架，或 UDF 执行器，或存储引擎等）可以只实现 Arrow 规范的一个子集，并且/或者在以下约束条件下对其进行扩展。

实现规范的子集#

  • **如果只生成（不使用）arrow 向量**：可以实现向量规范和相应元数据的任何子集。

  • **如果使用和生成向量**：需要支持向量的最小 子集。生成向量子集及其相应的元数据始终是可以的。使用向量至少应将不支持的输入向量转换为支持的子集（例如，将 Timestamp.millis 转换为 timestamp.micros 或将 int32 转换为 int64）。

可扩展性#

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