/ /

Insertar documentos

Overview

En esta guía, puede aprender cómo usar la Librería PHP de MongoDB para añadir documentos a una colección de MongoDB realizando operaciones de inserción.

Una operación de inserción inserta uno o más documentos en una colección de MongoDB. Puedes realizar una operación de inserción mediante los siguientes métodos:

MongoDB\Collection::insertOne() método para insertar un solo documento
MongoDB\Collection::insertMany() método para insertar uno o más 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.

El campo `_id`

En una colección de MongoDB, cada documento debe contener un campo _id con un valor de campo único.

MongoDB permite gestionar este campo de dos formas:

Establece el campo _id para cada documento tú mismo, asegurándote de que cada valor sea único.
Permite que el driver genere automáticamente valores únicos de ObjectId para cada campo _id del documento.

A menos que pueda garantizar la exclusividad, recomendamos dejar que el controlador genere automáticamente los valores de _id.

Nota

Los valores duplicados _id vulneran las restricciones de índice único, lo cual provoca que el controlador devuelva un error MongoDB\Driver\Exception\BulkWriteException.

Para obtener más información sobre el campo _id, consulta la guía Índices únicos en el manual del MongoDB Server.

Para obtener más información sobre la estructura y las reglas de los documentos, consulta la guía de Documentos en el manual de MongoDB Server.

Inserta un documento

Para añadir un único documento a una colección de MongoDB, llama al método MongoDB\Collection::insertOne() y pasa el documento que quieras añadir.

El siguiente ejemplo inserta un documento en la colección restaurants:

$result = $collection->insertOne(['name' => 'Mongo\'s Burgers']);

Inserta varios documentos

Para agregar varios documentos a una colección de MongoDB, llama al método MongoDB\Collection::insertMany() y pasa un arreglo que contenga la lista de documentos que deseas agregar.

El siguiente ejemplo inserta dos documentos en la colección restaurants:

$restaurants = [
    ['name' => 'Mongo\'s Burgers'],
    ['name' => 'Mongo\'s Pizza'],
];
$result = $collection->insertMany($restaurants);

Modificar el comportamiento de inserción

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

Campo	Descripción
`bypassDocumentValidation`	Si se establece en `true`, permite que la operación de guardar se excluya de la validación a nivel de documento. Por defecto, `false`. Tipo: `bool`
`writeConcern`	Establece el nivel de confirmación de escritura (write concern) para la operación. Por defecto, el nivel de confirmación de escritura (write concern) del namespace. Tipo: `MongoDB\Driver\WriteConcern`
`ordered`	Si `true` se establece en, la operación deja de insertar documentos cuando falla una inserción. Si se establece en,`false` la operación continúa insertando los documentos restantes cuando falla una inserción. No se puede pasar esta opción al `insertOne()` método. `true`El valor predeterminado es. Tipo: `bool`
`comment`	Un comentario para adjuntar a la operación. Para obtener más información, consulte la guía insertar campos de comando en el manual de MongoDB Server. Tipo: cualquier tipo BSON válido

Ejemplo

El siguiente código utiliza el método insertMany() para insertar tres nuevos documentos en una colección. Dado que el campo bypassDocumentValidation se configura en true en una matriz de opciones, esta operación de inserción omite la validación a nivel de documento:

$docs = [
    ['name' => 'Mongo\'s Burgers'],
    ['name' => 'Mongo\'s Pizza'],
    ['name' => 'Mongo\'s Tacos'],
];
$result = $collection->insertMany($docs, ['bypassDocumentValidation' => true]);

Información Adicional

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

Bases de datos y colecciones

Buscar documentos