Docs 菜单
Docs 主页
/
语言
/
Python
/
PyMongoArrow

数据类型

在此页面上

  • 嵌入式数组注意事项
  • 扩展类型
  • Null 值和转换为 Pandas DataFrame
  • 嵌套扩展类型

PyMongoArrow 支持大多数 BSON types。由于 Arrow 和Polars 为列表和结构体提供一流的支持，因此包括嵌入式数组和文档。

后续版本中将添加对其他类型的支持。

提示

有关BSON types 的详细信息，请参阅BSON 规范。

BSON 类型
类型标识符
字符串
py.str，一个实例 pyarrow.string
嵌入式文档
py.dict，以及实例 pyarrow.struct
嵌入式数组
的实例 pyarrow.list_
ObjectId
py.bytes、 bson.ObjectId 、 pymongoarrow.types.ObjectIdType的实例、 pymongoarrow.pandas_types.PandasObjectId的实例
Decimal128
bson.Decimal128、 pymongoarrow.types.Decimal128Type的实例、 pymongoarrow.pandas_types.PandasDecimal128的实例
布尔
~pyarrow.bool_ 、 ~py.bool的实例
64 位二进制浮点点
py.float，一个实例 pyarrow.float64
32 位整数
的实例 pyarrow.int32
64 位整型
~py.int、 bson.int64.Int64 、 pyarrow.int64的实例
UTC 日期时间
具有ms解析的~pyarrow.timestamp实例， py.datetime.datetime
二进制数据
bson.Binary、一个pymongoarrow.types.BinaryType的实例、一个pymongoarrow.pandas_types.PandasBinary的实例。
JavaScript 代码
bson.Code、 pymongoarrow.types.CodeType的实例、 pymongoarrow.pandas_types.PandasCode的实例

注意

PyMongoArrow 仅在小端系统上支持Decimal128 。 在大端系统上，它使用null代替。

在pymongoarrow.api.Schema声明期间，使用类型标识符指定字段属于特定类型。 例如，如果数据的字段f1和f2的类型为 32 位整数和 UTC 日期时间，并且_id是ObjectId ，则可以按如下方式定义模式：

schema = Schema({
  '_id': ObjectId,
  'f1': pyarrow.int32(),
  'f2': pyarrow.timestamp('ms')
})

模式中不支持的数据类型会导致标识字段及其数据类型的ValueError 。

嵌入式数组注意事项

用于嵌入式数组的模式必须使用pyarrow.list_()类型，以指定数组元素的类型。 例如，

from pyarrow import list_, float64
schema = Schema({'_id': ObjectId,
  'location': {'coordinates': list_(float64())}
})

扩展类型

PyMongoArrow 将ObjectId 、 Decimal128 、 Binary data和JavaScript code类型实现为 PyArrow 和 Pandas 的扩展类型。 对于箭头表，这些类型的值具有适当的pymongoarrow扩展类型，例如pymongoarrow.types.ObjectIdType 。 您可以使用.as_py()方法或对表调用.to_pylist()来获取适当的bson Python 对象。

>>> from pymongo import MongoClient
>>> from bson import ObjectId
>>> from pymongoarrow.api import find_arrow_all
>>> client = MongoClient()
>>> coll = client.test.test
>>> coll.insert_many([{"_id": ObjectId(), "foo": 100}, {"_id": ObjectId(), "foo": 200}])
<pymongo.results.InsertManyResult at 0x1080a72b0>
>>> table = find_arrow_all(coll, {})
>>> table
pyarrow.Table
_id: extension<arrow.py_extension_type<ObjectIdType>>
foo: int32
----
_id: [[64408B0D5AC9E208AF220142,64408B0D5AC9E208AF220143]]
foo: [[100,200]]
>>> table["_id"][0]
<pyarrow.ObjectIdScalar: ObjectId('64408b0d5ac9e208af220142')>
>>> table["_id"][0].as_py()
ObjectId('64408b0d5ac9e208af220142')
>>> table.to_pylist()
[{'_id': ObjectId('64408b0d5ac9e208af220142'), 'foo': 100},
 {'_id': ObjectId('64408b0d5ac9e208af220143'), 'foo': 200}]

转换为 Pandas 时，扩展类型列具有适当的pymongoarrow扩展类型，例如pymongoarrow.pandas_types.PandasDecimal128 。 数据框中元素的值是适当的bson类型。

>>> from pymongo import MongoClient
>>> from bson import Decimal128
>>> from pymongoarrow.api import find_pandas_all
>>> client = MongoClient()
>>> coll = client.test.test
>>> coll.insert_many([{"foo": Decimal128("0.1")}, {"foo": Decimal128("0.1")}])
<pymongo.results.InsertManyResult at 0x1080a72b0>
>>> df = find_pandas_all(coll, {})
>>> df
                       _id  foo
0  64408bf65ac9e208af220144  0.1
1  64408bf65ac9e208af220145  0.1
>>> df["foo"].dtype
<pymongoarrow.pandas_types.PandasDecimal128 at 0x11fe0ae90>
>>> df["foo"][0]
Decimal128('0.1')
>>> df["_id"][0]
ObjectId('64408bf65ac9e208af220144')

不支持扩展类型。

Null 值和转换为 Pandas DataFrame

在 Arrow 和Polars 中，所有数组均可为 null。 Pandas 具有实验性可空数据类型，例如Int64 。 您可以通过以下 Apache 文档代码指示 Arrow 使用可为 null 的数据类型创建一个 pandas DataFrame。

>>> dtype_mapping = {
...     pa.int8(): pd.Int8Dtype(),
...     pa.int16(): pd.Int16Dtype(),
...     pa.int32(): pd.Int32Dtype(),
...     pa.int64(): pd.Int64Dtype(),
...     pa.uint8(): pd.UInt8Dtype(),
...     pa.uint16(): pd.UInt16Dtype(),
...     pa.uint32(): pd.UInt32Dtype(),
...     pa.uint64(): pd.UInt64Dtype(),
...     pa.bool_(): pd.BooleanDtype(),
...     pa.float32(): pd.Float32Dtype(),
...     pa.float64(): pd.Float64Dtype(),
...     pa.string(): pd.StringDtype(),
... }
... df = arrow_table.to_pandas(
...     types_mapper=dtype_mapping.get, split_blocks=True, self_destruct=True
... )
... del arrow_table

为pa.string()定义转换还会将 Arrow 字符串转换为 NumPy 字符串，而不是对象。

嵌套扩展类型

待处理 ARROW-179 ，出现在嵌套文档中的扩展类型（例如ObjectId ）不会转换为相应的 PyMongoArrow 扩展类型，而是具有原始 Arrow 类型FixedSizeBinaryType(fixed_size_binary[12]) 。

这些值可以按原样使用，也可以单独转换为所需的扩展类型，例如_id = out['nested'][0]['_id'].cast(ObjectIdType()) 。

后退

与 PyMongo 比较