/ /

UpdateMany

Visão geral

Neste guia, você pode aprender como usar o Driver MongoDB .NET/C# para atualizar valores em vários documentos.

O driver .NET/C# fornece os seguintes métodos para atualizar valores:

UpdateMany(): atualiza um ou mais campos em vários documentos.
UpdateManyAsync(): A versão assíncrona do UpdateMany().

As seções a seguir descrevem esses métodos em mais detalhes.

Observação

Sobrecargas de método

Muitos dos métodos nesta página têm múltiplas sobrecargas. Os exemplos deste guia mostram apenas uma definição de cada método. Para obter mais informações sobre as sobrecargas disponíveis, consulte a documentação da API.

Importante

Validação de entrada

As classes de construtor e queries LINQ passam valores para a operação MongoDB subjacente. Por padrão, essas APIs não são uma camada de limpeza de segurança. Valide e higienize a entrada não confiável em seu aplicação antes de passá-la para um construtor ou uma query LINQ.

Dados de amostra

Os exemplos neste guia utilizam a coleção do restaurants a partir do banco de dados do sample_restaurants. Os documentos nesta coleção usam as seguintes classes Restaurant, Address e GradeEntry como modelos:

public class Restaurant
{
    public ObjectId Id { get; set; }
    public string Name { get; set; }
    [BsonElement("restaurant_id")]
    public string RestaurantId { get; set; }
    public string Cuisine { get; set; }
    public Address Address { get; set; }
    public string Borough { get; set; }
    public List<GradeEntry> Grades { get; set; }
}

public class Address
{
    public string Building { get; set; }
    [BsonElement("coord")]
    public double[] Coordinates { get; set; }
    public string Street { get; set; }
    [BsonElement("zipcode")]
    public string ZipCode { get; set; }
}

public class GradeEntry
{
    public DateTime Date { get; set; }
    public string Grade { get; set; }
    public float? Score { get; set; }
}

Observação

Os documentos na collection restaurants usam a convenção de nomenclatura snake-case. Os exemplos neste guia usam um ConventionPack para desserializar os campos na coleção em maiúsculas e minúsculas Pascal e mapeá-los para as propriedades na classe Restaurant .

Para saber mais sobre serialização personalizada, consulte Serialização personalizada.

Essa collection é dos conjuntos de dados de amostra fornecidos pelo Atlas. Consulte a Introdução ao driver .NET/C# para saber como criar um cluster MongoDB gratuito e carregar esses dados de exemplo.

Métodos e parâmetros

Os métodos UpdateMany() e UpdateManyAsync() aceitam os seguintes parâmetros:

Parâmetro	Descrição
`filter`	Uma instância da classe `FilterDefinition` que especifica os documentos para atualizar. Para saber como criar um filtro de query, consulte Criar um filtro de query. Tipo de Dados: FilterDefinition
`update`	Uma instância da classe `UpdateDefinition`. Este objeto especifica o tipo de operação de atualização, os campos a serem atualizados e o novo valor para cada campo. Para saber como criar um objeto `UpdateDefinition`, consulte Atualizar campos em muitos documentos e Atualizar arrays em muitos documentos. Tipo de Dados: UpdateDefinition<TDocument>
`options`	Optional. An instance of the `UpdateOptions` class that specifies the configuration for the update operation. The default value is `null`. For a list of available options, see Configuration Options. Tipo de Dados: UpdateOptions
`cancellationToken`	Opcional. Um token que você pode usar para cancelar a operação. Tipo de dados: `CancellationToken`

Atualizar vários valores

Os métodos UpdateMany() e UpdateManyAsync() aceitam somente um objeto UpdateDefinition. As seções a seguir descrevem como atualizar vários valores em uma única chamada de método.

Definições de atualização combinadas

O método Builders.Update.Combine() permite combinar vários objetos UpdateDefinition. Este método aceita o seguinte parâmetro:

Parâmetro	Descrição
`updates`	Uma array de definições de atualizações para combinar. Tipo de Dados: `UpdateDefinition<TDocument>[]`

O método Combine() retorna um único objeto UpdateDefinition que define múltiplas operações de atualização.

O seguinte exemplo de código utiliza o Combine() método para combinar uma operação $set e uma operação $unset:

var filter = Builders<Restaurant>.Filter
    .Eq("cuisine", "Pizza");
var combinedUpdate = Builders<Restaurant>.Update.Combine(
    Builders<Restaurant>.Update.Set("cuisine", "French"),
    Builders<Restaurant>.Update.Unset("borough")
);
_restaurantsCollection.UpdateMany(filter, combinedUpdate);

var filter = Builders<Restaurant>.Filter
    .Eq("cuisine", "Pizza");
var combinedUpdate = Builders<Restaurant>.Update.Combine(
    Builders<Restaurant>.Update.Set("cuisine", "French"),
    Builders<Restaurant>.Update.Unset("borough")
);
await _restaurantsCollection.UpdateManyAsync(filter, combinedUpdate);

Atualizar pipelines

Você pode unir uma sequência de operações de atualização em um único pipeline de agregação.

Para criar um pipeline de atualização, chame o método Builders.Update.Pipeline(). Este método aceita o seguinte parâmetro:

Parâmetro	Descrição
`pipeline`	Uma instância `PipelineDefinition` que representa o pipeline de atualização. Para criar um objeto `PipelineDefinition`, crie um documento BSON para cada operação de atualização que você deseja executar e, em seguida, passe esses documentos para o método `PipelineDefinition.Create()`. Tipo de Dados: `PipelineDefinition<TDocument, TDocument>`

O método Pipeline() retorna um único objeto UpdateDefinition que define vários estágios de agregação .

O seguinte exemplo de código utiliza o Pipeline() método para combinar uma operação $set e uma operação $unset:

var filter = Builders<Restaurant>.Filter
    .Eq("cuisine", "Pizza");
var updatePipeline = Builders<Restaurant>.Update.Pipeline(
    PipelineDefinition<Restaurant, Restaurant>.Create(
        new BsonDocument("$set", new BsonDocument("cuisine", "French")),
        new BsonDocument("$unset", "borough")
    )
);
_restaurantsCollection.UpdateMany(filter, updatePipeline);

var filter = Builders<Restaurant>.Filter
    .Eq("cuisine", "Pizza");
var updatePipeline = Builders<Restaurant>.Update.Pipeline(
    PipelineDefinition<Restaurant, Restaurant>.Create(
        new BsonDocument("$set", new BsonDocument("cuisine", "French")),
        new BsonDocument("$unset", "borough")
    )
);
await _restaurantsCollection.UpdateManyAsync(filter, updatePipeline);

Observação

Operações não suportadas

Os pipelines de atualização não suportam todas as operações de atualização, mas suportam determinados estágios de agregação não encontrados em outras definições de atualização. Para obter uma lista de operações de atualização suportadas por pipelines,consulte Atualizações com aggregation pipeline no manual do MongoDB Server .

Opções de configuração

Os métodos UpdateMany() e UpdateManyAsync() aceitam opcionalmente um objeto UpdateOptions como parâmetro. Você pode utilizar este argumento para configurar a operação de atualização.

A classe UpdateOptions contém as seguintes propriedades:

Propriedade

Descrição

ArrayFilters

Especifica quais elementos de array modificar para uma operação de atualização em um campo de array. Consulte o manual do servidor do MongoDB para obter mais informações.

Tipo de dados: IEnumerable<ArrayFilterDefinition>

BypassDocumentValidation

Especifica se a operação de atualização ignora a validação do documento. Isso permite atualizar documentos que não atendam aos requisitos de validação do esquema, se houver algum. Consulte o manual do servidor do MongoDB para obter mais informações sobre validação de esquema.

Tipo de Dados: bool?

Collation

Especifica o tipo de agrupamento de idiomas a ser usado ao classificar os resultados. Consulte a seção Agrupamento desta página para obter mais informações.

Tipo de Dados: Agrupamentos

Comment

Obtém ou define o comentário fornecido pelo usuário para a operação. Consulte o manual do servidor do MongoDB para obter mais informações.

Tipo de Dados: BsonValor

Hint

Obtém ou define o índice a ser usado para procurar documentos. Consulte o manual do servidor do MongoDB para obter mais informações.

Tipo de Dados: BsonValor

IsUpsert

Especifica se a operação de atualização executa uma operação upsert se nenhum documento corresponder ao filtro de queries. Consulte o manual do servidor do MongoDB para obter mais informações.

Tipo de Dados: bool

Sort

Determina qual documento a operação atualiza se a query selecionar vários documentos, porque a operação de atualização atualiza o primeiro documento na ordem de classificação especificada. Para definir essa opção, você deve instanciar uma instância UpdateOptions<T> que usa um tipo genérico que modela seus dados, conforme mostrado no código a seguir:

var options = new UpdateOptions<Restaurant>
{
  Sort = Builders<Restaurant>.Sort.Ascending(r => r.Name)
};

Tipo de Dados: SortDefinition<T>

Let

Obtém ou define o documento de permissão. Consulte o manual do servidor do MongoDB para obter mais informações.

Tipo de Dados: Documento BSON

Agrupamentos

Para configurar o agrupamento para sua operação, crie uma instância da classe Agrupamento.

A tabela seguinte descreve os parâmetros que o construtor do Collation aceita. Ela também lista a propriedade de classe correspondente que você pode usar para ler o valor de cada configuração.

Parâmetro	Descrição	Propriedade de classe
`locale`	Specifies the International Components for Unicode (ICU) locale. For a list of supported locales, see Collation Locales and Default Parameters in the MongoDB Server Manual. If you want to use simple binary comparison, use the `Collation.Simple` static property to return a `Collation` object with the `locale` set to `"simple"`. Data Type: `string`	`Locale`
`caseLevel`	(Opcional) Especifica se a comparação de caso deve ser incluída. Quando este argumento é `true`, o comportamento do driver depende do valor do argumento `strength`: - Se `strength` for `CollationStrength.Primary`, o driver compara caracteres básicos e maiúsculas e minúsculas. - Se `strength` for `CollationStrength.Secondary`, o driver compara caracteres básicos, diacríticos, outras diferenças secundárias e maiúsculas e minúsculas. - Se `strength` for qualquer outro valor, este argumento será ignorado. Quando este argumento é `false`, o driver não inclui comparação de maiúsculas e minúsculas no nível de força `Primary` ou `Secondary`. Tipo de dados: `boolean` Padrão: `false`	`CaseLevel`
`caseFirst`	(Optional) Specifies the sort order of case differences during tertiary level comparisons. Data Type: CollationCaseFirst Default: `CollationCaseFirst.Off`	`CaseFirst`
`strength`	(Optional) Specifies the level of comparison to perform, as defined in the ICU documentation. Data Type: CollationStrength Default: `CollationStrength.Tertiary`	`Strength`
`numericOrdering`	(Opcional) Especifica se o driver compara strings numéricas como números. Se esse argumento `true` for, o driver compara strings numéricas como números. Por exemplo, ao comparar as strings "10" e "2", o driver trata os valores como 10 2e, e considera 10 maior. Se esse argumento for `false` ou excluído, o driver compara cadeias de caracteres numéricas como cadeias de caracteres. Por exemplo, ao comparar as strings "10" e "2", o driver compara um caractere de cada vez. Porque "1" é inferior a "2", o condutor encontra "10" para ser menor que "2". Para obter mais informações, consulte Restrições de agrupamento no manual do MongoDB Server . Tipo de Dados: `boolean` Padrão: `false`	`NumericOrdering`
`alternate`	(Optional) Specifies whether the driver considers whitespace and punctuation as base characters for purposes of comparison. Data Type: CollationAlternate Default: `CollationAlternate.NonIgnorable` (spaces and punctuation are considered base characters)	`Alternate`
`maxVariable`	(Optional) Specifies which characters the driver considers ignorable when the `alternate` argument is `CollationAlternate.Shifted`. Data Type: CollationMaxVariable Default: `CollationMaxVariable.Punctuation` (the driver ignores punctuation and spaces)	`MaxVariable`
`normalization`	(Optional) Specifies whether the driver normalizes text as needed. Most text doesn't require normalization. For more information about normalization, see the ICU documentation. Data Type: `boolean` Default: `false`	`Normalization`
`backwards`	(Opcional) Especifica se as strings que contêm diacríticos são ordenadas da parte de trás da string para a frente. Tipo de dados: `boolean` Padrão: `false`	`Backwards`

Para obter mais informações sobre agrupamento, consulte a página Agrupamento no manual do MongoDB Server.

Valor de retorno

O método UpdateMany() retorna um UpdateResult e o método UpdateManyAsync() retorna um objeto Task<UpdateResult>. A classe UpdateResult contém as seguintes propriedades:

Propriedade	Descrição
`IsAcknowledged`	Indica se a operação de atualização foi reconhecida pelo MongoDB. Tipo de Dados: `bool`
`IsModifiedCountAvailable`	Indica se você pode ler a contagem de registros de atualização no `UpdateResult`. Tipo de Dados: `bool`
`MatchedCount`	O número de documentos que corresponderam ao filtro de query, independentemente de um ter sido atualizado. Tipo de Dados: `long`
`ModifiedCount`	O número de documentos atualizados pela operação de atualização. Tipo de Dados: `long`
`UpsertedId`	O ID do documento que foi atualizado no banco de dados, se o driver executou um upsert. Tipo de Dados: BsonValor

Informações adicionais

Esta página inclui um breve laboratório interativo que demonstra como modificar dados usando o método UpdateManyAsync(). É possível concluir este laboratório diretamente na janela do seu navegador sem instalar o MongoDB ou um editor de código.

Para iniciar o laboratório, clique no botão Open Interactive Tutorial na parte superior da página. Para expandir o laboratório para um formato de tela inteira, clique no botão de tela inteira (⛶) no canto superior direito do painel do laboratório.

Para obter exemplos executáveis das operações de atualização, consulte os seguintes exemplos de uso:

Para saber mais sobre como criar filtros de query, consulte o guia Criar um filtro de query.

Documentação da API

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

Voltar

arrays

Campos