/ /

Reemplazar Documentos

Overview

En esta guía, puedes aprender a utilizar la Librería PHP de MongoDB para ejecutar una operación de reemplazo en una colección de MongoDB. Una operación de reemplazo se comporta de manera diferente a una operación de actualización. Una operación de actualización modifica solo los campos especificados en un documento de destino. Una operación de reemplazo remueve todos los campos en el documento de destino y los reemplaza por otros nuevos.

Para reemplazar un documento, utiliza el método MongoDB\Collection::replaceOne().

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.

Operación de reemplazo

Puedes realizar una operación de reemplazo utilizando MongoDB\Collection::replaceOne(). Este método remueve todos los campos excepto el campo _id del primer documento que coincide con los criterios de búsqueda. Luego, inserta los campos y valores que especifiques en el documento.

Parámetros necesarios

El método replaceOne() requiere los siguientes parámetros:

filtro de query documento, que determina los documentos a reemplazar. 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.
Reemplaza el documento, que especifica los campos y valores que se deben insertar en el nuevo documento.

Valor de retorno

El método replaceOne() devuelve un objeto MongoDB\UpdateResult. El tipo MongoDB\UpdateResult contiene los siguientes métodos:

Método	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.
`getUpsertedCount()`	Devuelve el número de documentos insertados en la base de datos, si los hay.
`getUpsertedId()`	Devuelve el ID del document que fue inserción en la base de datos, si el driver realizó una inserción.
`isAcknowledged()`	Devuelve un booleano que indica si el servidor reconoció la operación de guardar.

Ejemplo

El siguiente ejemplo utiliza el método replaceOne() para reemplazar los campos y valores de un documento en el que el valor del campo name es 'Pizza Town'. Luego, imprime el número de documentos modificados:

$replaceDocument = [
    'name' => 'Mongo\'s Pizza',
    'cuisine' => 'Pizza',
    'address' => [
        'street' => '123 Pizza St',
        'zipCode' => '10003',
    ],
    'borough' => 'Manhattan',
];
$result = $collection->replaceOne(['name' => 'Pizza Town'], $replaceDocument);
echo 'Modified documents: ', $result->getModifiedCount();

Modified documents: 1

Importante

Los valores de los campos _id son inmutables. Si tu documento de reemplazo especifica un valor para el campo _id, este debe coincidir con el valor _id del documento existente.

Modificar la operación de reemplazo

Puedes modificar el comportamiento del método MongoDB\Collection::replaceOne() pasando un arreglo que especifique 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 reemplazo realiza una operación de inserción/actualización si ningún documento coincide con el filtro de consulta. Para obtener más información, consulte la instrucción de inserción/actualización en el manual del servidor MongoDB. El valor predeterminado `false` es.
`bypassDocumentValidation`	Especifica si la operación de reemplazo omite la validación del documento. Esto permite reemplazar 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`	Especifica el orden de clasificación que se aplicará a los documentos antes de realizar la operación de reemplazo.
`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.
`hint`	Obtiene o define el índice para escanear documentos. Para obtener más información, consulta la instrucción de sugerencia en el manual del MongoDB Server.
`session`	Especifica la sesión del cliente a asociar con la operación.
`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`	Adjunta un comentario a la operación. Para obtener más información, consulte la guía insertar campos de comando en el manual de MongoDB Server.

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.

Ejemplo

El siguiente código utiliza el método replaceOne() para encontrar el primer documento en el que el campo name tenga el valor 'Food Town', y luego reemplaza este documento con uno nuevo en el que el valor name sea 'Food World'. Debido a que la opción upsert está configurada en true, la librería inserta un nuevo documento si el filtro de query no coincide con ningún documento existente:

$replaceDocument = [
    'name' => 'Food World',
    'cuisine' => 'Mixed',
    'address' => [
        'street' => '123 Food St',
        'zipCode' => '10003',
    ],
    'borough' => 'Manhattan',
];
$result = $collection->replaceOne(
    ['name' => 'Food Town'],
    $replaceDocument,
    ['upsert' => true],
);

Información Adicional

Para obtener más información sobre las operaciones de actualización, consulte la guía Actualizar documentos.

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

Update Documents

Delete Documents