Schema/数据类型对象

class ExtensionAccessor(schema)

扩展类型参数的访问器

property metadata: bytes

此扩展类型的扩展元数据（如果存在）

property name: str

此扩展类型的扩展名称

property storage

此扩展类型的存储类型

class Schema(obj, *, name=None, nullable=None, metadata=None, fields=None, **params)

创建 nanoarrow Schema

Schema 是 nanoarrow 的高级数据类型表示，它涵盖了 PyArrow 的 Schema、Field 和 DataType 的作用。此范围与 Arrow C Data 接口中的 ArrowSchema 映射。

参数

obj

一个 Type 说明符或类似 Schema 的对象。类似 Schema 的对象包括：* 一个 pyarrow.Schema、pyarrow.Field` 或 pyarrow.DataType * 一个 nanoarrow Schema、CSchema 或 Type * 任何实现 Arrow PyCapsule 接口协议方法的对象。

namestr, 可选

要绑定到此字段的可选名称。

nullablebool, 可选

明确指定字段是否可为空。字段默认可为空。

metadata映射, 可选

明确指定字段元数据。

params

当 obj 为 Type 时，特定于类型的参数。

示例

>>> import nanoarrow as na
>>> import pyarrow as pa
>>> na.Schema(na.Type.INT32)
<Schema> int32
>>> na.Schema(na.Type.DURATION, unit=na.TimeUnit.SECOND)
<Schema> duration('s')
>>> na.Schema(pa.int32())
<Schema> int32

property byte_width: int | None

固定大小二进制类型的元素字节宽度

对于与此属性不相关的类型，返回 None。

>>> import nanoarrow as na
>>> na.fixed_size_binary(123).byte_width
123

property dictionary_ordered: bool | None

字典排序

对于字典类型，如果字典值的顺序有意义，则返回 True。

>>> import nanoarrow as na
>>> na.dictionary(na.int32(), na.string()).dictionary_ordered
False

property extension: ExtensionAccessor | None

访问扩展类型属性

>>> import nanoarrow as na
>>> schema = na.extension_type(na.int32(), "arrow.example", b"{}")
>>> schema.extension.name
'arrow.example'
>>> schema.extension.metadata
b'{}'

field(i) → Schema

提取子 Schema

>>> import nanoarrow as na
>>> schema = na.struct({"col1": na.int32()})
>>> schema.field(0)
<Schema> 'col1': int32

property fields: List[Schema]

遍历子 Schema

>>> import nanoarrow as na
>>> schema = na.struct({"col1": na.int32()})
>>> for field in schema.fields:
...     print(field.name)
...
col1

property index_type: Schema | None

字典索引类型

对于字典类型，与索引对应的类型。另请参阅 value_type。

>>> import nanoarrow as na
>>> na.dictionary(na.int32(), na.string()).index_type
<Schema> int32

property key_type: Schema | None

Map 键类型

>>> import nanoarrow as na
>>> na.map_(na.int32(), na.string()).key_type
<Schema> 'key': non-nullable int32

property list_size: int | None

固定大小列表元素大小

>>> import nanoarrow as na
>>> na.fixed_size_list(na.int32(), 123).list_size
123

property metadata: Mapping[bytes, bytes]

访问此字段的字段元数据

>>> import nanoarrow as na
>>> schema = na.Schema(na.int32(), metadata={"key": "value"})
>>> dict(schema.metadata.items())
{b'key': b'value'}

property n_fields: int

子 Schema 的数量

>>> import nanoarrow as na
>>> schema = na.struct({"col1": na.int32()})
>>> schema.n_fields
1

property name: str | None

此 Schema 的字段名称

>>> import nanoarrow as na
>>> schema = na.struct({"col1": na.int32()})
>>> schema.field(0).name
'col1'

property nullable: bool

此字段的可空性

>>> import nanoarrow as na
>>> na.int32().nullable
True
>>> na.int32(nullable=False).nullable
False

property params: Mapping

获取此类型的参数名称和值

返回一个参数字典，可用于与类型标识符一起重建此类型。

>>> import nanoarrow as na
>>> na.fixed_size_binary(123).params
{'byte_width': 123}

property precision: int

十进制精度

>>> import nanoarrow as na
>>> na.decimal128(10, 3).precision
10

property scale: int

十进制小数位数

>>> import nanoarrow as na
>>> na.decimal128(10, 3).scale
3

serialize(dst=None) → bytes | None

将此 Schema 写入 dst 作为封装的 IPC 消息

参数

dst文件对象, 可选

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

property timezone: str | None

时间戳类型时区

对于与此属性不相关的类型或未设置时区的时区类型，返回 None。

>>> import nanoarrow as na
>>> na.timestamp(na.TimeUnit.SECOND, timezone="America/Halifax").timezone
'America/Halifax'

property type: Type

此 Schema 的类型枚举器值

>>> import nanoarrow as na
>>> na.int32().type
<Type.INT32: 8>

property unit: TimeUnit | None

时间戳、时间、持续时间类型的 TimeUnit

对于与此属性不相关的类型，返回 None。

>>> import nanoarrow as na
>>> na.timestamp(na.TimeUnit.SECOND).unit
<TimeUnit.SECOND: 0>

property value_type: Schema | None

字典、映射或列表值类型

>>> import nanoarrow as na
>>> na.list_(na.int32()).value_type
<Schema> 'item': int32
>>> na.map_(na.int32(), na.string()).value_type
<Schema> 'value': string
>>> na.dictionary(na.int32(), na.string()).value_type
<Schema> string

class TimeUnit(*values)

时间戳、持续时间和时间类型的单位枚举器。

static create(obj)

从参数输入创建 TimeUnit。

此构造函数将接受缩写“s”、“ms”、“us”和“ns”并返回适当的枚举器值。

>>> import nanoarrow as na
>>> na.TimeUnit.create("s")
<TimeUnit.SECOND: 0>

class Type(*values)

Type 枚举器提供了一种识别各种类型类别的方法。Type 值可以在大多数地方代替 Schema 实例用于无参数类型。

binary(nullable: bool = True) → Schema

创建可变或固定宽度二进制类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.binary()
<Schema> binary

binary_view(nullable: bool = True) → Schema

创建二进制视图类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.binary_view()
<Schema> binary_view

bool_(nullable: bool = True) → Schema

创建布尔类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.bool_()
<Schema> bool

date32(nullable: bool = True) → Schema

创建 32 位日期类型（自 1970-01-01 以来的天数）的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.date32()
<Schema> date32

date64(nullable: bool = True) → Schema

创建 64 位日期类型（自 1970-01-01 以来的毫秒数）的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.date64()
<Schema> date64

decimal128(precision: int, scale: int, nullable: bool = True) → Schema

创建 128 位十进制类型的实例。

参数

precisionint

此类型可表示的有效位数。必须介于 1 和 38 之间。

scaleint

此类型值的小数点后的位数。

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.decimal128(10, 3)
<Schema> decimal128(10, 3)

decimal256(precision: int, scale: int, nullable: bool = True) → Schema

创建 256 位十进制类型的实例。

参数

precisionint

此类型可表示的有效位数。必须介于 1 和 76 之间。

scaleint

此类型值的小数点后的位数。

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.decimal256(10, 3)
<Schema> decimal256(10, 3)

dictionary(index_type, value_type, dictionary_ordered: bool = False) → Schema

创建表示字典编码值的类型

参数

index_type类似 Schema 的

索引的数据类型。必须是整数类型。

value_type类似 Schema 的

字典数组的类型。

ordered: bool, 可选

如果字典数组中值的顺序有意义，则使用 True。

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.dictionary(na.int32(), na.string())
<Schema> dictionary(int32)<string>

duration(unit, nullable: bool = True) → Schema

创建持续时间类型的实例。

参数

unitstr 或 TimeUnit

此类型存储值的单位。

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.duration("s")
<Schema> duration('s')

extension_type(storage_schema, extension_name: str, extension_metadata: str | bytes | None = None, nullable: bool = True) → Schema

创建 Arrow 扩展类型

参数

extension_name: str

与此类型关联的扩展名称。

extension_metadata: str 或 bytes, 可选

包含与此扩展类型关联的扩展参数的扩展元数据。

nullablebool, 可选

使用 False 将此字段标记为不可为空。

fixed_size_binary(byte_width: int, nullable: bool = True) → Schema

创建可变或固定宽度二进制类型的实例。

参数

byte_widthint

每个元素的字节宽度。

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.fixed_size_binary(123)
<Schema> fixed_size_binary(123)

fixed_size_list(value_type, list_size: int, nullable: bool = True) → Schema

创建表示其他类型的固定大小列表的类型。

参数

value_type类似 Schema 的

每个列表元素中值的类型。

list_sizeint

每个列表元素中值的数量。

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.fixed_size_list(na.int32(), 123)
<Schema> fixed_size_list(123)<item: int32>

float16(nullable: bool = True) → Schema

创建 16 位浮点类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.float16()
<Schema> half_float

float32(nullable: bool = True) → Schema

创建 32 位浮点类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.float32()
<Schema> float

float64(nullable: bool = True) → Schema

创建 64 位浮点类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.float64()
<Schema> double

int16(nullable: bool = True) → Schema

创建有符号 16 位整数类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.int16()
<Schema> int16

int32(nullable: bool = True) → Schema

创建有符号 32 位整数类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.int32()
<Schema> int32

int64(nullable: bool = True) → Schema

创建有符号 32 位整数类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.int64()
<Schema> int64

int8(nullable: bool = True) → Schema

创建有符号 8 位整数类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.int8()
<Schema> int8

interval_day_time(nullable: bool = True) → Schema

创建以日/时间对测量的间隔类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.interval_day_time()
<Schema> interval_day_time

interval_month_day_nano(nullable: bool = True) → Schema

创建以月/日/纳秒元组测量的间隔类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.interval_month_day_nano()
<Schema> interval_month_day_nano

interval_months(nullable: bool = True) → Schema

创建以月为单位测量的间隔类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.interval_months()
<Schema> interval_months

large_binary(nullable: bool = True) → Schema

创建使用 64 位偏移量的可变长度二进制类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.large_binary()
<Schema> large_binary

large_list(value_type, nullable: bool = True) → Schema

创建表示其他类型的可变大小列表的类型。

与 list_() 不同，func:large_list 可以容纳值数组中超过 2 ** 31 - 1 个项目的数组。

参数

value_type类似 Schema 的

每个列表元素中值的类型。

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.large_list(na.int32())
<Schema> large_list<item: int32>

large_string(nullable: bool = True) → Schema

创建使用 64 位偏移量的可变长度 UTF-8 编码字符串类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.large_string()
<Schema> large_string

list_(value_type, nullable: bool = True) → Schema

创建表示其他类型的可变大小列表的类型。

参数

value_type类似 Schema 的

每个列表元素中值的类型。

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.list_(na.int32())
<Schema> list<item: int32>

map_(key_type, value_type, keys_sorted: bool = False, nullable: bool = True)

创建表示键/值映射列表的类型

请注意，列表中的每个元素可能包含许多键/值对（并且映射数组可能包含许多单独的映射）。

参数

value_type类似 Schema 的

每个映射元素中键的类型。

value_type类似 Schema 的

每个映射元素中值的类型

keys_sortedbool, 可选

如果每个映射元素中的键已排序，则为 True。

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.map_(na.int32(), na.string())
<Schema> map<entries: struct<key: int32, value: string>>

null(nullable: bool = True) → Schema

创建 null 类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.null()
<Schema> na

schema(obj, **kwargs) → Schema

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

string(nullable: bool = True) → Schema

创建可变长度 UTF-8 编码字符串类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.string()
<Schema> string

string_view(nullable: bool = True) → Schema

创建字符串视图类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.string_view()
<Schema> string_view

struct(fields, nullable: bool = True) → Schema

创建表示命名字段序列的类型。

参数

fields

• 一个字典，其键是字段名称，值是类似 Schema 的对象

• 一个可迭代对象，其项目是类似 Schema 的对象，其中字段名称从类似 Schema 的对象继承。

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.struct([na.int32()])
<Schema> struct<: int32>
>>> na.struct({"col1": na.int32()})
<Schema> struct<col1: int32>

time32(unit: str | TimeUnit, nullable: bool = True) → Schema

创建 32 位日间时间类型的实例。

参数

unitstr 或 TimeUnit

此类型存储值的单位。

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.time32("s")
<Schema> time32('s')

time64(unit: str | TimeUnit, nullable: bool = True) → Schema

创建 64 位日间时间类型的实例。

参数

unitstr 或 TimeUnit

此类型存储值的单位。

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.time64("us")
<Schema> time64('us')

timestamp(unit: str | TimeUnit, timezone: str | None = None, nullable: bool = True) → Schema

创建时间戳类型的实例。

参数

unitstr 或 TimeUnit

此类型存储值的单位。

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.timestamp("s")
<Schema> timestamp('s', '')
>>> na.timestamp("s", timezone="America/Halifax")
<Schema> timestamp('s', 'America/Halifax')

uint16(nullable: bool = True) → Schema

创建无符号 16 位整数类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.uint16()
<Schema> uint16

uint32(nullable: bool = True) → Schema

创建无符号 32 位整数类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.uint32()
<Schema> uint32

uint64(nullable: bool = True) → Schema

创建无符号 32 位整数类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.uint64()
<Schema> uint64

uint8(nullable: bool = True) → Schema

创建无符号 8 位整数类型的实例。

参数

nullablebool, 可选

使用 False 将此字段标记为不可为空。

示例

>>> import nanoarrow as na
>>> na.uint8()
<Schema> uint8