/ /

/ /

Librerías de clientes

Python

PyMongo

Operaciones CRUD

Transacciones

Overview

En esta guía, aprenderá a usar el controlador de PyMongo para realizar transacciones. Las transacciones permiten ejecutar una serie de operaciones que no modifican ningún dato hasta que se confirman. Si alguna operación de la transacción devuelve un error, el controlador la cancela y descarta todos los cambios de datos antes de que sean visibles.

En MongoDB, las transacciones se ejecutan dentro de sesiones lógicas. Una sesión es una agrupación de operaciones de lectura o escritura relacionadas que se ejecutan secuencialmente. Las sesiones permiten ejecutar operaciones en una transacción compatible con ACID, que cumple con los requisitos de atomicidad, consistencia, aislamiento y durabilidad. MongoDB garantiza que los datos involucrados en las transacciones se mantengan consistentes, incluso si se producen errores inesperados.

Al usar PyMongo, puedes crear una nueva sesión desde una MongoClient Instancia de tipo ClientSession. Recomendamos reutilizar su MongoClient para múltiples sesiones y transacciones en lugar de crear un nuevo cliente cada vez.

Advertencia

Use un ClientSession solo con el MongoClient (o el MongoDatabase o MongoCollection asociado) que lo creó. Usar un ClientSession con un MongoClient diferente genera errores de operación.

Coherencia causal

MongoDB permite la consistencia causal en las sesiones de cliente. El modelo de consistencia causal garantiza que las operaciones dentro de una sesión se ejecuten en un orden causal. Los clientes observan resultados consistentes con las relaciones causales o las dependencias entre operaciones. Por ejemplo, si se realiza una serie de operaciones donde una depende lógicamente del resultado de otra, las lecturas posteriores reflejan la relación de dependencia.

Nota

Una sesión de cliente permite la coherencia causal incluso si no realiza una transacción.

La siguiente tabla describe las garantías que brindan las sesiones causalmente consistentes:

Garantía	Descripción
Leer las escrituras	Las operaciones de lectura reflejan los resultados de las operaciones de escritura anteriores.
Lecturas monotónicas	Las operaciones de lectura no devuelven resultados que reflejen un estado de datos anterior al de una operación de lectura anterior.
Escrituras monotónicas	Si una operación de escritura debe preceder a otras operaciones de escritura, el controlador ejecuta primero esta operación de escritura. Por ejemplo, si llama a `insert_one()` para insertar un documento y luego llama a `update_one()` para modificar el documento insertado, el controlador ejecuta primero la operación de inserción.
Las escrituras siguen a las lecturas	Si una operación de escritura debe seguir a otras operaciones de lectura, el controlador ejecuta primero las operaciones de lectura. Por ejemplo, si llama a `find()` para recuperar un documento y luego llama a `delete_one()` para eliminar el documento recuperado, el controlador ejecuta primero la operación de búsqueda.

En una sesión causalmente consistente, MongoDB garantiza la consistencia causal únicamente entre las siguientes operaciones:

Operaciones de lectura que tienen una preocupación de lectura majority
Operaciones de escritura que tienen una preocupación de escritura majority

Tip

Para obtener más información sobre los conceptos mencionados en esta sección, consulte las siguientes entradas del manual de MongoDB Server:

Datos de muestra

Los ejemplos de esta guía utilizan la colección de los sample_restaurants.restaurants conjuntos de datos de muestra de Atlas. Para aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de muestra, consulte Tutorial paraempezar a usar PyMongo.

Métodos

Después de iniciar una sesión utilizando el método start_session(), puede administrar el estado de la sesión utilizando los siguientes métodos proporcionados por el ClientSession devuelto:

Método	Descripción
`start_transaction()`	Starts a new transaction, configured with the given options, on this session. Returns an error if there is already a transaction in progress for the session. To learn more about this method, see the startTransaction() page in the Server manual. Parameters: `read_concern`, `write_concern`, `read_preference`, `max_commit_time_ms` Return Type: `ContextManager`
`abort_transaction()`	Ends the active transaction for this session. Returns an error if there is no active transaction for the session or the transaction has been committed or ended. To learn more about this method, see the abortTransaction() page in the Server manual.
`commit_transaction()`	Commits the active transaction for this session. Returns an error if there is no active transaction for the session or if the transaction was ended. To learn more about this method, see the commitTransaction() page in the Server manual.
`with_transaction()`	Starts a transaction on this session and runs `callback` once, then commits the transaction. In the event of an exception, this method may retry the commit or the entire transaction, which may invoke the callback multiple times by a single call to `with_transaction()`. Parameters: `callback`, `read_concern`, `write_concern`, `read_preference`, `max_commit_time_ms` Return Value: The result of the `callback` function
`end_session()`	Finishes this session. If a transaction has started, this method aborts it. Returns an error if there is no active session to end.

Un ClientSession también tiene métodos para recuperar propiedades de sesión y modificar propiedades de sesión mutables. Para obtener más información sobre estos métodos, consulte la documentación de la API.

Ejemplo

El siguiente ejemplo muestra cómo puedes crear una sesión, crear una transacción y confirmar una operación de inserción de varios documentos mediante los siguientes pasos:

Cree una sesión desde el cliente utilizando el método start_session().
Utilice el método with_transaction() para iniciar una transacción.
Inserte varios documentos. El método with_transaction() ejecuta la operación de inserción y confirma la transacción. Si alguna operación produce errores, with_transaction() cancela la transacción. Este método garantiza que la sesión se cierre correctamente cuando el bloque salga.
Cierre la conexión al servidor utilizando el método client.close().

Seleccione el Synchronous o pestaña Asynchronous para ver el código correspondiente:

# Establishes a connection to the MongoDB server
client = MongoClient("<connection string>")
# Defines the database and collection
restaurants_db = client["sample_restaurants"]
restaurants_collection = restaurants_db["restaurants"]
# Function performs the transaction
def insert_documents(session):
    restaurants_collection_with_session = restaurants_collection.with_options(
        write_concern=WriteConcern("majority"),
        read_concern=ReadConcern("local")
    )
    
    # Inserts documents within the transaction
    restaurants_collection_with_session.insert_one(
        {"name": "PyMongo Pizza", "cuisine": "Pizza"}, session=session
    )
    restaurants_collection_with_session.insert_one(
        {"name": "PyMongo Burger", "cuisine": "Burger"}, session=session
    )
# Starts a client session
async with client.start_session() as session:
    try:
        # Uses the with_transaction method to start a transaction, execute the callback, and commit (or abort on error).
        session.with_transaction(insert_documents)
        print("Transaction succeeded")
    except (ConnectionFailure, OperationFailure) as e:
        print(f"Transaction failed: {e}")
# Closes the client connection
client.close()

# Establishes a connection to the MongoDB server
client = AsyncMongoClient("<connection string>")
# Defines the database and collection
restaurants_db = client["sample_restaurants"]
restaurants_collection = restaurants_db["restaurants"]
# Function performs the transaction
async def insert_documents(session):
    restaurants_collection_with_session = restaurants_collection.with_options(
        write_concern=WriteConcern("majority"),
        read_concern=ReadConcern("local")
    )
    
    # Inserts documents within the transaction
    await restaurants_collection_with_session.insert_one(
        {"name": "PyMongo Pizza", "cuisine": "Pizza"}, session=session
    )
    await restaurants_collection_with_session.insert_one(
        {"name": "PyMongo Burger", "cuisine": "Burger"}, session=session
    )
# Starts a client session
with client.start_session() as session:
    try:
        # Uses the with_transaction method to start a transaction, execute the callback, and commit (or abort on error).
        await session.with_transaction(insert_documents)
        print("Transaction succeeded")
    except (ConnectionFailure, OperationFailure) as e:
        print(f"Transaction failed: {e}")
# Closes the client connection
await client.close()

Si necesita mayor control sobre sus transacciones, puede usar el método start_transaction(). Puede usar este método junto con los métodos commit_transaction() y abort_transaction() descritos en la sección anterior para administrar manualmente el ciclo de vida de las transacciones.

Nota

Operaciones paralelas no admitidas

PyMongo no admite la ejecución de operaciones paralelas dentro de una sola transacción.

Si utiliza MongoDB Server v8.0 o posterior, puede realizar operaciones de escritura en varios espacios de nombres dentro de una misma transacción llamando al bulk_write() método en una MongoClient instancia. Para obtener más información, consulte la guía "Operaciones de escritura en masa".

Información Adicional

Para obtener más información sobre los conceptos mencionados en esta guía, consulte las siguientes páginas del manual del servidor:

Para obtener más información sobre el cumplimiento de ACID, consulte el artículo ¿Qué son las propiedades ACID en los sistemas de administración de bases de datos? en el sitio web de MongoDB.

Documentación de la API

Para aprender más sobre cualquiera de los tipos o métodos discutidos en esta guía, consulta la siguiente documentación de la API:

Volver

Operaciones de escritura masiva

Almacene archivos grandes