/ /

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 tipos BSON. Dado que Arrow y los polares ofrecen compatibilidad de primera clase con listas y estructuras, esto incluye matrices y documentos incrustados.

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

Tip

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

Tipo BSON	Identificadores de tipo
String	`py.str` Instancia de `pyarrow.string`
Documento incrustado	`py.dict` Instancia de `pyarrow.struct`
Matriz incrustada	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 64bits	`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 resolución `ms`
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 entero de 32bits 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 una matriz incrustada debe usar el tipo pyarrow.list_() para especificar el tipo de los elementos de la matriz. 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 bson apropiado.

>>> 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 arrays admiten valores NULL. Pandas tiene tipos de datos experimentales que admiten valores NULL,Int64 como. Puedes indicarle a Arrow que cree un DataFrame de Pandas usando tipos de datos que admiten valores NULL con el siguiente código de la 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.

Tipos de extensión anidados

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

Estos valores se pueden consumir tal cual o convertir 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 discrepancias de tipo a NaN, pase el argumento allow_invalid=True a su llamada a la API pymongoarrow. El siguiente ejemplo pasa allow_invalid=True a la llamada a la API pymongoarrow para convertir las discrepancias en los datos de muestra a 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