/ /

Actualiza uno

Overview

En esta guía, puedes aprender cómo usar el controlador MongoDB .NET/C# para actualizar valores en un único documento.

El controlador .NET/C# proporciona los siguientes métodos para actualizar valores:

UpdateOne(): Actualiza uno o más campos en un único documento.
UpdateOneAsync(): la versión asíncrona de UpdateOne().

Las siguientes secciones describen estos métodos con más detalle.

Nota

Sobrecargas de métodos

Muchos de los métodos en esta página tienen varias sobrecargas. Los ejemplos de esta guía muestran solo una definición de cada método. Para obtener más información sobre las sobrecargas disponibles, se puede consultar la documentación de la API.

Datos de muestra

Los ejemplos de esta guía utilizan la colección restaurants de la base de datos sample_restaurants. Los documentos de esta colección utilizan las siguientes clases Restaurant, Address y 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; }
}

Nota

Los documentos de la colección restaurants utilizan la convención de nomenclatura snake-case. Los ejemplos de esta guía utilizan un ConventionPack para deserializar los campos de la colección en notación Pascal y asignarlos a las propiedades de la clase Restaurant.

Para aprender más sobre la serialización personalizada, consultar Serialización personalizada.

Esta colección es de los conjuntos de datos de muestra proporcionados por Atlas. Consulte Primeros pasos con el controlador .NET/C# para aprender a crear un clúster gratuito de MongoDB y cargar estos datos de muestra.

Métodos y parámetros

Los métodos UpdateOne() y UpdateOneAsync() aceptan los siguientes parámetros:

Parameter	Descripción
`filter`	Una instancia de la clase `FilterDefinition` que especifica el documento a actualizar. Para aprender a crear un filtro de query, consulta Crear un filtro de query. Tipo de dato: FilterDefinition
`update`	Una instancia de la clase `UpdateDefinition`. Este objeto especifica el tipo de operación de actualización, los campos a actualizar y el nuevo valor para cada campo. Para aprender a crear un `UpdateDefinition` objeto, consulta Actualizar campos en un documento y Actualizar arreglos en un documento. Tipo de dato: UpdateDefinition<TDocument>
`options`	opcional. Una instancia de la clase `UpdateOptions` que especifica la configuración para la operación de actualizar. El valor por defecto es `null`. Para obtener una lista de las opciones disponibles, consulta Opciones de configuración. Tipo de dato: UpdateOptions
`cancellationToken`	opcional. Un token que puedes usar para cancelar la operación. Tipo de datos: `CancellationToken`

Actualice varios valores

Los métodos UpdateOne() y UpdateOneAsync() solo aceptan un objeto UpdateDefinition cada uno. Las siguientes secciones describen cómo actualizar varios valores en una única llamada de método.

Definiciones de actualización combinada

El método Builders.Update.Combine() te permite combinar múltiples objetos UpdateDefinition. Este método acepta el siguiente parámetro:

Parameter	Descripción
`updates`	Un arreglo de definiciones de actualización para combinar. Tipo de dato: `UpdateDefinition<TDocument>[]`

El método Combine() devuelve un único objeto UpdateDefinition que define múltiples operaciones de actualización.

El siguiente ejemplo de código utiliza el método Combine() para combinar una operación $set y una operación $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);

Actualizar pipeline

Puedes unir una secuencia de operaciones de actualización en una sola pipeline de agregación.

Para crear un pipeline de actualización, llama al método Builders.Update.Pipeline(). Este método acepta el siguiente parámetro:

Parameter	Descripción
`pipeline`	Una instancia de `PipelineDefinition` que representa la pipeline de actualización. Para crear un objeto `PipelineDefinition`, crea un documento BSON para cada operación de actualización que quieras realizar y luego pásalos al método `PipelineDefinition.Create()`. Tipo de dato: `PipelineDefinition<TDocument, TDocument>`

El método Pipeline() devuelve un solo objeto UpdateDefinition que define múltiples etapas de agregación.

El siguiente ejemplo de código utiliza el método Pipeline() para combinar una operación $set y una operación $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);

Nota

Operaciones no admitidas

Las pipelines de actualización no admiten todas las operaciones de actualización, pero sí admiten ciertas etapas de agregación que no se encuentran en otras definiciones de actualización. Para obtener una lista de las operaciones de actualización admitidas por las pipelines, consulta Actualizaciones con pipeline de agregación en el manual de MongoDB Server.

Opciones de configuración

Los métodos UpdateOne() y UpdateOneAsync() aceptan opcionalmente un objeto UpdateOptions como parámetro. Puede utilizar este argumento para configurar la operación de actualizar.

La clase UpdateOptions contiene las siguientes propiedades:

Propiedad

Descripción

ArrayFilters

Especifica qué elementos del arreglo se deben modificar para una operación de actualización en un campo de arreglo. Para obtener más información, consulta el manual de MongoDB Server.

Tipo de dato: IEnumerable<ArrayFilterDefinition>

BypassDocumentValidation

Especifica si la operación de actualización omite la validación de documentos. Esto te permite actualizar documentos que no cumplen los requisitos de validación del esquema, si existieran. Consulta el manual de MongoDB Server para obtener más información sobre la validación de esquemas.

Tipo de dato: bool?

Collation

Especifica el tipo de intercalación lingüística a utilizar al ordenar los resultados. Consulta la sección intercalación en esta página para obtener más información.

Tipo de dato: Intercalación

Comment

Obtiene o establece el comentario proporcionado por el usuario para la operación. Para obtener más información, consulta el manual de MongoDB Server.

Tipo de dato: BsonValue

Hint

Obtiene o establece el índice que se utilizará para buscar documentos. Para obtener más información, consulta el manual de MongoDB Server.

Tipo de dato: BsonValue

IsUpsert

Especifica si la operación de actualizar realiza una operación de inserción si ningún documento coincide con el filtro de query. Para obtener más información, consulta el manual de MongoDB Server.

Tipo de dato: bool

Sort

Determina qué documento actualizará la operación si la query selecciona varios documentos, ya que la operación de actualización actualiza el primer documento en el orden de clasificación especificado. Para configurar esta opción, debes instanciar una instancia de UpdateOptions<T> que use un tipo genérico que modele tus datos, como se muestra en el siguiente código:

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

Tipo de dato: SortDefinition<T>

Let

Obtiene o establece el documento let. Para obtener más información, consulta el manual de MongoDB Server.

Tipo de dato: BsonDocument

Intercalación

Para configurar la intercalación para tu operación, crea una instancia de la clase intercalación.

La siguiente tabla describe los parámetros que acepta el constructor Collation. También enumera la propiedad de clase correspondiente que se puede usar para leer el valor de cada configuración.

Parameter	Descripción	Propiedad de clase
`locale`	Especifica la configuración regional de Componentes Internacionales para Unicode (ICU). Para obtener una lista de las configuraciones regionales compatibles, consulte Configuraciones regionales de intercalación y parámetros predeterminados en el Manual del servidor MongoDB. Si desea utilizar una comparación binaria simple, utilice la `Collation.Simple` propiedad estática para devolver un `Collation` objeto con establecido `locale` `"simple"`en. Tipo de datos: `string`	`Locale`
`caseLevel`	(Opcional) Especifica si se debe incluir la comparación de mayúsculas y minúsculas. Cuando este argumento `true` es, el comportamiento del controlador depende del valor del `strength` argumento: - Si `strength` `CollationStrength.Primary`es, el controlador compara caracteres base y mayúsculas y minúsculas. - Si `strength` `CollationStrength.Secondary`es, el controlador compara caracteres base, diacríticos, otras diferencias secundarias y mayúsculas y minúsculas. - Si `strength` es cualquier otro valor, este argumento se ignora. Cuando este argumento `false` es, el controlador no incluye la comparación de mayúsculas y minúsculas en el nivel `Primary` de fuerza `Secondary` o. Tipo `boolean` de datos: Predeterminado: `false`	`CaseLevel`
`caseFirst`	(Opcional) Especifica el orden de clasificación de las diferencias de mayúsculas y minúsculas durante las comparaciones de nivel terciario. Tipo de datos: CollationCaseFirst Valor predeterminado: `CollationCaseFirst.Off`	`CaseFirst`
`strength`	(Opcional) Especifica el nivel de comparación a realizar, tal como se define en la documentación de la UCI. Tipo de datos: CollationStrength Valor predeterminado: `CollationStrength.Tertiary`	`Strength`
`numericOrdering`	(Opcional) Especifica si el controlador compara las cadenas numéricas como números. Si este argumento `true` es, el controlador compara las cadenas numéricas como números. Por ejemplo, al comparar las cadenas "10" y "2", el controlador trata los valores como 10 2y, y encuentra 10 que es mayor. Si este argumento es `false` o se excluye, el controlador compara las cadenas numéricas como cadenas. Por ejemplo, al comparar las cadenas "10" y "2", el controlador compara un carácter a la vez. Como "1" es menor que "2", el controlador encuentra10que " " es menor que "2". Para obtener más información, consulte Restricciones de intercalación en el manual del servidor MongoDB. Tipo de datos: `boolean` Predeterminado: `false`	`NumericOrdering`
`alternate`	(Opcional) Especifica si el controlador considera los espacios en blanco y la puntuación como caracteres base para fines de comparación. Tipo de datos: CollationAlternate Valor predeterminado: `CollationAlternate.NonIgnorable` (los espacios y la puntuación se consideran caracteres base)	`Alternate`
`maxVariable`	(Opcional) Especifica qué caracteres considera el controlador como ignorables cuando el `alternate` argumento `CollationAlternate.Shifted` es. Tipo de datos: CollationMaxVariable Valor predeterminado: `CollationMaxVariable.Punctuation` (el controlador ignora la puntuación y los espacios)	`MaxVariable`
`normalization`	(Opcional) Especifica si el controlador normaliza el texto según sea necesario. La mayoría del texto no requiere normalización. Para obtener más información sobre la normalización, consulte la documentación de ICU. Tipo de datos: `boolean` Predeterminado: `false`	`Normalization`
`backwards`	(Opcional) Especifica si las cadenas que contienen diacríticos se ordenan desde el final de la cadena hacia el principio. Tipo de datos: `boolean` Valor predeterminado: `false`	`Backwards`

Más información sobre la intercalación en la página Intercalación en el manual de MongoDB Server.

Valor de retorno

El método UpdateOne() devuelve un UpdateResult, y el método UpdateOneAsync() devuelve un objeto Task<UpdateResult>. La clase UpdateResult contiene las siguientes propiedades:

Propiedad	Descripción
`IsAcknowledged`	Indica si la operación de actualización fue reconocida por MongoDB. Tipo de dato: `bool`
`IsModifiedCountAvailable`	Indica si puede leer la cantidad de registros de actualización en el `UpdateResult`. Tipo de dato: `bool`
`MatchedCount`	La cantidad de documentos que coincidieron con el filtro de query, independientemente de si uno fue actualizado. Tipo de dato: `long`
`ModifiedCount`	El número de documentos actualizados por la operación de actualización. Tipo de dato: `long`
`UpsertedId`	El ID del documento que fue insertado o actualizado en la base de datos, si el driver realizó una actualización o inserción. Tipo de dato: BsonValue

Información Adicional

Para ejemplos ejecutables de las operaciones de actualización, consulta los siguientes ejemplos de uso:

UpdateOne()

Para obtener más información sobre cómo crear filtros de query, consulta la guía Crear un filtro de query.

Documentación de la API

Para obtener más información sobre cualquiera de los métodos o tipos discutidos en esta guía, consulta la siguiente documentación de la API:

Volver

Acceder a datos desde un cursor

Campos