/ /

PyMongo

Docs Home

Librerías de clientes

Python

PyMongo

Docs Home

Librerías de clientes

Python

PyMongo

Migrar a PyMongo asíncrono

Overview

La API asíncrona de PyMongo es una unificación de PyMongo y la Biblioteca de Motor. En esta guía, podrá identificar los cambios necesarios para migrar una aplicación de PyMongo o Motor a la API asíncrona de PyMongo.

Motivación

La API asíncrona de PyMongo está diseñada para reemplazar la biblioteca Motor. Motor se creó para brindar soporte a Tornado, con asyncio La compatibilidad se añadió posteriormente. Por ello, Motor ofrece asyncio compatibilidad total con y Tornado, pero aún depende de un grupo de subprocesos para realizar operaciones de red. En algunos casos, esto podría provocar una degradación del rendimiento al usar la biblioteca Motor. Para solucionar este problema, la API asíncrona de PyMongo implementa la asyncio compatibilidad con directamente en PyMongo. En la mayoría de los casos, la API asíncrona de PyMongo ofrece un rendimiento mejorado en comparación con Motor. Para ver las pruebas de rendimiento, consulte la sección "Pruebas de rendimiento".

Síncrono versus asíncrono

Para decidir migrar a la API asíncrona de PyMongo o continuar usando PyMongo sincrónico, considera la información de esta sección.

Es preferible PyMongo sincrónico si los siguientes criterios se aplican a su aplicación o caso de uso:

Su aplicación es simple de ejecutar, o prefiere evitar el uso de llamadas asincrónicas en su código
Su aplicación depende de cargas de trabajo en serie o con tiempos de respuesta muy rápidos
El usuario prefiere la simplicidad de la lógica síncrona al depurar la aplicación

Se debe considerar migrar a la API asíncrona de PyMongo si se aplican los siguientes criterios a la aplicación o caso de uso:

Su aplicación implementa grandes cargas de trabajo altamente concurrentes (del orden de miles de operaciones concurrentes)
Su aplicación depende de cargas de trabajo que pasan mucho tiempo esperando respuestas o escribiendo datos
Su aplicación depende de otras librerías o frameworks asíncronos, como FastAPI

Benchmarks de rendimiento

La siguiente tabla muestra los benchmarks de rendimiento para diferentes tareas realizadas con la API asíncrona de PyMongo y la librería Motor. Cada tarea se realizó con 10 iteraciones de 1000 documentos cada una. En la mayoría de los casos, la API asíncrona de PyMongo resulta en un mejor rendimiento en comparación con Motor.

Operación	Rendimiento de Motor	Rendimiento de PyMongo (asíncrono)
`TestFindManyAndEmptyCursor`	74.074 MB/s	112.490 MB/s
`TestFindManyAndEmptyCursor80Tasks`	37.181 MB/s	89.521 MB/s
`TestFindManyAndEmptyCursor8Tasks`	63.145 MB/s	97.165 MB/s
`TestFindOneByID`	3.121 MB/s	2.922 MB/s
`TestFindOneByID80Tasks`	3.789 MB/s	4.071 MB/s
`TestFindOneByID8Tasks`	3.697 MB/s	3.445 MB/s
`TestFindOneByIDUnlimitedTasks`	3.866 MB/s	4.171 MB/s
`TestGridFsDownload`	573.770 MB/s	603.578 MB/s
`TestGridFsUpload`	430.870 MB/s	444.445 MB/s
`TestLargeDocBulkInsert`	82.631 MB/s	102.105 MB/s
`TestLargeDocClientBulkInsert`	75.057 MB/s	90.345 MB/s
`TestLargeDocCollectionBulkInsert`	85.810 MB/s	101.838 MB/s
`TestLargeDocInsertOne`	84.832 MB/s	101.934 MB/s
`TestLargeDocInsertOneUnlimitedTasks`	120.389 MB/s	163.553 MB/s
`TestRunCommand`	0.036 MB/s	0.034 MB/s
`TestRunCommand80Tasks`	0.042 MB/s	0.043 MB/s
`TestRunCommand8Tasks`	0.039 MB/s	0.041 MB/s
`TestRunCommandUnlimitedTasks`	0.043 MB/s	0.042 MB/s
`TestSmallDocBulkInsert`	35.071 MB/s	38.213 MB/s
`TestSmallDocBulkMixedOps`	0.729 MB/s	0.446 MB/s
`TestSmallDocClientBulkInsert`	25.032 MB/s	25.727 MB/s
`TestSmallDocClientBulkMixedOps`	1.746 MB/s	1.723 MB/s
`TestSmallDocCollectionBulkInsert`	34.144 MB/s	37.666 MB/s
`TestSmallDocInsertOne`	0.539 MB/s	0.572 MB/s
`TestSmallDocInsertOneUnlimitedTasks`	0.740 MB/s	0.786 MB/s

Migra desde Motor

Advertencia

Motor queda obsoleto

Motor quedará obsoleto a partir del 14 de mayo de 2026. Recomendamos encarecidamente que los usuarios de Motor migren a la API asíncrona de PyMongo mientras Motor aún sea compatible.

La API asíncrona de PyMongo funciona de manera similar a la librería Motor, pero permite una menor latencia y un mayor rendimiento gracias al uso directo de Python asyncio en lugar de delegar el trabajo a un grupo de hilos. En la mayoría de los casos, puedes migrar directamente las aplicaciones de Motor existentes a PyMongo asíncrono utilizando AsyncMongoClient en lugar de MotorClient y cambiando las instrucciones de importación de la aplicación para importar desde pymongo.

El siguiente ejemplo muestra la diferencia en las importaciones para usar un cliente para operaciones de lectura y guardado en Motor en comparación con PyMongo asíncrono:

# Motor client import
from motor.motor_asyncio import AsyncIOMotorClient
# PyMongo Async client import
from pymongo import AsyncMongoClient

Para ver una lista de los métodos asíncronos disponibles en la API asíncrona de PyMongo, vea la sección Métodos asíncronos. Para aprender sobre las versiones de Motor que corresponden a PyMongo, consulte la página Compatibilidad.

La siguiente sección muestra los cambios en la firma del método que se debe implementar en la aplicación al migrar de motor a la API asíncrona de PyMongo.

Cambios en la firma del método

Las siguientes firmas de métodos de Motor se comportan de manera diferente en la API asíncrona de PyMongo:

AsyncMongoClient.__init__() no acepta un parámetro io_loop.
AsyncCursor.each() no existe en la API asíncrona de PyMongo.
MotorGridOut.stream_to_handler() no existe en la API asíncrona de PyMongo.
AsyncCursor.to_list(0) no es válido en la API asíncrona de PyMongo. Utiliza to_list(None) en su lugar.
MongoClient es seguro para hilos y puede ser utilizado por muchos hilos; sin embargo, un AsyncMongoClient no es seguro para hilos y solo debe ser utilizado por un único bucle de eventos.

Advertencia

Los usuarios de Motor pueden experimentar una degradación del rendimiento al cambiar a la API asíncrona de PyMongo. Esto se debe a que la API asíncrona de PyMongo utiliza tareas nativas de asyncio en vez de ejecutores basados en hilos. Los ejecutores basados en hilos tienen características de rendimiento similares a las del controlador síncrono, pero son más lentos. Esto significa que funcionan mejor para cargas de trabajo que no cumplen con los criterios anteriores para la API asíncrona de PyMongo.

Si se experimenta una ralentización del rendimiento, se debe identificar si la API asíncrona de PyMongo es necesaria para el caso de uso. Si se determina que el caso de uso requiere PyMongo sincrónico, se debe considerar usar el driver sincrónico con asyncio.loop.run_in_executor() para la compatibilidad asincrónica. Para aprender más, se debe consultar la documentación de la API del bucle de eventos.

Migra desde PyMongo

La API asíncrona de PyMongo se comporta de manera similar a PyMongo, pero todos los métodos que realizan operaciones de red son corrutinas y se deben esperar. Para migrar de PyMongo a PyMongo asíncrono, se debe actualizar el código de las siguientes maneras:

Reemplaza todos los usos de MongoClient por AsyncMongoClient.
Agregue la palabra clave await a todas las llamadas de métodos asíncronos.
Si ejecuta un método asíncrono dentro de una función, marque la función como async.

Tenga en cuenta los siguientes puntos al migrar de PyMongo síncrono a la API asíncrona de PyMongo:

Para convertir un AsyncCursor en una lista, debe usar el método asíncrono cursor.to_list().
El método AsyncCollection.find() en la API asíncrona de PyMongo es síncrono, pero devuelve un AsyncCursor. Para iterar sobre el cursor, debes usar un bucle de async for.
El objeto AsyncMongoClient no admite el argumento de la palabra clave connect.
No puede compartir objetos AsyncMongoClient a través de hilos o bucles de eventos.
Para acceder a una propiedad o método de un resultado devuelto por una llamada asíncrona, debe envolver correctamente la llamada entre paréntesis, como se muestra en el siguiente ejemplo:
```
id = (await posts.insert_one(doc)).inserted_id
```

Métodos asíncronos

Para una lista completa de métodos asíncronos disponibles en la API Async de PyMongo, consulte la documentación de la API.

Nota

Cualquier método que no esté listado en la documentación anterior de la API es síncrono.

Información Adicional

Para aprender más sobre Python asincrónico, consulta la documentación de Python asincrónico.

Volver

Guías de actualización

Versiones anteriores