UpdateOne

Visão geral

Neste guia, você pode aprender como usar o Driver MongoDB .NET/C# para atualizar valores em um único documento.

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

UpdateOne(): atualiza um ou mais campos em um único documento.
UpdateOneAsync(): A versão assíncrona do UpdateOne().

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 UpdateOne() e UpdateOneAsync() aceitam os seguintes parâmetros:

Parâmetro	Descrição
`filter`	Uma `FilterDefinition` instância da classe que especifica o documento a ser atualizado. 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 um documento e Atualizar arrays em um documento. Tipo de Dados: UpdateDefinition<TDocument>
`options`	Opcional. Uma instância da classe `UpdateOptions` que especifica a configuração para a operação de atualização. 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 UpdateOne() e UpdateOneAsync() 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("name", "Downtown Deli");
var combinedUpdate = Builders<Restaurant>.Update.Combine(
    Builders<Restaurant>.Update.Set("cuisine", "French"),
    Builders<Restaurant>.Update.Unset("borough")
);
_restaurantsCollection.UpdateOne(filter, combinedUpdate);

var filter = Builders<Restaurant>.Filter
    .Eq("name", "Downtown Deli");
var combinedUpdate = Builders<Restaurant>.Update.Combine(
    Builders<Restaurant>.Update.Set("cuisine", "French"),
    Builders<Restaurant>.Update.Unset("borough")
);
await _restaurantsCollection.UpdateOneAsync(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("name", "Downtown Deli");
var updatePipeline = Builders<Restaurant>.Update.Pipeline(
    PipelineDefinition<Restaurant, Restaurant>.Create(
        new BsonDocument("$set", new BsonDocument("cuisine", "French")),
        new BsonDocument("$unset", "borough")
    )
);
_restaurantsCollection.UpdateOne(filter, updatePipeline);

var filter = Builders<Restaurant>.Filter
    .Eq("name", "Downtown Deli");
var updatePipeline = Builders<Restaurant>.Update.Pipeline(
    PipelineDefinition<Restaurant, Restaurant>.Create(
        new BsonDocument("$set", new BsonDocument("cuisine", "French")),
        new BsonDocument("$unset", "borough")
    )
);
await _restaurantsCollection.UpdateOneAsync(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 UpdateOne() e UpdateOneAsync() 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

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`	(Optional) Specifies whether to include case comparison. When this argument is `true`, the driver's behavior depends on the value of the `strength` argument: - If `strength` is `CollationStrength.Primary`, the driver compares base characters and case. - If `strength` is `CollationStrength.Secondary`, the driver compares base characters, diacritics, other secondary differences, and case. - If `strength` is any other value, this argument is ignored. When this argument is `false`, the driver doesn't include case comparison at strength level `Primary` or `Secondary`. Data Type: `boolean` Default: `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`	(Optional) Specifies whether the driver compares numeric strings as numbers. If this argument is `true`, the driver compares numeric strings as numbers. For example, when comparing the strings "10" and "2", the driver treats the values as 10 and 2, and finds 10 to be greater. If this argument is `false` or excluded, the driver compares numeric strings as strings. For example, when comparing the strings "10" and "2", the driver compares one character at a time. Because "1" is less than "2", the driver finds "10" to be less than "2". For more information, see Collation Restrictions in the MongoDB Server manual. Data Type: `boolean` Default: `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`	(Optional) Specifies whether strings containing diacritics sort from the back of the string to the front. Data Type: `boolean` Default: `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 UpdateOne() retorna um UpdateResult e o método UpdateOneAsync() 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

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

Acessar dados de um cursor

Campos