/ /

Insertar documentos

Overview

En esta guía, puedes aprender cómo insertar documentos en colecciones de MongoDB desde tu aplicación Laravel utilizando Laravel MongoDB.

Cuando insertes los documentos, asegúrate de que los datos no violen ningún índice único en la colección. Al insertar el primer documento de una colección o crear una nueva colección, MongoDB crea automáticamente un índice único en el campo _id.

Para obtener más información sobre cómo crear índices en colecciones de MongoDB utilizando el generador de esquemas de Laravel, consulta la sección Gestionar índices de la documentación del generador de esquemas.

Para obtener más información sobre los modelos Eloquent en la integración de Laravel, consulte la sección Modelar sus datos.

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.

Inserta un documento

Los ejemplos de esta sección muestran cómo utilizar los métodos Eloquent save() y create() para insertar una instancia de un modelo Concert como un documento de MongoDB.

Método save()

Cuando el método save() tenga éxito, podrás acceder a la instancia del modelo en la que llamaste a ese método.

Si la operación falla, a la instancia del modelo se le asigna null.

Este código de ejemplo realiza las siguientes acciones:

Crea una nueva instancia del modelo Concert
Asigna valores de string a los campos performer y venue
Asigna un arreglo de cadenas de texto al campo genre
Asigna un número al campo ticketsSold
Asigna una fecha al campo performanceDate utilizando el paquete Carbon
Inserta el documento llamando al método save()

$concert = new Concert();
$concert->performer = 'Mitsuko Uchida';
$concert->venue = 'Carnegie Hall';
$concert->genres = ['classical'];
$concert->ticketsSold = 2121;
$concert->performanceDate = Carbon::create(2024, 4, 1, 20, 0, 0, 'EST');
$concert->save();

Puedes recuperar el valor _id del documento insertado accediendo al nodo id del modelo, como se muestra en el siguiente ejemplo de código:

$insertedId = $concert->id;

create() Método

Si habilita la asignación masiva definiendo los atributos $fillable o $guarded, puede usar el método create() del modelo Eloquent para realizar la inserción en una sola llamada, como se muestra en el siguiente ejemplo:

$insertResult = Concert::create([
    'performer' => 'The Rolling Stones',
    'venue' => 'Soldier Field',
    'genres' => [ 'rock', 'pop', 'blues' ],
    'ticketsSold' => 59527,
    'performanceDate' => Carbon::create(2024, 6, 30, 20, 0, 0, 'CDT'),
]);

Inserta varios documentos

Este ejemplo muestra cómo utilizar el método Eloquent insert() para insertar múltiples instancias de un modelo Concert como documentos MongoDB. Este método de inserción masiva reduce el número de llamadas que tu aplicación necesita hacer para guardar los documentos.

Cuando el método insert() tiene éxito, devuelve el valor true. Si falla, lanza una excepción.

El siguiente ejemplo guarda múltiples modelos en una sola llamada pasándolos como un arreglo al método insert():

$data = [
    [
        'performer' => 'Brad Mehldau',
        'venue' => 'Philharmonie de Paris',
        'genres' => [ 'jazz', 'post-bop' ],
        'ticketsSold' => 5745,
        'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')),
    ],
    [
        'performer' => 'Billy Joel',
        'venue' => 'Madison Square Garden',
        'genres' => [ 'rock', 'soft rock', 'pop rock' ],
        'ticketsSold' => 12852,
        'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')),
    ],
];
Concert::insert($data);

Nota

Este ejemplo envuelve las fechas en la clase MongoDB\BSON\UTCDateTime para convertirlo a un tipo que MongoDB pueda serializar, porque Laravel omite el casteo de atributos en operaciones masivas de inserción.

Ejemplos totalmente ejecutables

Las siguientes secciones proporcionan ejemplos de código totalmente ejecutables que demuestran cómo insertar 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.

Insertar un documento

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
inserta un documento en la colección movies
Imprime el documento recién insertado

El ejemplo ejecuta el método create() para insertar un documento que contiene los siguientes campos y valores:

title valor de "Marriage Story"
year valor de 2019
runtime valor de 136

$movie = Movie::create([
    'title' => 'Marriage Story',
    'year' => 2019,
    'runtime' => 136,
]);
echo $movie->toJson();

{
    "title": "Marriage Story",
    "year": 2019,
    "runtime": 136,
    "updated_at": "...",
    "created_at": "...",
    "_id": "..."
}

Este ejemplo realiza las siguientes acciones:

Accede a la colección movies llamando al método table() desde la fachada DB
inserta un documento en la colección movies
Imprime si la operación de inserción ha tenido éxito

El ejemplo ejecuta el método insert() para insertar un documento que contiene los siguientes campos y valores:

title valor de "Marriage Story"
year valor de 2019
runtime valor de 136

$success = DB::table('movies')
    ->insert([
        'title' => 'Marriage Story',
        'year' => 2019,
        'runtime' => 136,
    ]);
echo 'Insert operation success: ' . ($success ? 'yes' : 'no');

Insert operation success: yes

Inserta 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
Inserta documentos en la colección movies
Imprime si la operación de inserción ha tenido éxito

El ejemplo llama al método insert() para insertar documentos que representan películas lanzadas en 2023.

$success = Movie::insert([
    [
        'title' => 'Anatomy of a Fall',
        'release_date' => new UTCDateTime(new DateTimeImmutable('2023-08-23')),
    ],
    [
        'title' => 'The Boy and the Heron',
        'release_date' => new UTCDateTime(new DateTimeImmutable('2023-12-08')),
    ],
    [
        'title' => 'Passages',
        'release_date' => new UTCDateTime(new DateTimeImmutable('2023-06-28')),
    ],
]);
echo 'Insert operation success: ' . ($success ? 'yes' : 'no');

Insert operation success: yes

Este ejemplo realiza las siguientes acciones:

Accede a la colección movies llamando al método table() desde la fachada DB
Inserta documentos en la colección movies
Imprime si la operación de inserción ha tenido éxito

El ejemplo llama al método insert() para insertar documentos que representan películas lanzadas en 2023.

$success = DB::table('movies')
    ->insert([
        [
            'title' => 'Anatomy of a Fall',
            'release_date' => new UTCDateTime(new DateTimeImmutable('2023-08-23')),
        ],
        [
            'title' => 'The Boy and the Heron',
            'release_date' => new UTCDateTime(new DateTimeImmutable('2023-12-08')),
        ],
        [
            'title' => 'Passages',
            'release_date' => new UTCDateTime(new DateTimeImmutable('2023-06-28')),
        ],
    ]);
echo 'Insert operation success: ' . ($success ? 'yes' : 'no');

Insert operation success: yes

Información Adicional

Para obtener más información sobre la extensión API de Carbon PHP, consulte el repositorio Carbon en GitHub.

Para aprender a modificar datos que ya están en MongoDB, consulte la guía Actualizar documentos.

Volver

Constructor de esquema

Documentos de query