Operações de gravação em massa

Dados de amostra

Os exemplos neste guia usam as collections sample_restaurants.restaurants e sample_mflix.movies dos conjuntos de dados de amostra do Atlas. Para saber como criar um cluster gratuito do MongoDB Atlas e carregar os conjuntos de dados de amostra, consulte o tutorial Introdução ao PyMongo.

Inserir operações

Para executar uma operação de inserção, crie uma instância de InsertOne e especifique o documento que você deseja inserir. Passe os seguintes argumentos de palavra-chave para o construtor InsertOne:

• namespace: O namespace no qual inserir o documento. Este argumento é opcional se você executar a operação em massa em uma única coleção.

• document: O documento a inserir.

O exemplo a seguir cria uma instância de InsertOne:

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

Você também pode criar uma instância de InsertOne passando uma instância de uma classe personalizada para o construtor. Isso oferece segurança adicional de tipo se você estiver usando uma ferramenta de verificação de tipo. A instância pela qual você passa deve herdar da classe TypedDict.

O exemplo a seguir constrói uma instância InsertOne usando uma classe personalizada para maior segurança 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 inserir vários documentos, crie uma instância de InsertOne para cada documento.

Atualizar operações

Para atualizar um documento, crie uma instância de UpdateOne e passe os seguintes argumentos:

• namespace: o namespace no qual executar a atualização. Este argumento é opcional se você executar a operação em massa em uma única coleção.

• filter: o filtro de query que especifica os critérios utilizados para corresponder a documentos em sua coleção.

• update: A atualização que você deseja executar. Para obter mais informações sobre operações de atualização, consulte o guia Operadores de atualização de campo no manual do MongoDB Server.

UpdateOne atualiza o primeiro documento que corresponde ao seu filtro de query.

O exemplo a seguir cria uma instância de UpdateOne:

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

Para atualizar vários documentos, crie uma instância de UpdateMany e passe os mesmos argumentos. UpdateMany atualiza todos os documentos que correspondem ao seu filtro de query.

O exemplo a seguir cria uma instância de UpdateMany:

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

Operações de substituição

Uma operação de substituição remove todos os campos e valores de um documento especificado e os substitui por novos. Para executar uma operação de substituição, crie uma instância de ReplaceOne e passe os seguintes argumentos:

• namespace: o namespace no qual executar a operação de substituição. Este argumento é opcional se você executar a operação em massa em uma única coleção.

• filter: o filtro de query que especifica os critérios usados para corresponder ao documento a ser substituído.

• replacement: o documento que inclui os novos campos e valores que você deseja armazenar no documento correspondente.

O exemplo a seguir cria uma instância de ReplaceOne:

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

Você também pode criar uma instância de ReplaceOne passando uma instância de uma classe personalizada para o construtor. Isso oferece segurança adicional de tipo se você estiver usando uma ferramenta de verificação de tipo. A instância pela qual você passa deve herdar da classe TypedDict.

O exemplo a seguir constrói uma instância ReplaceOne usando uma classe personalizada para maior segurança 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 substituir vários documentos, você deve criar uma instância de ReplaceOne para cada documento.

Excluir operações

Para excluir um documento, crie uma instância de DeleteOne e passe os seguintes argumentos:

• namespace: O namespace no qual excluir o documento. Este argumento é opcional se você executar a operação em massa em uma única coleção.

• filter: o filtro de query que especifica os critérios usados para corresponder ao documento a ser excluído.

DeleteOne remove apenas o primeiro documento que corresponde ao seu filtro de query.

O exemplo a seguir cria uma instância de DeleteOne:

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

Para excluir vários documentos, crie uma instância do DeleteMany e passe um namespace e um filtro de query especificando o documento que você deseja excluir. DeleteMany remove todos os documentos que correspondem ao seu filtro de query.

O exemplo a seguir cria uma instância de DeleteMany:

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

Exemplo de gravação em massa da collection

O exemplo seguinte executa múltiplas operações de gravação na coleção restaurants utilizando o método bulk_write() em uma instância do Collection:

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)

Exemplo de gravação em massa do cliente

O seguinte exemplo executa múltiplas operações de gravação nos namespaces sample_restaurants.restaurants e sample_mflix.movies utilizando o método bulk_write() em uma instância do MongoClient:

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)

Opções de gravação em massa da collection

A tabela a seguir descreve as opções que você pode passar para o método Collection.bulk_write() :

O exemplo a seguir chama o método bulk_write() do Exemplo de gravação em massa da coleção anterior, mas define a opção ordered como False:

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

Se qualquer uma das operações de gravação em uma gravação em massa não ordenada falhar, o PyMongo relatará os erros somente depois de tentar todas as operações.

Opções de gravação em massa do cliente

A tabela a seguir descreve as opções que você pode passar para o método MongoClient.bulk_write() :

O exemplo a seguir chama o método bulk_write() do Exemplo de gravação em massa do cliente anterior, mas define a opção verbose_results como True:

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)

Valor de retorno de gravação em massa da coleção

O método Collection.bulk_write() retorna um objeto BulkWriteResult . O objeto BulkWriteResult contém as seguintes propriedades:

Valor de retorno de gravação em massa do cliente

O método MongoClient.bulk_write() retorna um objeto ClientBulkWriteResult . O objeto ClientBulkWriteResult contém as seguintes propriedades:

Anotações do tipo de cliente

Se você não adicionar uma anotação de tipo para seu objeto MongoClient, seu verificador de tipo poderá mostrar um erro semelhante ao seguinte:

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

A solução é anotar o objeto MongoClient como client: MongoClient ou client: MongoClient[Dict[str, Any]].

Tipo incompatível

Se você especificar MongoClient como uma dica de tipo, mas não incluir tipos de dados para o documento, as chaves e os valores, seu verificador de tipo poderá mostrar um erro semelhante ao seguinte:

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

A solução é adicionar a seguinte dica de tipo ao seu objeto MongoClient :

``client: MongoClient[Dict[str, Any]]``

Documentação da API

Para saber mais sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API:

• Collection.bulk_write()

• MongoClient.bulk_write()

• InsertOne

• UpdateOne

• UpdateMany

• replaceOne

• DeleteOne

• deleteMany

• BulkWriteResult

• ClientBulkWriteResult

• BulkWriteError

• ClientBulkWriteException