Operaciones de escritura masiva

Datos de muestra

Los ejemplos de esta guía utilizan las colecciones sample_restaurants.restaurants y sample_mflix.movies de la 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 Comenzar con PyMongo tutorial.

Operaciones de inserción

Para realizar una operación de inserción, crea una instancia de InsertOne y especifica el documento que deseas insertar. Pasa los siguientes argumentos clave al constructor InsertOne:

• namespace: El namespace en el que insertar el documento. Este argumento es opcional si realiza la operación masiva en una sola colección.

• document: El documento a insertar.

El siguiente ejemplo crea una instancia de InsertOne:

operation = InsertOne(
    namespace="sample_restaurants.restaurants",
    document={
        "name": "Mongo's Deli",
        "cuisine": "Sandwiches",
        "borough": "Manhattan",
        "restaurant_id": "1234"
    }
)

También puedes crear una instancia de InsertOne pasando una instancia de una clase personalizada al constructor. Esto proporciona mayor seguridad de tipos si usas una herramienta de verificación de tipos. La instancia que pases debe heredar de la clase TypedDict.

El siguiente ejemplo construye una instancia de InsertOne utilizando una clase personalizada para mayor seguridad de tipo:

class Restaurant (TypedDict):
    name: str
    cuisine: str
    borough: str
    restaurant_id: str
operation = pymongo.InsertOne(Restaurant(
    name="Mongo's Deli", cuisine="Sandwiches", borough="Manhattan", restaurant_id="1234"))

Para insertar varios documentos, cree una instancia de InsertOne para cada documento.

Operaciones de actualizar

Para actualizar un documento, cree una instancia de UpdateOne y pase los siguientes argumentos:

• namespace: El espacio de nombres donde se realizará la actualización. Este argumento es opcional si se realiza la operación masiva en una sola colección.

• filter: El filtro de query que especifica los criterios usados para emparejar documentos en tu colección.

• update: La actualización que desea realizar. Para obtener más información sobre las operaciones de actualización, consulte la guía Operadores de actualización de campos en el manual del MongoDB Server.

UpdateOne actualiza el primer documento que coincide con el filtro de query.

El siguiente ejemplo crea una instancia de UpdateOne:

operation = UpdateOne(
    namespace="sample_restaurants.restaurants",
    filter={ "name": "Mongo's Deli" },
    update={ "$set": { "cuisine": "Sandwiches and Salads" }}
)

Para actualizar varios documentos, crea una instancia de UpdateMany y pasa los mismos argumentos. UpdateMany actualiza todos los documentos que coincidan con su filtro de query.

El siguiente ejemplo crea una instancia de UpdateMany:

operation = UpdateMany(
    namespace="sample_restaurants.restaurants",
    filter={ "name": "Mongo's Deli" },
    update={ "$set": { "cuisine": "Sandwiches and Salads" }}
)

Reemplazar operaciones

Una operación de reemplazo remueve todos los campos y valores de un documento especificado y los reemplaza por otros nuevos. Para realizar una operación de reemplazo, crea una instancia de ReplaceOne y pasa los siguientes argumentos:

• namespace: El espacio de nombres en el que llevar a cabo la operación de reemplazo. Este argumento es opcional si realiza la operación masiva en una sola colección.

• filter: El filtro de query que especifica los criterios utilizados para emparejar el documento a reemplazar.

• replacement: El documento que incluye los nuevos campos y valores que desea almacenar en el documento coincidente.

El siguiente ejemplo crea una instancia de ReplaceOne:

operation = ReplaceOne(
    namespace="sample_restaurants.restaurants",
    filter={ "restaurant_id": "1234" },
    replacement={
        "name": "Mongo's Pizza",
        "cuisine": "Pizza",
        "borough": "Brooklyn",
        "restaurant_id": "5678"
    }
)

También puedes crear una instancia de ReplaceOne pasando una instancia de una clase personalizada al constructor. Esto proporciona mayor seguridad de tipos si usas una herramienta de verificación de tipos. La instancia que pases debe heredar de la clase TypedDict.

El siguiente ejemplo construye una instancia de ReplaceOne usando una clase personalizada para mayor seguridad de tipo:

class Restaurant (TypedDict):
    name: str
    cuisine: str
    borough: str
    restaurant_id: str
operation = pymongo.ReplaceOne(
    { "restaurant_id": "1234" },
    Restaurant(name="Mongo's Pizza", cuisine="Pizza", borough="Brooklyn", restaurant_id="5678")
)

Para reemplazar varios documentos, debe crear una instancia de ReplaceOne para cada documento.

Operaciones de borrar

Para eliminar un documento, cree una instancia de DeleteOne y pase los siguientes argumentos:

• namespace: El espacio de nombres donde se eliminará el documento. Este argumento es opcional si se realiza la operación masiva en una sola colección.

• filter: El filtro de query que especifica los criterios utilizados para hacer coincidir el documento a eliminar.

DeleteOne elimina únicamente el primer documento que coincida con tu filtro de query.

El siguiente ejemplo crea una instancia de DeleteOne:

operation = DeleteOne(
    namespace="sample_restaurants.restaurants",
    filter={ "restaurant_id": "5678" }
)

Para borrar varios documentos, crea una instancia de DeleteMany e introduce un namespace y un filtro de query que especifique el documento que deseas borrar. DeleteMany remueve todos los documentos que coinciden con tu filtro de query.

El siguiente ejemplo crea una instancia de DeleteMany:

operation = DeleteMany(
    namespace="sample_restaurants.restaurants",
    filter={ "name": "Mongo's Deli" }
)

Ejemplo De Guardar Masiva En Colección

El siguiente ejemplo realiza múltiples operaciones de escritura en la colección restaurants utilizando el método bulk_write() en una instancia de Collection. Elija el Synchronous o la pestaña Asynchronous para ver el código correspondiente:

operations = [
    InsertOne(
        document={
            "name": "Mongo's Deli",
            "cuisine": "Sandwiches",
            "borough": "Manhattan",
            "restaurant_id": "1234"
        }
    ),
    InsertOne(
        document={
            "name": "Mongo's Deli",
            "cuisine": "Sandwiches",
            "borough": "Brooklyn",
            "restaurant_id": "5678"
        }
    ),
    UpdateMany(
        filter={ "name": "Mongo's Deli" },
        update={ "$set": { "cuisine": "Sandwiches and Salads" }}
    ),
    DeleteOne(
        filter={ "restaurant_id": "1234" }
    )
]
results = restaurants.bulk_write(operations)
print(results)

BulkWriteResult({'writeErrors': [], 'writeConcernErrors': [], 'nInserted': 2,
'nUpserted': 0, 'nMatched': 2, 'nModified': 2, 'nRemoved': 1, 'upserted': []},
acknowledged=True)

operations = [
    InsertOne(
        document={
            "name": "Mongo's Deli",
            "cuisine": "Sandwiches",
            "borough": "Manhattan",
            "restaurant_id": "1234"
        }
    ),
    InsertOne(
        document={
            "name": "Mongo's Deli",
            "cuisine": "Sandwiches",
            "borough": "Brooklyn",
            "restaurant_id": "5678"
        }
    ),
    UpdateMany(
        filter={ "name": "Mongo's Deli" },
        update={ "$set": { "cuisine": "Sandwiches and Salads" }}
    ),
    DeleteOne(
        filter={ "restaurant_id": "1234" }
    )
]
results = await restaurants.bulk_write(operations)
print(results)

BulkWriteResult({'writeErrors': [], 'writeConcernErrors': [], 'nInserted': 2,
'nUpserted': 0, 'nMatched': 2, 'nModified': 2, 'nRemoved': 1, 'upserted': []},
acknowledged=True)

Ejemplo de escritura masiva del cliente

El siguiente ejemplo realiza múltiples operaciones de escritura en los espacios de nombres sample_restaurants.restaurants y sample_mflix.movies utilizando el método bulk_write() en una instancia de MongoClient. Selecciona la pestaña Synchronous o Asynchronous para ver el código correspondiente:

operations = [
    InsertOne(
        namespace="sample_mflix.movies",
        document={
            "title": "Minari",
            "runtime": 217,
            "genres": ["Drama", "Comedy"]
        }
    ),
    UpdateOne(
        namespace="sample_mflix.movies",
        filter={ "title": "Minari" },
        update={ "$set": { "runtime": 117 }}
    ),
    DeleteMany(
        namespace="sample_restaurants.restaurants",
        filter={ "cuisine": "French" }
    )
]
results = client.bulk_write(operations)
print(results)

ClientBulkWriteResult({'anySuccessful': True, 'error': None, 'writeErrors': [],
'writeConcernErrors': [], 'nInserted': 1, 'nUpserted': 0, 'nMatched': 1,
'nModified': 1, 'nDeleted': 344, 'insertResults': {}, 'updateResults': {},
'deleteResults': {}}, acknowledged=True, verbose=False)

operations = [
    InsertOne(
        namespace="sample_mflix.movies",
        document={
            "title": "Minari",
            "runtime": 217,
            "genres": ["Drama", "Comedy"]
        }
    ),
    UpdateOne(
        namespace="sample_mflix.movies",
        filter={ "title": "Minari" },
        update={ "$set": { "runtime": 117 }}
    ),
    DeleteMany(
        namespace="sample_restaurants.restaurants",
        filter={ "cuisine": "French" }
    )
]
results = await client.bulk_write(operations)
print(results)

ClientBulkWriteResult({'anySuccessful': True, 'error': None, 'writeErrors': [],
'writeConcernErrors': [], 'nInserted': 1, 'nUpserted': 0, 'nMatched': 1,
'nModified': 1, 'nDeleted': 344, 'insertResults': {}, 'updateResults': {},
'deleteResults': {}}, acknowledged=True, verbose=False)

Opciones de escritura masiva de colecciones

La siguiente tabla describe las opciones que puedes pasar al método Collection.bulk_write():

El siguiente ejemplo llama al método bulk_write() del anterior Ejemplo de guardar masivo en la colección, pero establece la opción ordered en False. Selecciona la pestaña Synchronous o Asynchronous para ver el código correspondiente:

results = restaurants.bulk_write(operations, ordered=False)

results = await restaurants.bulk_write(operations, ordered=False)

Si alguna de las operaciones de guardar en una escritura masiva no ordenada falla, PyMongo informa los errores solo después de intentar todas las operaciones.

Opciones de escritura masiva de clientes

La siguiente tabla describe las opciones que puedes pasar al método MongoClient.bulk_write():

El siguiente ejemplo llama al método bulk_write() desde el anterior Ejemplo de escritura masiva en el cliente, pero configura la opción verbose_results en True. Selecciona la pestaña Synchronous o Asynchronous para ver el código correspondiente:

results = client.bulk_write(operations, verbose_results=True)

ClientBulkWriteResult({'anySuccessful': True, 'error': None, 'writeErrors': [],
'writeConcernErrors': [], 'nInserted': 1, 'nUpserted': 0, 'nMatched': 1, 'nModified': 1,
'nDeleted': 344, 'insertResults': {0: InsertOneResult(ObjectId('...'),
acknowledged=True)}, 'updateResults': {1: UpdateResult({'ok': 1.0, 'idx': 1, 'n': 1,
'nModified': 1}, acknowledged=True)}, 'deleteResults': {2: DeleteResult({'ok': 1.0,
'idx': 2, 'n': 344}, acknowledged=True)}}, acknowledged=True, verbose=True)

results = await client.bulk_write(operations, verbose_results=True)

ClientBulkWriteResult({'anySuccessful': True, 'error': None, 'writeErrors': [],
'writeConcernErrors': [], 'nInserted': 1, 'nUpserted': 0, 'nMatched': 1, 'nModified': 1,
'nDeleted': 344, 'insertResults': {0: InsertOneResult(ObjectId('...'),
acknowledged=True)}, 'updateResults': {1: UpdateResult({'ok': 1.0, 'idx': 1, 'n': 1,
'nModified': 1}, acknowledged=True)}, 'deleteResults': {2: DeleteResult({'ok': 1.0,
'idx': 2, 'n': 344}, acknowledged=True)}}, acknowledged=True, verbose=True)

Valor de retorno de escritura masiva de colección

El método Collection.bulk_write() devuelve un objeto BulkWriteResult. El objeto BulkWriteResult contiene las siguientes propiedades:

Valor de retorno de guardar masivo del cliente

El método MongoClient.bulk_write() devuelve un objeto ClientBulkWriteResult. El objeto ClientBulkWriteResult contiene las siguientes propiedades:

Anotaciones de tipo de cliente

Si no se agrega una anotación de tipo para el objeto MongoClient, el verificador de tipos podría mostrar un error similar al siguiente:

from pymongo import MongoClient
client = MongoClient()  # error: Need type annotation for "client"

La solución es anotar el objeto MongoClient como client: MongoClient o client: MongoClient[Dict[str, Any]].

Tipo incompatible

Si especifica MongoClient como una sugerencia de tipo, pero no incluye los tipos de datos para el documento, las claves y los valores, su verificador de tipos podría mostrar un error similar al siguiente:

error: Dict entry 0 has incompatible type "str": "int";
expected "Mapping[str, Any]": "int"

La solución es agregar la siguiente sugerencia de tipo al objeto MongoClient:

client: MongoClient[Dict[str, Any]]

Documentación de la API

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

• Colección.bulk_write()

• MongoClient.bulk_write()

• InsertOne

• UpdateOne

• UpdateMany

• Reemplace uno

• DeleteOne

• Borrar muchos

• BulkWriteResult

• ClientBulkWriteResult

• Error de escritura masiva

• ClientBulkWriteException