#

注意:Table API 处于实验阶段,可能会发生变化。请参阅以下限制列表。

Table 是基于 FieldVector 的不可变表格数据结构。与 VectorSchemaRoot 一样,Table 是一个由 Arrow 数组支持的列式数据结构,更确切地说,是由 FieldVector 对象支持的。它与 VectorSchemaRoot 的主要区别在于它是完全不可变的,并且不支持批处理操作。任何在管道中处理表格数据批次的程序员都应该继续使用 VectorSchemaRoot。最后,Table API 主要面向行,因此在某些方面它更像 JDBC API 而不是 VectorSchemaRoot API,但您仍然可以使用 FieldReaders 以列式方式处理数据。

Table 和 VectorSchemaRoot 中的变异#

VectorSchemaRoot 为保存其数据的向量提供了一个薄包装器。可以从向量模式根中检索单个向量。这些向量具有用于修改其元素的设置器,这使得 VectorSchemaRoot 仅按惯例不可变。修改向量的协议在 ValueVector 接口中进行了记录

  • 值需要按顺序写入(例如,索引 0、1、2、5)

  • 空向量在写入任何内容之前都以所有值为 null 开始

  • 对于可变宽度类型,偏移向量在写入之前应全部为零

  • 您必须在读取向量之前调用 setValueCount

  • 您不应该在读取向量后写入向量。

这些规则没有被 API 强制执行,因此程序员有责任确保遵守这些规则。未能做到这一点可能会导致运行时异常。

Table 另一方面,是不可变的。不会公开底层向量。当从现有向量创建表时,它们的内存将被转移到新的向量,因此随后对原始向量的更改不会影响新表的数值。

功能和限制#

目前提供了一组基本的表格功能

  • 从向量或 VectorSchemaRoot 创建表

  • 按行迭代表,或直接设置当前行索引

  • 以基本类型、对象和/或可空 ValueHolder 实例访问向量值(取决于类型)

  • 获取任何向量的 FieldReader

  • 添加和删除向量,创建新表

  • 使用字典编码对表的向量进行编码和解码

  • 导出表格数据以供本机代码使用

  • 将代表性数据打印到 TSV 字符串

  • 获取表的模式

  • 切片表

  • 将表转换为 VectorSchemaRoot

11.0.0 版本中的限制

  • 不支持 ChunkedArray 或任何形式的行组。将考虑在未来版本中支持分块数组或行组。

  • 不支持 C-Stream API。对流式 API 的支持取决于分块数组支持

  • 不支持直接从 Java POJO 创建表。表持有的所有数据必须通过 VectorSchemaRoot 导入,或者从向量集合或数组导入。

Table API#

VectorSchemaRoot 一样,表包含一个 Schema 和一个有序的 FieldVector 对象集合,但它旨在通过面向行的接口进行访问。

从 VectorSchemaRoot 创建表#

表是从 VectorSchemaRoot 创建的,如下所示。保存数据的内存缓冲区将从向量模式根转移到新表中的新向量,在此过程中清除源向量。这确保了新表中的数据永远不会改变。由于缓冲区是转移而不是复制的,因此这是一个非常低开销的操作。

Table t = new Table(someVectorSchemaRoot);

如果您现在更新 VectorSchemaRoot 持有的向量(使用某种版本的 ValueVector#setSafe()),它将反映这些更改,但表 t 中的值保持不变。

从 FieldVectors 创建表#

表可以从 FieldVectors 创建,如下所示,使用“var-arg”数组参数

IntVector myVector = createMyIntVector();
VectorSchemaRoot vsr1 = new VectorSchemaRoot(myVector);

或者通过传递集合

IntVector myVector = createMyIntVector();
List<FieldVector> fvList = List.of(myVector);
VectorSchemaRoot vsr1 = new VectorSchemaRoot(fvList);

在多个向量模式根之间共享向量很少是一个好主意,在向量模式根和表之间共享向量也不是一个好主意。从向量列表创建 VectorSchemaRoot 不会导致向量的引用计数增加。除非您手动管理计数,否则下面的代码会导致引用多于引用计数,这可能会导致问题。有一个隐含的假设是,这些向量是为使用一个 VectorSchemaRoot 创建的,而这段代码违反了这个假设。

不要这样做

IntVector myVector = createMyIntVector();  // Reference count for myVector = 1
VectorSchemaRoot vsr1 = new VectorSchemaRoot(myVector); // Still one reference
VectorSchemaRoot vsr2 = new VectorSchemaRoot(myVector);
// Ref count is still one, but there are two VSRs with a reference to myVector
vsr2.clear(); // Reference count for myVector is 0.

发生的事情是,引用计数器的工作级别低于 VectorSchemaRoot 接口。引用计数器计算对控制内存缓冲区的 ArrowBuf 实例的引用。它不计算对保存这些 ArrowBuf 的向量的引用。在上面的示例中,每个 ArrowBuf 由一个向量持有,因此只有一个引用。当您调用 VectorSchemaRoot 的 clear() 方法时,这种区别会变得模糊,该方法会释放它引用的每个向量的内存,即使另一个实例引用了相同的向量。

当您从向量创建表时,假设没有对这些向量进行外部引用。为了确保这一点,表中的新向量将转移这些向量底层的缓冲区,并清除原始向量。

也不要这样做,但请注意与上面的区别

IntVector myVector = createMyIntVector(); // Reference count for myVector = 1
Table t1 = new Table(myVector);
// myVector is cleared; Table t1 has a new hidden vector with the data from myVector
Table t2 = new Table(myVector);
// t2 has no rows because myVector was just cleared
// t1 continues to have the data from the original vector
t2.clear();
// no change because t2 is already empty and t1 is independent

对于表,内存是在实例化时显式转移的,因此表持有的缓冲区仅由该表持有。

使用字典编码向量创建表#

另一个区别是,VectorSchemaRoot 不了解其向量的任何字典编码,而表持有可选的 DictionaryProvider 实例。如果源数据中的任何向量都被编码,则必须设置 DictionaryProvider 来对值进行解码。

VectorSchemaRoot vsr = myVsr();
DictionaryProvider provider = myProvider();
Table t = new Table(vsr, provider);

Table 中,字典的使用方式与向量相同。要解码向量,用户提供要解码的向量的名称和字典 ID

Table t = new Table(vsr, provider);
ValueVector decodedName = t.decode("name", 1L);

要从表中编码向量,使用类似的方法

Table t = new Table(vsr, provider);
ValueVector encodedName = t.encode("name", 1L);

显式释放内存#

表使用必须在不再需要时释放的堆外内存。 Table 实现 AutoCloseable,因此创建它的最佳方式是在 try-with-resources 块中

try (VectorSchemaRoot vsr = myMethodForGettingVsrs();
    Table t = new Table(vsr)) {
    // do useful things.
}

如果您不使用 try-with-resources 块,则必须手动关闭表

try {
    VectorSchemaRoot vsr = myMethodForGettingVsrs();
    Table t = new Table(vsr);
    // do useful things.
} finally {
    vsr.close();
    t.close();
}

手动关闭应在 finally 块中执行。

获取模式#

您可以像使用向量模式根一样获取表的模式

Schema s = table.getSchema();

添加和删除向量#

Table 提供了用于添加和删除向量的功能,这些功能模拟了 VectorSchemaRoot 中的相同功能。这些操作返回新实例,而不是就地修改原始实例。

try (Table t = new Table(vectorList)) {
    IntVector v3 = new IntVector("3", intFieldType, allocator);
    Table t2 = t.addVector(2, v3);
    Table t3 = t2.removeVector(1);
    // don't forget to close t2 and t3
}

切片表#

Table 支持切片() 操作,其中源表的切片是第二个 Table,它引用源表中单个连续的行范围。

try (Table t = new Table(vectorList)) {
    Table t2 = t.slice(100, 200); // creates a slice referencing the values in range (100, 200]
    ...
}

这提出了一个问题:如果您使用所有源表中的值创建切片(如下所示),它与使用与源表相同的向量构造的新 Table 有什么区别?

try (Table t = new Table(vectorList)) {
    Table t2 = t.slice(0, t.getRowCount()); // creates a slice referencing all the values in t
    // ...
}

区别在于,当您构建一个新表时,缓冲区会从源向量转移到目标中的新向量。对于切片,两个表共享相同的底层向量。不过,这没关系,因为两个表都是不可变的。

使用 FieldReaders#

您可以为表中的任何向量获取一个 FieldReader,方法是将 Field、向量索引或向量名称作为参数传递。签名与 VectorSchemaRoot 中的相同。

FieldReader nameReader = table.getReader("user_name");

行操作#

Row 对象支持基于行的访问。 Row 通过向量名称和向量位置提供get()方法,但不提供set()操作。

重要的是要认识到,行不是作为对象具体化的,而是像一个游标一样工作,其中可以使用相同的 Row 实例查看表中多个逻辑行的数据(一次一个)。有关在表中导航的信息,请参见下面的“从一行移动到另一行”。

获取一行#

在任何表实例上调用 immutableRow() 将返回一个新的 Row 实例。

Row r = table.immutableRow();

从一行移动到另一行#

由于行是可迭代的,因此您可以使用标准的 while 循环遍历表

Row r = table.immutableRow();
while (r.hasNext()) {
  r.next();
  // do something useful here
}

Table 实现 Iterable<Row>,因此您可以在增强的 for 循环中直接从表中访问行

for (Row row: table) {
  int age = row.getInt("age");
  boolean nameIsNull = row.isNull("name");
  ...
}

最后,虽然行通常按底层数据向量的顺序进行迭代,但它们也可以使用 Row#setPosition() 方法定位,因此您可以跳到特定行。行号从 0 开始。

Row r = table.immutableRow();
int age101 = r.setPosition(101); // change position directly to 101

对位置的任何更改都将应用于表中的所有列。

请注意,您必须在通过行访问值之前调用 next()setPosition()。否则会导致运行时异常。

使用行进行读取操作#

提供了一些方法,用于通过向量名称和向量索引获取值,其中索引是表中向量的 0 基位置。例如,假设“age”是“table”中的第 13 个向量,则以下两个获取是等效的

Row r = table.immutableRow();
r.next(); // position the row at the first value
int age1 = r.get("age"); // gets the value of vector named 'age' in the table at row 0
int age2 = r.get(12);    // gets the value of the 13th vector in the table at row 0

您还可以使用可空 ValueHolder 获取值。例如

NullableIntHolder holder = new NullableIntHolder();
int b = row.getInt("age", holder);

这可用于检索值,而无需为每个值创建一个新对象。

除了获取值之外,您还可以使用 isNull() 检查值是否为空。如果向量包含任何空值,这一点很重要,因为在某些情况下,从向量中请求值会导致 NullPointerExceptions。

boolean name0isNull = row.isNull("name");

您还可以获取当前行号

int row = row.getRowNumber();

将值读取为对象#

对于任何给定的向量类型,基本的get()方法在可能的情况下返回一个基本值。例如,getTimeStampMicro() 返回一个长整型值,该值对时间戳进行编码。要获取在 Java 中表示该时间戳的 LocalDateTime 对象,请提供另一个方法,其名称后缀为“Obj”。例如

long ts = row.getTimeStampMicro();
LocalDateTime tsObject = row.getTimeStampMicroObj();

此命名方案的例外情况是复杂向量类型(List、Map、Schema、Union、DenseUnion 和 ExtensionType)。这些始终返回对象而不是基本类型,因此不需要“Obj”扩展。预计一些用户可能会对 Row 进行子类化,以添加更适合其需求的 getter。

读取 VarChars 和 LargeVarChars#

箭头中的字符串表示为使用 UTF-8 字符集编码的字节数组。您可以获取字符串结果或实际的字节数组。

byte[] b = row.getVarChar("first_name");
String s = row.getVarCharObj("first_name");       // uses the default encoding (UTF-8)

将表转换为 VectorSchemaRoot#

可以使用toVectorSchemaRoot()方法将表转换为向量模式根。缓冲区将被转移到向量模式根,并且源表将被清除。

VectorSchemaRoot root = myTable.toVectorSchemaRoot();

使用 C-Data 接口#

许多 Arrow 功能都需要能够使用本机代码。本节介绍如何将表导出以供本机代码使用

导出通过将数据转换为 VectorSchemaRoot 实例并使用现有工具来传输数据来实现。您可以自己完成,但这并不理想,因为转换为向量模式根会破坏不可变性保证。使用 Data 类中的 exportTable() 方法可以避免这种情况。

Data.exportTable(bufferAllocator, table, dictionaryProvider, outArrowArray);

如果表包含字典编码向量,并且是使用 DictionaryProvider 构建的,则可以省略 exportTable() 的提供程序参数,并将使用表的提供程序属性

Data.exportTable(bufferAllocator, table, outArrowArray);