/ /

Update Documents

Overview

En esta guía, puedes aprender a modificar documentos en tu colección de MongoDB desde tu aplicación Laravel usando Laravel MongoDB. Utiliza operaciones de actualización para modificar documentos existentes o insertar un documento si ninguno coincide con los criterios de búsqueda.

Puedes guardar los cambios en una instancia de un modelo Eloquent o utilizar la sintaxis fluida de Eloquent para encadenar una operación de actualización en métodos que devuelvan un objeto colección de Laravel.

Esta guía proporciona ejemplos de las siguientes operaciones de actualización:

Actualizar un documento
Actualiza varios documentos
Actualizar o insertar en una sola operación
Actualizar arreglos en un documento

Modelo muestra

Las operaciones en esta guía hacen referencia a la siguiente clase de modelo Eloquent:

Concierto.php

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Concert extends Model
{
    protected $connection = 'mongodb';
    protected $fillable = ['performer', 'venue', 'genres', 'ticketsSold', 'performanceDate'];
    protected $casts = ['performanceDate' => 'datetime'];
}

Tip

El atributo $fillable permite utilizar la asignación masiva de Laravel para operaciones de inserción. Para obtener más información sobre la asignación masiva, consulta Personalizar la asignación masiva en la documentación de la Clase de Modelo Eloquent.

El atributo $casts indica a Laravel que debe convertir los atributos a tipos de datos comunes. Para seguir aprendiendo, consulta Conversión de atributos en la documentación de Laravel.

Actualizar un documento

Puedes actualizar un documento de las siguientes maneras:

Modifique una instancia del modelo y guarde los cambios llamando al método save().
Encadena los métodos para recuperar una instancia de un modelo y realizar actualizaciones en ella llamando al método update().

El siguiente ejemplo muestra cómo actualizar un documento modificando una instancia del modelo y llamando a su método save():

$concert = Concert::first();
$concert->venue = 'Manchester Arena';
$concert->ticketsSold = 9543;
$concert->save();

Cuando el método save() se ejecuta correctamente, la instancia del modelo en la que se ha llamado al método contiene los valores actualizados.

Si la operación falla, la Integración Laravel asigna a la instancia del modelo un valor null.

El siguiente ejemplo muestra cómo actualizar un documento encadenando métodos para recuperar y actualizar el primer documento coincidente:

$concert = Concert::where(['performer' => 'Brad Mehldau'])
    ->orderBy('id')
    ->first()
    ->update(['venue' => 'Manchester Arena', 'ticketsSold' => 9543]);

Nota

La llamada orderBy() ordena los resultados por el campo _id para garantizar un orden de clasificación consistente. Para obtener más información sobre la ordenación en MongoDB, consulte la entrada de glosario Orden natural en el manual del servidor.

Cuando el método update() se ejecuta correctamente, la operación retorna el número de documentos actualizados.

Si la parte de recuperación de la llamada no coincide con ningún documento, la Integración de Laravel devuelve el siguiente error:

Error: Call to a member function update() on null

Actualiza varios documentos

Para realizar una actualización en uno o más documentos, añade el método update() a los resultados de un método que recupere los documentos como un objeto de colección de Laravel, como where().

El siguiente ejemplo muestra cómo encadenar llamadas para recuperar documentos coincidentes y actualizarlos:

Concert::whereIn('venue', ['Philharmonie de Paris', 'Soldier Field'])
    ->update(['venue' => 'Concertgebouw', 'ticketsSold' => 0]);

Cuando el método update() se ejecuta correctamente, la operación retorna el número de documentos actualizados.

Si la parte de recuperación de la llamada no coincide con ningún documento en la colección, la integración de Laravel devuelve el siguiente error:

Error: Call to a member function update() on null

Actualizar o insertar en una sola operación

Una operación de Upsert te permite realizar una actualización o inserción en una sola operación. Esta operación simplifica la tarea de actualizar un documento o insertarlo si no existe.

A partir de la v4.7, puedes realizar una operación de inserción actualizada utilizando cualquiera de los siguientes métodos:

upsert()Al utilizar este método, puedes realizar una agrupar inserciones para cambiar o insertar varios documentos en una sola operación.
update(): Cuando se utiliza este método, debe especificar la opción upsert para actualizar todos los documentos que coincidan con el filtro de query o insertar un documento si no se encuentran documentos que coincidan. Solo se admite este método inserción en las versiones v4.6 y anteriores.

Método de inserción

El método upsert() acepta los siguientes parámetros:

$valuesArreglo de campos y valores que especifican los documentos a actualizar o insertar.
$uniqueBy: Uno o más campos que identifican de manera única los documentos en tu primer parámetro de arreglo.
$update: arreglo opcional de campos que se actualizarán si existe un documento coincidente. Si omites este parámetro, la Integración Laravel actualiza todos los campos.

Para especificar una inserción en el método upsert(), pasa los parámetros requeridos como se muestra en el siguiente ejemplo de código:

YourModel::upsert(
   [/* documents to update or insert */],
   '/* unique field */',
   [/* fields to update */],
);

Ejemplo

Este ejemplo muestra cómo usar el método upsert() para realizar una actualización o inserción en una sola operación. Haz clic en el botón VIEW OUTPUT para ver los cambios de datos resultantes cuando hay un documento en el que el valor de performer es 'Angel Olsen' en la colección:

Concert::upsert([
    ['performer' => 'Angel Olsen', 'venue' => 'Academy of Music', 'ticketsSold' => 275],
    ['performer' => 'Darondo', 'venue' => 'Cafe du Nord', 'ticketsSold' => 300],
], 'performer', ['ticketsSold']);

{
  "_id": "...",
  "performer": "Angel Olsen",
  "venue": "State Theatre",
  "genres": [
    "indie",
    "rock"
  ],
  "ticketsSold": 275,
  "updated_at": ...
},
{
  "_id": "...",
  "performer": "Darondo",
  "venue": "Cafe du Nord",
  "ticketsSold": 300,
  "updated_at": ...
}

En el documento en el que el valor de performer es 'Angel Olsen', el valor del campo venue no se actualiza, ya que la inserción específica que la actualización solo se aplica al campo ticketsSold.

Método de actualizar

Para especificar una inserción en un método update(), establece la opción upsert en true, como se muestra en el siguiente ejemplo de código:

YourModel::where(/* match criteria */)
   ->update(
       [/* update data */],
       ['upsert' => true]);

Cuando el método update() se encadena a una query, realiza una de las siguientes acciones:

Si la query coincide con los documentos, el método update() modifica los documentos coincidentes.
Si la consulta no coincide con ningún documento, el método update() inserta un documento que contiene los datos de la actualización y los datos de los criterios de coincidencia exacta.

Ejemplo

Este ejemplo muestra cómo pasar la opción upsert al método update() para realizar una actualización o inserción en una sola operación. Haga clic en el botón VIEW OUTPUT para ver el documento de ejemplo insertado cuando no existan documentos coincidentes:

Concert::where(['performer' => 'Jon Batiste', 'venue' => 'Radio City Music Hall'])
    ->update(
        ['genres' => ['R&B', 'soul'], 'ticketsSold' => 4000],
        ['upsert' => true],
    );

{
  "_id": "660c...",
  "performer": "Jon Batiste",
  "venue": "Radio City Music Hall",
  "genres": [
    "R&B",
    "soul"
  ],
  "ticketsSold": 4000,
  "updated_at": ...
}

Actualizar arreglos en un documento

En esta sección, puedes ver ejemplos de las siguientes operaciones que actualizan valores de arreglo en un documento MongoDB:

Añadir valores a un arreglo
Remover valores de un arreglo
Actualizar el valor de un elemento de arreglo

Estos ejemplos modifican el documento de muestra creado por la siguiente operación de inserción:

Concert::create([
    'performer' => 'Mitsuko Uchida',
    'genres' => ['classical', 'dance-pop'],
]);

Añadir valores a un ejemplo de arreglo

Esta sección muestra cómo utilizar el método push() para agregar valores a un arreglo en un documento de MongoDB. Puedes pasar uno o más valores para agregar y establecer el parámetro opcional unique en true para omitir la adición de valores duplicados en el arreglo. El siguiente ejemplo de código muestra la estructura de una llamada al método push():

YourModel::where(<match criteria>)
   ->push(
       <field name>,
       [<values>], // array or single value to add
       unique: true); // whether to skip existing values

El siguiente ejemplo muestra cómo agregar el valor "baroque" al campo arreglo genres de un documento que cumpla con la condición. Hacer clic en el botón VIEW OUTPUT para ver el documento actualizado:

Concert::where('performer', 'Mitsuko Uchida')
    ->push(
        'genres',
        ['baroque'],
    );

{
  "_id": "660eb...",
  "performer": "Mitsuko Uchida",
  "genres": [
      "classical",
      "dance-pop",
  ],
  "updated_at": ...,
  "created_at": ...
}

Remover valores de un ejemplo de arreglo

Esta sección muestra cómo utilizar el método pull() para eliminar valores de un arreglo en un documento de MongoDB. Se puede pasar uno o varios valores para remover del arreglo. El siguiente ejemplo de código muestra la estructura de una llamada de método pull():

YourModel::where(<match criteria>)
   ->pull(
       <field name>,
       [<values>]); // array or single value to remove

El siguiente ejemplo muestra cómo remover los valores de arreglo "classical" y "dance-pop" del campo de arreglo genres. Haz clic en el botón VIEW OUTPUT para ver el documento actualizado:

Concert::where('performer', 'Mitsuko Uchida')
    ->pull(
        'genres',
        ['dance-pop', 'classical'],
    );

{
  "_id": "660e...",
  "performer": "Mitsuko Uchida",
  "genres": [],
  "updated_at": ...,
  "created_at": ...
}

Actualizar el valor de un elemento de arreglo: ejemplo

Esta sección muestra cómo usar el operador posicional $ para actualizar elementos específicos de arreglo en un documento de MongoDB. El operador $ representa el primer elemento del arreglo que coincide con la consulta. El siguiente ejemplo de código muestra la estructura de una llamada de actualización de operador posicional en un único documento coincidente:

Nota

Actualmente, la Integración de Laravel ofrece esta operación solo en el facade DB y no en el ORM Eloquent.

DB::connection('mongodb')
   ->getCollection(<collection name>)
   ->updateOne(
       <match criteria>,
       ['$set' => ['<array field>.$' => <replacement value>]]);

El siguiente ejemplo muestra cómo reemplazar el valor de arreglo "dance-pop" por "contemporary" en el campo de la matriz genres. Haz clic en el botón VIEW OUTPUT para ver el documento actualizado:

$match = ['performer' => 'Mitsuko Uchida', 'genres' => 'dance-pop'];
$update = ['$set' => ['genres.$' => 'contemporary']];
DB::connection('mongodb')
    ->getCollection('concerts')
    ->updateOne($match, $update);

{
  "_id": "660e...",
  "performer": "Mitsuko Uchida",
  "genres": [
    "classical",
    "contemporary"
  ],
  "updated_at": ...,
  "created_at": ...
}

Para obtener más información sobre los operadores de actualización de arreglos, consulta Operadores de actualización de arreglos en el manual del servidor.

Ejemplos totalmente ejecutables

Las siguientes secciones proporcionan ejemplos de código totalmente ejecutables que demuestran cómo actualizar documentos mediante la integración de Laravel. Estos ejemplos utilizan la colección sample_mflix.movies de los conjuntos de datos de muestra de Atlas.

Tip

Puedes ejecutar los ejemplos completos desde tu propia aplicación Laravel o desde la aplicación my-app creada en el tutorial Introducción. Los ejemplos utilizan la clase de modelo Movie.php creada en este tutorial para demostrar operaciones en la colección de MongoDB movies. Para ejecutar la operación, puedes copiar el código de muestra en un endpoint del controlador en tu aplicación Laravel.

Para ver la salida esperada de la operación, puedes agregar una ruta web a tu aplicación que llame a la función controladora y devuelva el resultado a una interfaz web.

Actualizar un documento

Este ejemplo realiza las siguientes acciones:

Utiliza el modelo Movie Eloquent para representar la colección movies en la base de datos sample_mflix
Actualiza un documento de la colección movies que coincide con el filtro de query
Imprime el número de documentos actualizados

El ejemplo llama a los siguientes métodos en el modelo Movie:

where():: Coincide con los documentos en los que el valor del campo title es "Carol"
orderBy(): Ordena los documentos coincidentes por sus valores de _id ascendentes
first(): Recupera solo el primer documento coincidente
update(): Actualiza el valor del campo anidado imdb.rating de 6.9 a 7.3 y el valor del campo anidado imdb.votes de 493 a 142000

$updates = Movie::where('title', 'Carol')
    ->orderBy('id')
    ->first()
    ->update([
        'imdb' => [
            'rating' => 7.3,
            'votes' => 142000,
        ],
    ]);
echo 'Updated documents: ' . $updates;

Updated documents: 1

Actualiza varios documentos

Seleccione de las siguientes pestañas Eloquent y Query Builder para ver ejemplos de cada sintaxis de query correspondiente:

Este ejemplo realiza las siguientes acciones:

Utiliza el modelo Movie Eloquent para representar la colección movies en la base de datos sample_mflix
Actualiza documentos de la colección movies que coincidan con un filtro de query
Imprime el número de documentos actualizados

El ejemplo llama a los siguientes métodos en el modelo Movie:

where()Coincide con documentos en los que el valor del campo anidado imdb.rating es mayor que 9.0
update(): Actualiza los documentos coincidentes agregando un campo acclaimed y asignando su valor a true, luego devuelve el número de documentos actualizados

$updates = Movie::where('imdb.rating', '>', 9.0)
    ->update(['acclaimed' => true]);
echo 'Updated documents: ' . $updates;

Updated documents: 20

Este ejemplo realiza las siguientes acciones:

Accede a la colección movies llamando al método table() desde la fachada DB
Actualiza documentos de la colección movies que coincidan con un filtro de query
Imprime el número de documentos actualizados

El ejemplo llama a los siguientes métodos para crear query:

where()Coincide con documentos en los que el valor del campo anidado imdb.rating es mayor que 9.0
update(): Actualiza los documentos coincidentes agregando un campo acclaimed y asignando su valor a true, luego devuelve el número de documentos actualizados

$updates = DB::table('movies')
    ->where('imdb.rating', '>', 9.0)
    ->update(['acclaimed' => true]);
echo 'Updated documents: ' . $updates;

Updated documents: 20

Información Adicional

Para aprender cómo insertar documentos en una colección MongoDB, consulta la guía Insertar documentos.

Volver

Registro de query

Delete Documents