API 参考

Arrow.ArrowVector

一个抽象类型，是 AbstractVector 的子类型。每种特定的 Arrow 数组类型都是 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)

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

Arrow.DictEncoded

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

Arrow.DictEncoding

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

S 类型参数，虽然没有直接与任何字段关联，但它是父级 DictEncoded 的有符号整数“索引类型”。我们在 DictEncoding 中跟踪这一点，以验证池的长度不超过索引类型的限制。写入 Arrow 数据的通用工作流程意味着初始模式通常基于第一个记录批次中的数据，并且后续的记录批次必须与相同的模式完全匹配。例如，如果一个非第一个记录批次的字典编码的列在唯一值上导致 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)

开始读取一个 Arrow 格式的表，来自

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

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

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

这允许以记录批次表示的块的形式迭代极其庞大的“Arrow 表”。

支持 convert 关键字参数，它控制是否将某些 Arrow 原始类型惰性转换为更友好的 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)

读取一个 Arrow 格式的表，来自

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

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

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

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

支持 convert 关键字参数，它控制是否将某些 Arrow 原始类型惰性转换为更友好的 Julia 默认值；默认情况下，convert=true。

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

包装数组，为 ZonedDateTime 元素提供更高效的编码到 Arrow 格式。在 Arrow 格式中，带有时区信息的*时间戳*列被编码为 Julia 类型参数的 Arrow 等价物，这意味着一整列*应该*所有元素都具有相同的时区。如果将 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{String,String}，其中键是 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 模式中的某些 Arrow 原始类型，是否应将其转换为 Julia 默认值以匹配 tbl 的模式；默认情况下，convert=true。
• file::Bool: 适用于提供了 IO 的情况，它是否是一个文件；默认 file=false。

给定一个 FlatBuffers.Builder 和一个 Julia 列或列的 eltype，写入 eltype 的 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 存储 eltype

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{String,String}，其中键是 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 是 T <: Number 的 Union，这些类型允许在 FlatBuffers 模式中使用

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

Builder 以后进先出的方式构建字节缓冲区，以求简单和性能。

表

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

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

createstring! 将一个空终止字符串写入为一个向量。

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

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

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

finishedbytes 返回指向字节缓冲区中写入数据的指针。如果构建器不在完成状态（这是通过调用 finish!() 引起的），则会恐慌。

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

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

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

offset 提供对 Table 的 vtable 的访问。

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

place! 将 T 预置到 Builder 中，不检查空间。

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

prependslot! 在 vtable 插槽 o 处将 T 预置到对象上。如果值 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 的偏移量（可能是负数）> <byte: 数据>+