API 参考

Arrow.ArrowVector

一种继承自 AbstractVector 的抽象类型。每个特定的箭头数组类型都是 ArrowVector 的子类型。有关更多详细信息，请参阅 BoolVector、Primitive、List、Map、FixedSizeList、Struct、DenseUnion、SparseUnion 和 DictEncoded。

Arrow.BoolVector

一种位压缩数组类型，类似于 ValidityBitmap，但它保存布尔值 true 或 false。

Arrow.Compressed

表示 ArrowVector 的压缩版本。持有对原始列的引用。嵌套数组类型可能具有 Compressed 子级。

Arrow.DenseUnion

一种 ArrowVector，其中每个元素的类型是一组固定类型之一，这意味着其 eltype 类似于 Julia 的 Union{type1, type2, ...}。与 Arrow.SparseUnion 相比，Arrow.DenseUnion 将元素存储在一组数组中，每个可能的类型对应一个数组，还有一个“偏移量”数组，其中每个偏移量元素都是其中一个类型化数组的索引。这允许某种“压缩”，其中不使用/分配额外的空间来存储所有元素。

Arrow.DictEncode(::AbstractVector, id::Integer=nothing)

指示在序列化为箭头流/文件格式时，列/数组应进行字典编码。可以提供可选的 `id` 编号，以指示多个列在进行字典编码时应使用相同的池。

Arrow.DictEncoded

一种字典编码的数组类型（类似于 `PooledArray`）。在大多数方面，其行为与普通数组相同；在内部，可能的值存储在 `encoding::DictEncoding` 字段中，而 `indices::Vector{<:Integer}` 字段保存每个元素用于索引编码池的“代码”。任何列/数组都可以在序列化为箭头格式时进行字典编码，方法是将 `dictencode=true` 关键字参数传递给 `Arrow.write`（这会导致 *所有* 列都被字典编码），或者将单个列/数组包装在 `Arrow.DictEncode(x)` 中.

Arrow.DictEncoding

表示 `DictEncoded` 数组类型的可能值的“池”。可以通过查看 `isOrdered` 布尔字段来检查值的顺序是否重要。

类型参数 `S` 虽然不直接与任何字段关联，但它是父 DictEncoded 的带符号整数“索引类型”。我们在 DictEncoding 中跟踪这一点，以便验证池的长度不超过索引类型限制。写入箭头数据的一般工作流程意味着初始模式通常基于第一个记录批次中的数据，后续记录批次需要与同一模式完全匹配。例如，如果一个非第一个记录批次的字典编码列导致 DictEncoding 池中的唯一值溢出，则应抛出致命错误。

Arrow.FixedSizeList

一种 `ArrowVector`，其中每个元素都是某种“固定大小”的列表，例如 `NTuple{N, T}`.

Arrow.List

一个`ArrowVector`，其中每个元素都是某种可变大小的列表，例如`AbstractVector`或`AbstractString`。

Arrow.Map

一个`ArrowVector`，其中每个元素都是某种“映射”，例如`Dict`。

Arrow.Primitive

一个 `ArrowVector`，其中每个元素都是某种“固定大小”的标量，例如整数、浮点数、十进制数或时间类型。

Arrow.SparseUnion

一个`ArrowVector`，其中每个元素的类型是一组固定类型之一，这意味着它的eltype类似于Julia的`Union{type1，type2，...}`。与`Arrow.DenseUnion`相比，`Arrow.SparseUnion`将元素存储在一组数组中，每个可能的类型对应一个数组，并且每个类型化数组的长度与完整数组相同。这最终会导致空间“浪费”，因为每个完整数组元素在类型化数组中只有一个槽有效，但在每个类型化数组具有相同长度时，可以进行某些优化.

Arrow.Stream(io::IO; convert::Bool=true)
Arrow.Stream(file::String; convert::Bool=true)
Arrow.Stream(bytes::Vector{UInt8}, pos=1, len=nothing; convert::Bool=true)
Arrow.Stream(inputs::Vector; convert::Bool=true)

开始读取箭头格式的表格，来自

• io，字节将通过 read(io) 一次性读取
• file，字节将通过 Mmap.mmap(file) 读取
• bytes，一个字节向量，可以选择指定起始字节位置 pos 和 len
• 上述任何一个的 Vector，其中每个输入都应是 IPC 或箭头文件，并且必须与模式匹配

从箭头流/文件中读取初始模式消息，然后返回一个 Arrow.Stream 对象，该对象将迭代记录批处理消息，并在每次迭代时生成一个 Arrow.Table。

通过迭代 Arrow.Table，Arrow.Stream 满足 Tables.partitions 接口，因此可以传递给与 Tables.jl 兼容的接收器函数。

这允许以记录批处理表示的块迭代超大的“箭头表”。

支持 convert 关键字参数，该参数控制是否将某些箭头基本类型延迟转换为更友好的 Julia 默认值；默认情况下，convert=true。

Arrow.Struct

一个`ArrowVector`，其中每个元素都是某种具有有序命名字段的“结构体”，例如`NamedTuple{names，types}`或常规的Julia`struct`。

Arrow.Table(io::IO; convert::Bool=true)
Arrow.Table(file::String; convert::Bool=true)
Arrow.Table(bytes::Vector{UInt8}, pos=1, len=nothing; convert::Bool=true)
Arrow.Table(inputs::Vector; convert::Bool=true)

读取箭头格式的表格，来自

• io，字节将通过 read(io) 一次性读取
• file，字节将通过 Mmap.mmap(file) 读取
• bytes，一个字节向量，可以选择指定起始字节位置 pos 和 len
• 上述任何一个的 Vector，其中每个输入都应是 IPC 或箭头文件，并且必须与模式匹配

返回一个 Arrow.Table 对象，该对象允许通过 table.col1、table[:col1] 或 table[1] 访问列。

注意：Arrow.Table 中的列是对原始箭头内存的视图，因此不容易修改（例如使用 push!、append! 等）。要改变箭头列，请调用 copy(x) 将箭头数据实例化为普通的 Julia 数组。

Arrow.Table 还满足 Tables.jl 接口，因此可以很容易地通过任何支持的接收器函数实现：例如 DataFrame(Arrow.Table(file))、SQLite.load!(db, "table", Arrow.Table(file)) 等。

支持 convert 关键字参数，该参数控制是否将某些箭头基本类型延迟转换为更友好的 Julia 默认值；默认情况下，convert=true。

Arrow.ToTimestamp(x::AbstractVector{ZonedDateTime})

包装器数组，它提供了一种更有效的将`ZonedDateTime`元素编码为箭头格式的方法。在箭头格式中，带有时区信息的timestamps列被编码为Julia类型参数的箭头等效项，这意味着整个列*应该*具有都具有相同时区的元素。如果将`ZonedDateTime`列传递给`Arrow.write`，为了正确起见，它必须扫描每个元素以检查每个时区。`Arrow.ToTimestamp`通过对`AbstractVector{ZonedDateTime}`的第一个元素的时区进行编码来提供此过程的“旁路”，这反过来又允许`Arrow.write`避免代价高昂的检查/转换，并且可以直接将`ZonedDateTime`编码为`Arrow.Timestamp`。

Arrow.ValidityBitmap

一种位压缩数组类型，其中每一位对应于 ArrowVector 中的一个元素，指示该元素是否“有效”（位 == 1）或无效（位 == 0）。用于指示元素缺失（是否为 null）。

如果数组的 null 计数为零，则 ValidityBitmap 将“为空”，并且所有元素都被视为“有效”/非 null。

Arrow.View

一个`ArrowVector`，其中每个元素都是某种可变大小的列表，例如`AbstractVector`或`AbstractString`。

Arrow.Writer{T<:IO}

可用于增量写入 Arrow 分区的对象

示例

julia> writer = open(Arrow.Writer, tempname())

julia> partition1 = (col1 = [1, 2], col2 = ["A", "B"])
(col1 = [1, 2], col2 = ["A", "B"])

julia> Arrow.write(writer, partition1)

julia> partition2 = (col1 = [3, 4], col2 = ["C", "D"])
(col1 = [3, 4], col2 = ["C", "D"])

julia> Arrow.write(writer, partition2)

julia> close(writer)

也可以使用 do 块自动关闭 Writer

julia> open(Arrow.Writer, tempname()) do writer
           partition1 = (col1 = [1, 2], col2 = ["A", "B"])
           Arrow.write(writer, partition1)
           partition2 = (col1 = [3, 4], col2 = ["C", "D"])
           Arrow.write(writer, partition2)
       end

Arrow.append(io::IO, tbl)
Arrow.append(file::String, tbl)
tbl |> Arrow.append(file)

将任何与 Tables.jl 兼容的 tbl 追加到现有的 Arrow 格式文件或 IO。现有的 Arrow 数据必须采用 IPC 流格式。请注意，不允许追加到“Feather 格式文件”，因为此文件格式不支持追加。这意味着像 Arrow.write(filename::String, tbl) 这样写入的文件*不能*追加；相反，您应该像 Arrow.write(filename::String, tbl; file=false) 这样写入。

当提供要写入的 IO 对象时，它必须支持查找。例如，以 r+ 模式打开的文件或可读、可写和可查找的 IOBuffer 可以追加，但网络流不能。

将根据提供的 Tables.partitions(tbl) 的数量写入多个记录批次；默认情况下，对于给定表，这只是一个，但某些表源支持自动分区。请注意，您可以通过执行 Tables.partitioner([tbl1, tbl2, ...]) 将多个表对象转换为分区，但请注意，每个表必须具有完全相同的 Tables.Schema。

默认情况下，Arrow.append 将使用多个线程同时写入多个记录批次（例如，如果使用 julia -t 8 启动 julia 或设置了 JULIA_NUM_THREADS 环境变量）。

Arrow.append 支持的关键字参数包括

• alignment::Int=8：指定在消息中写入时缓冲区对齐的字节数；强烈建议仅使用 8 或 64 的对齐值以进行现代内存缓存行优化
• colmetadata=nothing：应作为表的列的 custom_metadata 字段写入的元数据；必须是 nothing 或 AbstractDict 类型的 column_name::Symbol => column_metadata，其中 column_metadata 是 <:AbstractString 对的可迭代对象。
• dictencode::Bool=false：写入时是否所有列都应使用字典编码；要对特定列进行字典编码，请将列/数组包装在 Arrow.DictEncode(col) 中
• dictencodenested::Bool=false：嵌套数据类型列是否也应字典编码嵌套数组/缓冲区；其他语言实现 可能不支持此功能
• denseunions::Bool=true：Julia Vector{<:Union} 数组是否应使用密集联合布局写入；传递 false 将导致稀疏联合布局
• largelists::Bool=false：导致列表列类型使用 Int64 偏移量数组写入；主要用于测试目的；默认情况下，仅在需要时才使用 Int64 偏移量
• maxdepth::Int=6：允许的最深嵌套序列化级别；默认提供此功能是为了防止具有相互递归数据结构的意外无限递归
• metadata=Arrow.getmetadata(tbl)：应作为表的架构的 custom_metadata 字段写入的元数据；必须是 nothing 或 <:AbstractString 对的可迭代对象。
• ntasks::Int：将输入分区作为 Arrow 记录批次写入时允许的并发线程任务数；默认值为无限制；要禁用多线程写入，请传递 ntasks=1
• convert::Bool：file 架构中的某些 Arrow 原始类型是否应转换为 Julia 默认值，以便将它们与 tbl 的架构匹配；默认情况下，convert=true。
• file::Bool：当提供 IO 时适用，它是否是文件；默认情况下 file=false。

给定 FlatBuffers.Builder 和 Julia 列或列元素类型，写入元素类型的 field.type flatbuffer 定义

Arrow.getmetadata(x)

如果 x isa Arrow.Table，则返回 x 的 Schema custom_metadata 的 Base.ImmutableDict{String,String} 表示形式，如果不存在此类元数据，则返回 nothing。

如果 x isa Arrow.ArrowVector，则返回 x 的 Field custom_metadata 的 Base.ImmutableDict{String,String} 表示形式，如果不存在此类元数据，则返回 nothing。

否则，返回 nothing。

有关自定义应用程序元数据的更多详细信息，请参阅 官方 Arrow 文档。

给定 flatbuffers 元数据类型定义（来自 Schema.fbs 的 Field 实例），转换为相应的 Julia 存储元素类型

Arrow.write(io::IO, tbl)
Arrow.write(file::String, tbl)
tbl |> Arrow.write(io_or_file)

将任何与 Tables.jl 兼容的 tbl 写入为 Arrow 格式的数据。提供 io::IO 参数将导致数据以 “流”格式 写入其中，除非传递了 file=true 关键字参数。提供 file::String 参数将导致写入 “文件”格式。

将根据提供的 Tables.partitions(tbl) 的数量写入多个记录批次；默认情况下，对于给定表，这只是一个，但某些表源支持自动分区。请注意，您可以通过执行 Tables.partitioner([tbl1, tbl2, ...]) 将多个表对象转换为分区，但请注意，每个表必须具有完全相同的 Tables.Schema。

默认情况下，Arrow.write 将使用多个线程同时写入多个记录批次（例如，如果使用 julia -t 8 启动 julia 或设置了 JULIA_NUM_THREADS 环境变量）。

Arrow.write 支持的关键字参数包括

• colmetadata=nothing：应作为表的列的 custom_metadata 字段写入的元数据；必须是 nothing 或 AbstractDict 类型的 column_name::Symbol => column_metadata，其中 column_metadata 是 <:AbstractString 对的可迭代对象。
• compress：可能的值包括 :lz4、:zstd 或您自己初始化的 LZ4FrameCompressor 或 ZstdCompressor 对象；将导致每个记录批次中的所有缓冲区使用相应的压缩编码
• alignment::Int=8：指定在消息中写入时缓冲区对齐的字节数；强烈建议仅使用 8 或 64 的对齐值以进行现代内存缓存行优化
• dictencode::Bool=false：写入时是否所有列都应使用字典编码；要对特定列进行字典编码，请将列/数组包装在 Arrow.DictEncode(col) 中
• dictencodenested::Bool=false：嵌套数据类型列是否也应字典编码嵌套数组/缓冲区；其他语言实现 可能不支持此功能
• denseunions::Bool=true：Julia Vector{<:Union} 数组是否应使用密集联合布局写入；传递 false 将导致稀疏联合布局
• largelists::Bool=false：导致列表列类型使用 Int64 偏移量数组写入；主要用于测试目的；默认情况下，仅在需要时才使用 Int64 偏移量
• maxdepth::Int=6：允许的最深嵌套序列化级别；默认提供此功能是为了防止具有相互递归数据结构的意外无限递归
• metadata=Arrow.getmetadata(tbl)：应作为表的架构的 custom_metadata 字段写入的元数据；必须是 nothing 或 <:AbstractString 对的可迭代对象。
• ntasks::Int：将输入分区作为 Arrow 记录批次写入时允许的缓冲线程任务数；默认值为无限制；对于非缓冲写入，请传递 ntasks=0
• file::Bool=false：如果正在写入 io 参数，则传递 file=true 将导致写入 Arrow 文件格式而不是仅仅写入 IPC 流

Scalar FlatBuffers 架构中允许的 Julia 类型 T <: Number 的联合

Builder 是用于创建 FlatBuffer 对象的状态机。使用 Builder 从叶节点开始构造对象。

为了简单和性能，Builder 以 last-first 的方式构造字节缓冲区。

表

包含特定于表的 flatbuffer 和位置信息的对象。包含特定成员偏移量的 vtable 位于 pos 之前。表中的实际值跟随 pos 偏移量和 vtable 的大小。

• bytes::Vector{UInt8}：flatbuffer 本身
• pos::Integer：表在 bytes 中的基准位置

createstring! 将以 null 结尾的字符串作为向量写入。

endobject 写入完成对象构造所需的数据。

endvector 写入完成向量构造所需的数据。

finish! 完成缓冲区，指向给定的 rootTable。

finishedbytes 返回一个指向字节缓冲区中已写入数据的指针。如果构建器未处于完成状态（这是由调用 finish!() 引起的），则会发生 panic。

GetVOffsetTSlot 检索给定 vtable 位置指向的 VOffsetT。如果 vtable 值为零，则将返回默认值 d。

getslot 检索给定 vtable 位置指向的 T。如果 vtable 值为零，则将返回默认值 d。

indirect 检索存储在 offset 处的相对偏移量。

offset 提供对表格 vtable 的访问。

通过检查 vtable 的长度来忽略已弃用的字段。

place! 将 T 添加到构建器的开头，而不检查空间。

prep! 准备在写入 additionalbytes 个字节后写入大小为 size 的元素，例如，如果您写入字符串，则需要对齐，使得 int 长度字段与 sizeof(Int32) 对齐，并且字符串数据紧随其后。如果您只需要进行对齐，则 additionalbytes 将为 0。

prependslot! 将 T 添加到 vtable 槽 o 处的对象的开头。如果值 x 等于默认值 d，则该槽将设置为零，并且不会写入其他数据。

prependstructslot! 将结构体添加到 vtable 槽 o 处的对象的开头。结构体是内联存储的，因此不会添加任何其他内容。在生成的代码中，d 始终为 0。

slot! 将 vtable 键 voffset 设置为缓冲区中的当前位置。

startvector 初始化用于写入新向量的簿记。

向量的格式如下：<UOffsetT：此向量中元素的数量> <T：数据>+，其中 T 是此向量元素的类型。

vector 检索此对象中偏移量存储在 off 处的向量的数据的起始位置。

vectorlen 检索此对象中偏移量存储在 off 处的向量的长度。

vtableEqual 将未写入的 vtable 与写入的 vtable 进行比较。

WriteVtable 序列化当前对象的 vtable（如果适用）。

在写出 vtable 之前，它会检查预先存在的 vtable 是否与此 vtable 相等。如果找到相等的 vtable，则将对象指向现有的 vtable 并返回。

由于 vtable 值对对象数据的对齐方式敏感，因此并非所有逻辑上相等的 vtable 都会被去重复。

vtable 具有以下格式：<VOffsetT：vtable 的大小（以字节为单位），包括此值> <VOffsetT：对象的大小（以字节为单位），包括 vtable 偏移量> <VOffsetT：字段的偏移量> * N，其中 N 是此类型的架构中的字段数。包括已弃用的字段。因此，vtable 由 2 + N 个元素组成，每个元素的宽度为 SizeVOffsetT 个字节。

对象的格式如下：<SOffsetT：此对象的 vtable 的偏移量（可以为负）> <字节：数据>+