表#
注意：Table API 仍处于实验阶段，可能会有所更改。请参阅下面的限制列表。
Table 是一个基于 FieldVector 的不可变表格数据结构。与 VectorSchemaRoot 类似，Table 是一个由 Arrow 数组（或更具体地说，由 FieldVector 对象）支持的列式数据结构。它与 VectorSchemaRoot 的主要区别在于它是完全不可变的，并且不支持批处理操作。任何在管道中处理表格数据批次的用户都应继续使用 VectorSchemaRoot。最后，Table API 主要面向行，因此在某些方面它更像 JDBC API 而不是 VectorSchemaRoot API，但您仍然可以使用 FieldReaders 以列式方式处理数据。
Table 和 VectorSchemaRoot 中的修改#
VectorSchemaRoot 提供了一个对其数据所持向量的薄包装器。可以从向量模式根检索单个向量。这些向量具有用于修改其元素的 setter，使得 VectorSchemaRoot 仅在约定上是不可变的。修改向量的协议记录在 ValueVector 接口中
值需要按顺序写入（例如，索引 0、1、2、5）
空向量在写入任何内容之前，所有值都为空
对于可变宽度类型，偏移向量在写入之前应全部为零
在读取向量之前必须调用 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 创建，如下所示，使用“可变参数”数组参数
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 支持 slice() 操作，其中源表的切片是第二个表，它引用源中单个连续的行范围。
try (Table t = new Table(vectorList)) {
Table t2 = t.slice(100, 200); // creates a slice referencing the values in range (100, 200]
...
}
这就提出了一个问题：如果您创建一个包含源表中 所有 值的切片（如下所示），这与使用与源表相同的向量构造的新表有何不同？
try (Table t = new Table(vectorList)) {
Table t2 = t.slice(0, t.getRowCount()); // creates a slice referencing all the values in t
// ...
}
区别在于，当您 构造 一个新表时，缓冲区会从源向量转移到目标中的新向量。而对于切片，两个表共享相同的底层向量。但这没关系，因为两个表都是不可变的。
使用 FieldReaders#
您可以通过将 Field、向量索引或向量名称作为参数，获取表中任何向量的 FieldReader。签名与 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() 检查值是否为空。如果向量包含任何空值，这很重要，因为在某些情况下，从向量请求值可能会导致 NullPointerException。
boolean name0isNull = row.isNull("name");
您还可以获取当前行号
int row = row.getRowNumber();
将值读取为对象#
对于任何给定的向量类型，基本的 get() 方法在可能的情况下返回原始值。例如，getTimeStampMicro() 返回一个编码时间戳的 long 值。要获取 Java 中表示该时间戳的 LocalDateTime 对象，提供了另一个名称后附加“Obj”的方法。例如
long ts = row.getTimeStampMicro();
LocalDateTime tsObject = row.getTimeStampMicroObj();
此命名方案的例外是复杂向量类型（List、Map、Schema、Union、DenseUnion 和 ExtensionType）。它们总是返回对象而不是原始类型，因此不需要“Obj”扩展。预计一些用户可能会子类化 Row 以添加更符合其需求的 getter。
读取 VarChars 和 LargeVarChars#
Arrow 中的字符串表示为使用 UTF-8 字符集编码的字节数组。您可以获取 String 结果或实际的字节数组。
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() 的 provider 参数，并且将使用表的 provider 属性
Data.exportTable(bufferAllocator, table, outArrowArray);