/ /

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.

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`	opcional. Uma instância da classe `UpdateOptions` que especifica a configuração para a operação de atualizar. O valor padrão é `null`. Para obter uma lista das opções disponíveis, consulte Opções de configuração. 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`	Especifica o locale dos Componentes Internacionais para Unicode (ICU). Para obter uma lista de locale compatíveis, consulte agrupamentos locale e parâmetros padrão no MongoDB Server Manual. Se você quiser usar uma comparação binária simples, use a propriedade estática `Collation.Simple` para retornar um objeto `Collation` com o `locale` definido como `"simple"`. Tipo de dados: `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`	(Opcional) Especifica a ordem de classificação das diferenças de caso durante comparações de nível terciário. Tipo de dados: CollationCaseFirst Padrão: `CollationCaseFirst.Off`	`CaseFirst`
`strength`	(Opcional) Especifica o nível de comparação a ser executado, conforme definido na documentação da ICU. Tipo de dados: CollationStrength Padrão: `CollationStrength.Tertiary`	`Strength`
`numericOrdering`	(Opcional) Especifica se o driver compara strings numéricas como números. Se esse argumento for `true`, 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 e 2 e considera 10 maior. Se este argumento for `false` ou excluído, o driver compara strings numéricas como strings. Por exemplo, ao comparar as strings "10" e "2", o driver compara um caractere por vez. Como "1" é menor que "2", o driver considera "10" 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`	(Opcional) Especifica se o driver considera espaços em branco e pontuação como caracteres básicos para fins de comparação. Tipo de dados: CollationAlternate Padrão: `CollationAlternate.NonIgnorable` (espaços e pontuação são considerados caracteres básicos)	`Alternate`
`maxVariable`	(Opcional) Especifica quais caracteres o driver considera ignoráveis quando o `alternate` argumento `CollationAlternate.Shifted` é. Tipo de Dados: CollationMaxVariable Padrão: `CollationMaxVariable.Punctuation` (o driver ignora pontuação e espaços)	`MaxVariable`
`normalization`	(Opcional) Especifica se o driver normaliza o texto conforme necessário. A maioria dos textos não exige normalização. Para obter mais informações sobre normalização, consulte a documentação da ICU. Tipo de dados: `boolean` Padrão: `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:

UpdateOne()

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