数组#

另请参阅

Array API 参考

Arrow 中的中心类型是类 arrow::Array。数组表示已知长度且具有相同类型的值序列。在内部，这些值由一个或多个缓冲区表示，缓冲区的数量和含义取决于数组的数据类型，如 Arrow 数据布局规范中所述。

这些缓冲区由值数据本身和一个可选的位图缓冲区组成，位图缓冲区指示哪些数组条目为空值。如果已知数组没有空值，则可以完全省略位图缓冲区。

每个数据类型都有 arrow::Array 的具体子类，可帮助您访问数组的各个值。

构建数组#

可用策略#

由于 Arrow 对象是不可变的，因此它们不能像 std::vector 那样直接填充。相反，可以使用多种策略

如果数据已经以正确的布局存在于内存中，则可以将所述内存包装在 arrow::Buffer 实例中，然后构造一个描述数组的 arrow::ArrayData；

另请参阅

内存管理
否则，arrow::ArrayBuilder 基类及其具体子类有助于增量构建数组数据，而无需处理 Arrow 格式的细节。

使用 ArrayBuilder 及其子类#

要构建一个 Int64 Arrow 数组，我们可以使用 arrow::Int64Builder 类。在以下示例中，我们构建一个 1 到 8 范围的数组，其中应保存值 4 的元素为空

arrow::Int64Builder builder;
builder.Append(1);
builder.Append(2);
builder.Append(3);
builder.AppendNull();
builder.Append(5);
builder.Append(6);
builder.Append(7);
builder.Append(8);

auto maybe_array = builder.Finish();
if (!maybe_array.ok()) {
   // ... do something on array building failure
}
std::shared_ptr<arrow::Array> array = *maybe_array;

生成的 Array（如果您想访问其值，可以将其转换为具体的 arrow::Int64Array 子类）然后由两个 arrow::Buffer 组成。第一个缓冲区保存空位图，此处由一个字节组成，其位为 1|1|1|1|0|1|1|1。当我们使用最低有效位 (LSB) 编号时，这表明数组中的第四个条目为空。第二个缓冲区只是一个包含上述所有值的 int64_t 数组。由于第四个条目为空，因此缓冲区中该位置的值未定义。

以下是如何访问具体数组的内容

// Cast the Array to its actual type to access its data
auto int64_array = std::static_pointer_cast<arrow::Int64Array>(array);

// Get the pointer to the null bitmap
const uint8_t* null_bitmap = int64_array->null_bitmap_data();

// Get the pointer to the actual data
const int64_t* data = int64_array->raw_values();

// Alternatively, given an array index, query its null bit and value directly
int64_t index = 2;
if (!int64_array->IsNull(index)) {
   int64_t value = int64_array->Value(index);
}

注意

arrow::Int64Array（分别为 arrow::Int64Builder）只是为了方便而提供的 typedef，分别是 arrow::NumericArray<Int64Type>（分别为 arrow::NumericBuilder<Int64Type>）。

性能#

虽然可以像上面的示例那样逐个值地构建数组，但要获得最高性能，建议在具体的 arrow::ArrayBuilder 子类中使用批量追加方法（通常命名为 AppendValues）。

如果您预先知道元素的数量，还建议通过调用 Resize() 或 Reserve() 方法来预先调整工作区的大小。

以下是如何重写上面的示例以利用这些 API

arrow::Int64Builder builder;
// Make place for 8 values in total
builder.Reserve(8);
// Bulk append the given values (with a null in 4th place as indicated by the
// validity vector)
std::vector<bool> validity = {true, true, true, false, true, true, true, true};
std::vector<int64_t> values = {1, 2, 3, 0, 5, 6, 7, 8};
builder.AppendValues(values, validity);

auto maybe_array = builder.Finish();

如果您仍然必须逐个追加值，则一些具体的构建器子类具有标记为“Unsafe”的方法，这些方法假设工作区已正确预先调整大小，并且提供更高的性能作为交换

arrow::Int64Builder builder;
// Make place for 8 values in total
builder.Reserve(8);
builder.UnsafeAppend(1);
builder.UnsafeAppend(2);
builder.UnsafeAppend(3);
builder.UnsafeAppendNull();
builder.UnsafeAppend(5);
builder.UnsafeAppend(6);
builder.UnsafeAppend(7);
builder.UnsafeAppend(8);

auto maybe_array = builder.Finish();

大小限制和建议#

某些数组类型在结构上仅限于 32 位大小。对于列表数组（最多可以容纳 2^31 个元素）、字符串数组和二进制数组（最多可以容纳 2GB 的二进制数据）来说，就是这种情况。至少，某些其他数组类型可以在 C++ 实现中容纳最多 2^63 个元素，但其他 Arrow 实现对于这些数组类型也可能具有 32 位大小限制。

由于这些原因，建议将巨大的数据分块为更合理大小的子集。

分块数组#

arrow::ChunkedArray 就像数组一样，是值的逻辑序列；但与简单数组不同，分块数组不需要整个序列在内存中物理上连续。此外，分块数组的组成部分不必具有相同的大小，但它们必须都具有相同的数据类型。

分块数组是通过聚合任意数量的数组来构造的。在这里，我们将构建一个分块数组，其逻辑值与上面的示例相同，但在两个单独的块中

std::vector<std::shared_ptr<arrow::Array>> chunks;
std::shared_ptr<arrow::Array> array;

// Build first chunk
arrow::Int64Builder builder;
builder.Append(1);
builder.Append(2);
builder.Append(3);
if (!builder.Finish(&array).ok()) {
   // ... do something on array building failure
}
chunks.push_back(std::move(array));

// Build second chunk
builder.Reset();
builder.AppendNull();
builder.Append(5);
builder.Append(6);
builder.Append(7);
builder.Append(8);
if (!builder.Finish(&array).ok()) {
   // ... do something on array building failure
}
chunks.push_back(std::move(array));

auto chunked_array = std::make_shared<arrow::ChunkedArray>(std::move(chunks));

assert(chunked_array->num_chunks() == 2);
// Logical length in number of values
assert(chunked_array->length() == 8);
assert(chunked_array->null_count() == 1);

切片#

与物理内存缓冲区一样，可以对数组和分块数组进行零复制切片，以获得引用数据的一些逻辑子序列的数组或分块数组。这是通过分别调用 arrow::Array::Slice() 和 arrow::ChunkedArray::Slice() 方法来完成的。