高级 ArrayStream 实现

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

高级内存中数组表示

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

Array 类是 nanoarrow 的高级内存中数组表示，它包含了 PyArrow 的 Array、ChunkedArray、RecordBatch 和 Table 的作用。该范围映射到 Arrow C 流接口中完全消费的 ArrowArrayStream。

注意，Array 不一定在内存中是连续的（即，它可能包含零个或多个``ArrowArray``）。

参数

obj数组或类似数组流

由 c_array_stream() 筛选的类似数组或类似数组流的对象。

schema类似模式，可选

可选模式，传递给 c_array_stream()。

device设备，可选

与该数组持有的缓冲区相关的设备。默认为 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)

从其父级借用子数组。

参数

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)

从底层表示中提取单个连续数组。

参数

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)

使用显式块创建数组

使用可转换为 c_array() 的对象的 iterable，创建一个具有显式块的 Array。

参数

obj类似数组的 iterable

可以传递给 c_array() 的对象的 iterable。

schema类似模式，可选

可选模式。如果存在，将传递给 c_array() 以用于 obj 中的每个项目；如果不存在，它将从第一个块推断。

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

迭代该数组的子级

示例

>>> 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

迭代底层表示中的数组，这些数组的缓冲区在内存中是连续的。

示例

>>> 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

获取该数组中每个块中的缓冲区数量

示例

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

property n_children: int

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

示例

>>> 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

获取该数组底层表示中的块数。

示例

>>> 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

获取该数组的模式（数据类型）

serialize(dst=None) → bytes | None

将此数组写入 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

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

array(obj, schema=None) → Array

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