高级 ArrayStream 实现

class Array(obj, schema=None, device=None)

高级内存中数组表示

Array 是 nanoarrow 的高级内存中数组表示，其范围映射到 Arrow C Data 接口中完全消耗的 ArrowArrayStream 的范围。

Array 类是 nanoarrow 的高级内存中数组表示，包含了 PyArrow 的 Array、ChunkedArray、RecordBatch 和 Table 的角色。此范围映射到 Arrow C Stream 接口所表示的完全消耗的 ArrowArrayStream 的范围。

请注意，Array 不一定在内存中是连续的（即，它可能由零个或多个 ArrowArray 对象组成）。

参数

objarray 或 array stream-like

经 c_array_stream() 清理过的类数组或类数组流对象。

schema类 schema，可选

一个可选的 schema，传递给 c_array_stream()。

deviceDevice，可选

与此 Array 所持有的缓冲区关联的设备。默认为 CPU 设备。

示例

>>> import nanoarrow as na
>>> na.Array([1, 2, 3], na.int32())
nanoarrow.Array<int32>[3]
1
2
3

buffer(i: int) → CBufferView

访问连续数组的单个缓冲区

示例

>>> import nanoarrow as na
>>> array = na.Array([1, 2, 3], na.int32())
>>> array.buffer(1)
nanoarrow.c_buffer.CBufferView(int32[12 b] 1 2 3)

property buffers: Tuple[CBufferView, ...]

访问连续数组的缓冲区。

示例

>>> import nanoarrow as na
>>> array = na.Array([1, 2, 3], na.int32())
>>> for buffer in array.buffers:
...     print(buffer)
nanoarrow.c_buffer.CBufferView(bool[0 b] )
nanoarrow.c_buffer.CBufferView(int32[12 b] 1 2 3)

child(i: int)

从其父级借用一个子 Array。

参数

iint

要返回的子级的索引。

示例

>>> import nanoarrow as na
>>> import pyarrow as pa
>>> batch = pa.record_batch(
...     [pa.array([1, 2, 3]), pa.array(["a", "b", "c"])],
...     names=["col1", "col2"]
... )
>>> array = na.Array(batch)
>>> array.child(1)
nanoarrow.Array<'col2': string>[3]
'a'
'b'
'c'

chunk(i: int)

从底层表示中提取单个连续的 Array。

参数

iint

要提取的块的索引。

示例

>>> import nanoarrow as na
>>> array = na.Array([1, 2, 3], na.int32())
>>> array.chunk(0)
nanoarrow.Array<int32>[3]
1
2
3

property device: Device

获取此数组的缓冲区所在的设备

示例

>>> import nanoarrow as na
>>> array = na.Array([1, 2, 3], na.int32())
>>> array.device
<nanoarrow.device.Device>
- device_type: CPU <1>
- device_id: -1

static from_chunks(obj: Iterable, schema=None, validate: bool = True)

创建具有显式块的 Array

从可转换为 c_array() 的可迭代对象创建具有显式块的 Array。

参数

obj可迭代的类数组对象

可传递给 c_array() 的可迭代对象。

schema类 schema，可选

一个可选的 schema。如果存在，将传递给 obj 中每个项的 c_array()；如果不存在，则将从第一个块推断。

validatebool

使用 False 放弃构建此数组时执行的验证步骤。

示例

>>> import nanoarrow as na
>>> na.Array.from_chunks([[1, 2, 3], [4, 5, 6]], na.int32())
nanoarrow.Array<int32>[6]
1
2
3
4
5
6

inspect()

打印数组的详细信息（类型、长度、偏移量、缓冲区和子数组）。

iter_children() → Iterable

迭代此 Array 的子级

示例

>>> import nanoarrow as na
>>> import pyarrow as pa
>>> batch = pa.record_batch(
...     [pa.array([1, 2, 3]), pa.array(["a", "b", "c"])],
...     names=["col1", "col2"]
... )
>>> array = na.Array(batch)
>>> for child in array.iter_children():
...     print(child)
nanoarrow.Array<'col1': int64>[3]
1
2
3
nanoarrow.Array<'col2': string>[3]
'a'
'b'
'c'

iter_chunk_views() → Iterable[CArrayView]

迭代每个块的准备好的视图

示例

>>> import nanoarrow as na
>>> array = na.Array([1, 2, 3], na.int32())
>>> for view in array.iter_chunk_views():
...     offset, length = view.offset, len(view)
...     validity, data = view.buffers
...     print(offset, length)
...     print(validity)
...     print(data)
0 3
nanoarrow.c_buffer.CBufferView(bool[0 b] )
nanoarrow.c_buffer.CBufferView(int32[12 b] 1 2 3)

iter_chunks() → Iterable

迭代底层表示中缓冲区在内存中连续的 Array。

示例

>>> import nanoarrow as na
>>> array = na.Array([1, 2, 3], na.int32())
>>> for chunk in array.iter_chunks():
...     print(chunk)
nanoarrow.Array<int32>[3]
1
2
3

iter_py() → Iterable

迭代每个元素的默认 Python 表示。

示例

>>> import nanoarrow as na
>>> array = na.Array([1, 2, 3], na.int32())
>>> for item in array.iter_py():
...     print(item)
1
2
3

iter_scalar() → Iterable[Scalar]

将项目作为标量进行迭代

示例

>>> import nanoarrow as na
>>> array = na.Array([1, 2, 3], na.int32())
>>> for item in array.iter_scalar():
...     print(item)
Scalar<int32> 1
Scalar<int32> 2
Scalar<int32> 3

iter_tuples() → Iterable[Tuple]

将结构数组的行作为元组进行迭代。

示例

>>> import nanoarrow as na
>>> import pyarrow as pa
>>> batch = pa.record_batch(
...     [pa.array([1, 2, 3]), pa.array(["a", "b", "c"])],
...     names=["col1", "col2"]
... )
>>> array = na.Array(batch)
>>> for item in array.iter_tuples():
...     print(item)
(1, 'a')
(2, 'b')
(3, 'c')

property n_buffers: int

获取此 Array 的每个块中的缓冲区数量

示例

>>> import nanoarrow as na
>>> array = na.Array([1, 2, 3], na.int32())
>>> array.n_buffers
2

property n_children: int

获取此类型 Array 的子级数量。

示例

>>> import nanoarrow as na
>>> import pyarrow as pa
>>> batch = pa.record_batch(
...     [pa.array([1, 2, 3]), pa.array(["a", "b", "c"])],
...     names=["col1", "col2"]
... )
>>> array = na.Array(batch)
>>> array.n_children
2

property n_chunks: int

获取此 Array 底层表示中的块数量。

示例

>>> import nanoarrow as na
>>> array = na.Array([1, 2, 3], na.int32())
>>> array.n_chunks
1

property offset: int

访问连续数组的逻辑偏移量

示例

>>> import nanoarrow as na
>>> c_array = na.c_array([1, 2, 3], na.int32())
>>> na.Array(c_array[1:]).offset
1

property schema: Schema

获取此 Array 的 schema（数据类型）

serialize(dst=None) → bytes | None

将此 Array 写入 dst，作为零个或多个封装的 IPC 消息

参数

dst文件类对象，可选

如果存在，一个文件类对象，此数组的块应序列化到其中。如果省略，这将创建一个 io.BytesIO() 并返回序列化结果。

class Scalar

围绕 Array 元素的通用包装器

此类旨在为 Array 提供类数组索引的通用实现。这些对象目前只能通过从 Array 中提取元素来创建。

请注意，迭代 Scalar 对象通常效率不高：使用 nanoarrow.iterator 中的迭代器可以更有效地迭代 Array。

示例

>>> import nanoarrow as na
>>> array = na.Array([1, 2, 3], na.int32())
>>> array[0]
Scalar<int32> 1
>>> array[0].as_py()
1
>>> array[0].schema
<Schema> int32

as_py()

获取此标量的 Python 对象表示

property schema: Schema

获取此标量的 schema（数据类型）

array(obj, schema=None) → Array

Array 类构造函数的别名。建议使用 nanoarrow.Array() 而非 nanoarrow.array()。