/ /

Update Documents

Overview

En esta guía, puedes aprender a utilizar la librería PHP de MongoDB para actualizar documentos en una colección de MongoDB. Puedes llamar al método MongoDB\Collection::updateOne() para actualizar un solo documento o al método MongoDB\Collection::updateMany() para actualizar varios documentos.

Datos de muestra

Los ejemplos de esta guía utilizan la colección restaurants en la base de datos sample_restaurants de los conjuntos de datos de muestra de Atlas. Para acceder a esta colección desde tu aplicación PHP, instancia un MongoDB\Client que se conecte a un clúster Atlas y asigna el siguiente valor a tu variable $collection:

$collection = $client->sample_restaurants->restaurants;

Para saber cómo crear una implementación gratuita de MongoDB y cargar los conjuntos de datos de ejemplo, consulta la guía MongoDB Primeros Pasos.

Operaciones de actualizar

Puedes realizar operaciones de actualización en MongoDB utilizando los siguientes métodos:

MongoDB\Collection::updateOne()que actualiza el primer documento que coincide con los criterios de búsqueda
MongoDB\Collection::updateMany(), que actualiza todos los documentos que coinciden con los criterios de búsqueda

Cada método de actualización requiere los siguientes parámetros:

Documento de filtro de query: Especifica qué documentos actualizar. Para obtener más información sobre los filtros de query, consulta la sección Documentos de filtros de query en el manual de MongoDB Server.
Actualizar documento: Especifica el operador de actualización, o el tipo de actualización a realizar, así como los campos y valores que se deben cambiar. Para obtener una lista de operadores de actualización y su uso, consulta la Guía de operadores de actualización de campos en el manual de MongoDB Server.

Actualizar un documento

El siguiente ejemplo utiliza el método updateOne() para actualizar el valor name de un documento en la colección restaurants de 'Bagels N Buns' a '2 Bagels 2 Buns':

$result = $collection->updateOne(
    ['name' => 'Bagels N Buns'],
    ['$set' => ['name' => '2 Bagels 2 Buns']],
);

Actualizar muchos documentos

El siguiente ejemplo utiliza el método updateMany() para actualizar todos los documentos que tengan un valor cuisine de 'Pizza'. Después de la actualización, los documentos tienen un cuisine valor de 'Pasta'.

$result = $collection->updateMany(
    ['cuisine' => 'Pizza'],
    ['$set' => ['cuisine' => 'Pasta']],
);

Personaliza la operación de actualizar

Puedes modificar el comportamiento de los métodos updateOne() y updateMany() pasando un arreglo que especifique los valores de opciones como parámetro. La siguiente tabla describe algunas opciones que puedes configurar en el arreglo:

Opción	Descripción
`upsert`	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 la instrucción de inserción en el manual de MongoDB Server. por defecto en `false`.
`bypassDocumentValidation`	Especifica si la operación de actualización omite la validación del documento. Esto permite actualizar documentos que no cumplen con los requisitos de validación del esquema, si los hubiera. Para obtener más información sobre la validación del esquema, consulte Validación de esquema en el manual del servidor MongoDB. El valor predeterminado `false` es.
`sort`	Se aplica solo a `updateOne()`. Especifica el orden de clasificación que se aplicará a los documentos antes de realizar la operación de actualización.
`collation`	Especifica el tipo de intercalación de lenguaje que se debe usar al clasificar los resultados. Para aprender más, consulte la sección Intercalación de esta página.
`arrayFilters`	Especifica a qué elementos del arreglo se aplica una actualización si la operación modifica los campos del arreglo.
`hint`	Establece el índice para buscar documentos. Para más información, consulta la instrucción de pistas en el manual de MongoDB Server.
`writeConcern`	Establece el nivel de confirmación de escritura (write concern) para la operación. Para más información, consulta nivel de confirmación de escritura (Write Concern) en el manual de MongoDB Server.
`let`	Especifica un documento con una lista de valores para mejorar la legibilidad de la operación. Los valores deben ser expresiones constantes o cerradas que no hagan referencia a campos de documentos. Para obtener más información, consulta la instrucción let en el manual de MongoDB Server.
`comment`	Un comentario que debe adjuntarse a la operación. Para obtener más información, consulta la guía de campos de inserción de comandos en el manual del MongoDB Server.

El siguiente ejemplo utiliza el método updateMany() para encontrar todos los documentos que tienen borough valor de 'Manhattan'. Luego actualiza el valor borough en estos documentos a 'Manhattan (north)'. Debido a que la opción upsert está configurada en true, la MongoDB PHP librería inserta un nuevo documento si el filtro de consulta no coincide con ningún documento existente.

$result = $collection->updateMany(
    ['borough' => 'Manhattan'],
    ['$set' => ['borough' => 'Manhattan (north)']],
    ['upsert' => true],
);

Intercalación

Para especificar una intercalación para tu operación, pasa un parámetro arreglo $options que establezca la opción collation en el método de la operación. Asigna la opción collation a un arreglo que configure las reglas de intercalación.

La siguiente tabla describe los campos que se pueden configurar para la intercalación:

Campo	Descripción
`locale`	(Obligatorio) 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. Tipo de datos: `string`
`caseLevel`	(Opcional) Especifica si se debe incluir la comparación de mayúsculas y minúsculas. Cuando se establece `true` en, el comportamiento de la comparación depende del valor del `strength` campo: - Si `strength` `1`es, la biblioteca PHP compara caracteres base y mayúsculas y minúsculas. - Si `strength` `2`es, la biblioteca PHP compara caracteres base, diacríticos, otras diferencias secundarias y mayúsculas y minúsculas. - Si `strength` es cualquier otro valor, este campo se ignora. Cuando se establece `false` en, la biblioteca PHP no incluye la comparación de mayúsculas y minúsculas en el nivel `1` de fuerza `2` o. Tipo de datos: `bool` Predeterminado: `false`
`caseFirst`	(Opcional) Especifica el orden de clasificación de las diferencias entre casos durante las comparaciones de nivel terciario. Tipo de datos: `string` Valor predeterminado: `"off"`
`strength`	(Opcional) Especifica el nivel de comparación a realizar, tal como se define en la documentación de la UCI. Tipo de datos: `int` Valor predeterminado: `3`
`numericOrdering`	(Opcional) Especifica si el driver compara las strings numéricas como números. Si se establece en `true`, la librería PHP compara las strings numéricas como números. Por ejemplo, al comparar las strings "10" y "2", la librería utiliza los valores numéricos de las strings y trata "10" como mayor que "2". Si se establece en `false`, la librería PHP compara las strings numéricas como strings. Por ejemplo, al comparar las strings "10" y "2", la librería compara un carácter a la vez y trata "10" como menor que "2". Para obtener más información, consulte Restricciones de intercalación en el manual de MongoDB Server. Tipo de dato: `bool` Por defecto: `false`
`alternate`	(Opcional) Especifica si la librería considera los espacios en blanco y la puntuación como caracteres base a los efectos de la comparación. Tipo de dato: `string` Por defecto: `"non-ignorable"`
`maxVariable`	(Opcional) Especifica qué caracteres considera la biblioteca ignorables cuando el `alternate` campo se establece `"shifted"` en. Tipo de datos: `string` Valor predeterminado: `"punct"`
`backwards`	(Opcional) Especifica si las cadenas que contienen diacríticos se ordenan desde el final de la cadena hacia el principio. Tipo de datos: `bool` Valor predeterminado: `false`

Para obtener más información sobre la intercalación y los posibles valores de cada campo, consulta la entrada Collation en el manual del servidor de MongoDB.

Valor de retorno

Los métodos updateOne() y updateMany() devuelven una instancia de la clase MongoDB\UpdateResult. Esta clase contiene las siguientes funciones miembro:

Función	Descripción
`getMatchedCount()`	Devuelve el número de documentos que coincidieron con el filtro de query, independientemente de cuántos se actualizaron.
`getModifiedCount()`	Devuelve el número de documentos modificados por la operación de actualización. Si un document actualizado es idéntico al original, no se incluye en este recuento.
`isAcknowledged()`	Devuelve un booleano que indica si el servidor reconoció la operación de guardar.
`getUpsertedCount()`	Devuelve el número de document que fueron insertados o actualizados en la base de datos.
`getUpsertedId()`	Devuelve el ID del document que fue inserción en la base de datos, si el driver realizó una inserción.

El siguiente ejemplo utiliza el método updateMany() para actualizar el campo name de los documentos coincidentes de 'Dunkin' Donuts' a 'Dunkin''. Llama a la función nodo getModifiedCount() para imprimir el número de documentos modificados:

$result = $collection->updateMany(
    ['name' => 'Dunkin\' Donuts'],
    ['$set' => ['name' => 'Dunkin\'']],
);
echo 'Modified documents: ', $result->getModifiedCount();

Modified documents: 206

Actualizar el Creador

Se puede utilizar la MongoDB\Builder\Update clase para construir documentos de actualizar con soporte para la finalización de código IDE y verificación de tipo en PHP. La clase Update proporciona métodos de fábrica que corresponden a los operadores de actualización de MongoDB como $set, $inc y $unset.

Para usar el generador de actualizaciones, importe las siguientes clases en su aplicación:

use MongoDB\Builder\Query;
use MongoDB\Builder\Update;

El siguiente ejemplo utiliza el método factory Update::set() para actualizar el campo name a '2 Bagels 2 Buns' en el primer documento coincidente con un valor name de 'Bagels N Buns' en la colección restaurants:

$result = $collection->updateOne(
    Query::query(name: Query::eq('Bagels N Buns')),
    Update::set(name: '2 Bagels 2 Buns'),
);

Para aplicar varios operadores de actualización en una sola operación, pasa los operadores al constructor MongoDB\Builder\Update. El siguiente ejemplo combina Update::set() y Update::unset() para establecer el campo cuisine en Pasta y eliminar el campo grades de todos los documentos con un valor de cuisine de 'Pizza':

$result = $collection->updateMany(
    Query::query(cuisine: Query::eq('Pizza')),
    new Update(
        Update::set(cuisine: 'Pasta'),
        Update::unset('grades'),
    ),
);

Para obtener más información sobre las clases de generadores y ver más ejemplos, consulta la guía Operaciones con desarrolladores.

Información Adicional

Para obtener más información sobre cómo crear filtros de query, se puede consultar la Especificar una query.

Documentación de la API

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

Volver

Acceder a datos desde un cursor

Reemplazar Documentos