/ /

PyMongoArrow

Docs Home

Librerías de clientes

Python

PyMongoArrow

Docs Home

Librerías de clientes

Python

PyMongoArrow

Tipos de datos

PyMongoArrow admite la mayoría de los BSON types. Como Arrow y Polars ofrecen soporte de primera clase para listas y estructuras, esto incluye arreglos y documentos incrustados.

Se añadirá soporte para tipos adicionales en versiones posteriores.

Tip

Para obtener más información sobre los tipos BSON, consulta la Especificación BSON.

Tipo BSON	Identificadores de tipo
String	`py.str` Instancia de `pyarrow.string`
embeddedDocument	`py.dict` Instancia de `pyarrow.struct`
Arreglo incrustado	Instancia de `pyarrow.list_`
ObjectId	`py.bytes` `bson.ObjectId` Instancia de `pymongoarrow.types.ObjectIdType` Instancia de `pymongoarrow.pandas_types.PandasObjectId`
Decimal128	`bson.Decimal128` Instancia de `pymongoarrow.types.Decimal128Type` Instancia de `pymongoarrow.pandas_types.PandasDecimal128` Instancia de `pyarrow.Decimal128`
Booleano	`~py.bool` Instancia de `~pyarrow.bool_`
punto flotante binario de 64 bits	`py.float` Instancia de `pyarrow.float64`
entero de 32 bits	Instancia de `pyarrow.int32`
entero de 64 bits	`~py.int` `bson.int64.Int64` Instancia de `pyarrow.int64`
Fecha y hora UTC	`py.datetime.datetime` Instancia de `~pyarrow.timestamp` con `ms` resolución
Datos binarios	`bson.Binary` Instancia de `pymongoarrow.types.BinaryType` Instancia de `pymongoarrow.pandas_types.PandasBinary`
Código JavaScript	`bson.Code` Instancia de `pymongoarrow.types.CodeType` Instancia de `pymongoarrow.pandas_types.PandasCode`
Nulo	Instancia de `pyarrow.null`

Nota

PyMongoArrow solo admite Decimal128 en sistemas little-endian. En sistemas big-endian, usa null.

Utilice identificadores de tipo para especificar que un campo es de un tipo determinado durante la declaración pymongoarrow.api.Schema. Por ejemplo, si sus datos tienen los campos f1 y f2 con tipos enteros de 32 bits y fecha y hora UTC, y un _id que es un ObjectId, puede definir su esquema de la siguiente manera:

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

Los tipos de datos no admitidos en un esquema generan un ValueError que identifica el campo y su tipo de dato.

Consideraciones sobre matrices integradas

El esquema utilizado para un arreglo anidado debe usar el tipo pyarrow.list_(), para especificar el tipo de los elementos del arreglo. Por ejemplo,

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

Tipos de extensión

PyMongoArrow implementa los tipos ObjectId, Decimal128, Binary data y JavaScript code como tipos de extensión para PyArrow y Pandas. En las tablas de flechas, los valores de estos tipos tienen el tipo de extensión pymongoarrow adecuado, como pymongoarrow.types.ObjectIdType. Puede obtener el objeto de Python bson adecuado mediante el método .as_py() o llamando a .to_pylist() en la tabla.

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

Al convertir a pandas, las columnas de tipo de extensión tienen un tipo de extensión pymongoarrow apropiado, como pymongoarrow.pandas_types.PandasDecimal128. El valor del elemento en el dataframe es del tipo adecuado 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')

Polars no admite tipos de extensión.

Valores nulos y conversión a DataFrames de Pandas

En Arrow y Polars, todos los arreglos son nulos. Pandas tiene tipos de datos admiten valores nulos experimentales, como Int64. Puede instruir a Arrow para que cree un DataFrame de pandas utilizando tipos de datos anulables con el siguiente Código de documentación de Apache.

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

Definir una conversión para pa.string() también convierte cadenas Arrow en cadenas NumPy, y no objetos.

Extensiones de tipos anidados

Pendiente ARROW-179, los tipos de extensión, como ObjectId, que aparecen en documentos anidados no se convierten al tipo de extensión correspondiente de PyMongoArrow, sino que tienen el tipo Arrow bruto, FixedSizeBinaryType(fixed_size_binary[12]).

Estos valores pueden ser consumidos tal cual, o convertidos individualmente al tipo de extensión deseado, como _id = out['nested'][0]['_id'].cast(ObjectIdType()).

Adherencia estricta al tipo

Al proporcionar un esquema para datos en PyMongoArrow v1.9 y versiones posteriores, el controlador aplica una estricta adherencia a los tipos. Si el valor de un campo presenta una discrepancia de tipo con el tipo del esquema para ese campo, el controlador genera un TypeError. NaN es un tipo válido para todos los campos.

Para suprimir TypeErrors y convertir silenciosamente las incompatibilidades de tipo en NaN, pase el argumento allow_invalid=True a su llamada a la API pymongoarrow. El siguiente ejemplo pasa allow_invalid=True a la llamada API pymongoarrow para convertir las incompatibilidades en los datos de muestra en NaN:

>>> from pymongoarrow.monkey import patch_all
>>> from pymongoarrow.api import Schema, find_arrow_all
>>> from pyarrow import int32, string
>>> from pymongo import MongoClient
>>> patch_all()
>>> client = MongoClient()
>>> coll = client.test.test
>>> sample_data = [
...     {"name": "Alice", "age": 35, "city": "Chicago"},
...     {"name": {"first": "Bob", "last": "Smith"}, "age": 28, "city": "Boston"},
...     {"name": "Charlie", "age": "thirty-two", "city": "Seattle"}
... ]
>>> coll.insert_many(sample_data)
>>> schema = Schema({
...     "name": string(),
...     "age": int32(),
...     "city": string()
... })
>>> result = find_arrow_all(collection, {}, schema=schema, allow_invalid=True)

Volver

Empezar

Ejemplos de esquemas