Modificar documentos

Abrir tutorial interativo

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; }
}

Essa coleção é dos conjuntos de dados de amostra fornecidos pelo Atlas. Consulte o Quick Start para saber como criar um cluster MongoDB gratuito e carregar esses dados de amostra.

Parâmetros necessários

Cada método de atualização exige os seguintes parâmetros:

• Um documento de filtro de queries, que determina quais registros devem ser atualizados. Consulte o manual do servidor MongoDB para obter mais informações sobre filtros de queries.

• Um documento de atualização, que especifica o operador de atualização (o tipo de atualização a ser executada) e os campos e valores que devem ser alterados. Consulte a página do Manual de operadores de atualização de campos para obter uma lista completa dos operadores de atualização e seu uso.

O driver .NET/C# fornece uma classe Builders que simplifica a criação de filtros de queries e documentos de atualização. A amostra de código abaixo usa Builders para criar dois documentos para utilizar como parâmetros em uma operação de atualização:

• Um filtro de queries que pesquisa restaurantes com um valor do campo cuisine de "Pizza"

• Um documento de atualização que define o valor do campo cuisine desses restaurantes como "Massas e pães"

const string oldValue = "Pizza";
const string newValue = "Pasta and breadsticks";
// Creates a filter for all documents with a "cuisine" value of "Pizza"
var filter = Builders<Restaurant>.Filter
     .Eq(restaurant => restaurant.Cuisine, oldValue);
// Creates instructions to update the "cuisine" field of documents that
// match the filter
var update = Builders<Restaurant>.Update
    .Set(restaurant => restaurant.Cuisine, newValue);
// Updates all documents that have a "cuisine" value of "Pizza"
return _restaurantsCollection.UpdateMany(filter, update);

Atualizar um documento

O código abaixo mostra como usar o método UpdateOneAsync() assíncrono ou o método UpdateOne() síncrono para atualizar um documento.

var result = await _restaurantsCollection.UpdateOneAsync(filter, update);

var result = _restaurantsCollection.UpdateOne(filter, update);

Atualizar muitos documentos

O código abaixo mostra como usar o método UpdateManyAsync() assíncrono ou o método UpdateMany() síncrono para atualizar todos os documentos correspondentes.

var result = await _restaurantsCollection.UpdateManyAsync(filter, update);

var result = _restaurantsCollection.UpdateMany(filter, update);

Personalizar a operação de atualização

Ambos os métodos opcionalmente aceitam um objeto UpdateOptions como um parâmetro adicional, que representa as opções que você pode usar para configurar a operação de atualização. Se você não especificar quaisquer propriedades do UpdateOptions, o driver não personalizará a operação de atualização.

O tipo UpdateOptions permite a você configurar opções com as seguintes propriedades:

Valor de retorno

Os métodos UpdateOne() e UpdateMany() retornam um objeto UpdateResult. O tipo UpdateResult contém as seguintes propriedades:

Exemplo

O código abaixo usa o método UpdateMany() para encontrar todos os documentos onde o campo borough tem o valor "Manhattan" e, em seguida, atualiza o valor borough nesses documentos para "Manhattan (norte)". Como a opção IsUpsert está definida como true, o driver insere um novo documento se o filtro de queries não corresponder a nenhum documento existente.

  var filter = Builders<Restaurant>.Filter
      .Eq(restaurant => restaurant.Borough, "Manhattan");
  var update = Builders<Restaurant>.Update
      .Set(restaurant => restaurant.Borough, "Manhattan (north)");
  UpdateOptions opts = new UpdateOptions()
  {
      Comment = new BsonString("Borough updated for C# Driver Fundamentals"),
      IsUpsert = true
  };
  Console.WriteLine("Updating documents...");
  var result = _restaurantsCollection.UpdateMany(filter, update, opts);
  Console.WriteLine($"Updated documents: {result.ModifiedCount}");
  Console.WriteLine($"Result acknowledged? {result.IsAcknowledged}");

Updating documents...
Updated documents: 10259
Result acknowledged? True

Parâmetros necessários

O método ReplaceOne() exige os seguintes parâmetros:

• Um documento de filtro de queries, que determina qual registro substituir.

• Um documento de substituição, que especifica os campos e valores a serem inseridos no novo documento. Se os documentos em sua coleção forem mapeados para uma classe C#, o documento de substituição poderá ser uma instância dessa classe.

Como em uma operação de atualização, você pode utilizar a classe Builders no Driver .NET/C# para criar um filtro de queries. A seguinte amostra de código utiliza Builders para criar um filtro de queries que pesquisa restaurantes com um valor de campo name de "Pizza Town". O código também cria um novo objeto Restaurant que substituirá o primeiro documento correspondente.

// Creates a filter for all restaurant documents that have a "cuisine" value of "Pizza"
var filter = Builders<Restaurant>.Filter
    .Eq(r => r.Cuisine, "Pizza");
// Finds the ID of the first restaurant document that matches the filter
var oldPizzaRestaurant = _restaurantsCollection.Find(filter).First();
var oldId = oldPizzaRestaurant.Id;
// Generates a new restaurant document
Restaurant newPizzaRestaurant = new()
{
    Id = oldId,
    Name = "Mongo's Pizza",
    Cuisine = "Pizza",
    Address = new()
    {
        Street = "Pizza St",
        ZipCode = "10003"
    },
    Borough = "Manhattan",
};
// Replaces the existing restaurant document with the new document
return _restaurantsCollection.ReplaceOne(filter, newPizzaRestaurant);

O código abaixo mostra como usar o método ReplaceOneAsync() assíncrono ou o método ReplaceOne() síncrono para substituir um documento.

var result = await _restaurantsCollection.ReplaceOneAsync(filter, newRestaurant);

var result = _restaurantsCollection.ReplaceOne(filter, newRestaurant);

Personalizar a operação de substituição

O método ReplaceOne() aceita opcionalmente um objeto ReplaceOptions como parâmetro adicional, que representa as opções que você pode usar para configurar a operação de substituição. Se você não especificar quaisquer propriedades do ReplaceOptions, o driver não personalizará a operação de substituição.

O tipo ReplaceOptions permite a você configurar opções com as seguintes propriedades:

Valor de retorno

O método ReplaceOne() retorna um objeto ReplaceOneResult. O tipo ReplaceOneResult contém as seguintes propriedades:

Exemplo

O código abaixo usa o método ReplaceOne() para localizar o primeiro documento onde o campo name tem o valor "Pizza Town" e, em seguida, substitui este documento por um novo documento Restaurant chamado "Food World". Como a opção IsUpsert está definida como true, o driver insere um novo documento se o filtro de queries não corresponder a nenhum documento existente.

var filter = Builders<Restaurant>.Filter.Eq(restaurant => restaurant.Name, "Pizza Town");
Restaurant newRestaurant = new()
{
    Name = "Food World",
    Cuisine = "American",
    Address = new BsonDocument
    {
        {"street", "Food St"},
        {"zipcode", "10003"},
    },
    Borough = "Manhattan",
};
ReplaceOptions opts = new ReplaceOptions()
{
    Comment = new BsonString("Restaurant replaced for .NET/C# Driver Fundamentals"),
    IsUpsert = true
};
Console.WriteLine("Replacing document...");
var result = _restaurantsCollection.ReplaceOne(filter, newRestaurant, opts);
Console.WriteLine($"Replaced documents: {result.ModifiedCount}");
Console.WriteLine($"Result acknowledged? {result.IsAcknowledged}");

Replacing document...
Replaced documents: 1
Result acknowledged? True

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:

• UpdateOne()

• UpdateOneAsync()

• UpdateMany()

• UpdateManyAsync()

• UpdateOptions

• UpdateResult

• ReplaceOne()

• ReplaceOneAsync()

• ReplaceOptions

• ReplaceOneResult