Operaciones con Constructores

Overview

En esta guía, aprenderá sobre las clases de constructor que proporciona la biblioteca PHP para crear tipos utilizados en sus operaciones. Puede usar las clases de constructor y los métodos de fábrica del Generador de Agregaciones para crear filtros para otras operaciones, como buscar, actualizar y eliminar. Para obtener más información sobre el Generador de Agregaciones, consulte Constructor de agregaciones de la guía de Agregación.

Utilizar desarrolladores para crear queries ayuda a identificar errores en tiempo de compilación y a evitarlos en tiempo de ejecución. Esta guía proporciona información sobre las clases de desarrollador que puedes usar para realizar las siguientes tareas:

• Crear un filtro

• Definir un documento de actualización

• Modifica la salida del flujo de cambios

$options = [
    'limit' => 5,
    '<option name>' => '<specification>',
];

Esta guía proporciona ejemplos de cómo usar constructores en operaciones sin agregación. Para ver ejemplos de agregación, consulte la guía de Operaciones de Agregación.

$collection = $client->sample_geospatial->shipwrecks;

Importar clases de desarrolladores

Para ejecutar los ejemplos en esta guía, debes importar las siguientes clases en tu aplicación:

use MongoDB\Builder\Pipeline;
use MongoDB\Builder\Query;
use MongoDB\Builder\Stage;

Crear un filtro

Puedes usar los métodos de fábrica de la clase de generador Query para crear definiciones de filtros que se utilicen en las operaciones de búsqueda, actualización y eliminación. Cuando utilices el método de fábrica Query::query() para crear consultas, puedes utilizar la sintaxis de argumentos nombrados e implementar la seguridad de tipos. Para obtener más información sobre cómo crear filtros, consulta la guía Especificar una query.

Los siguientes pasos describen cómo crear una definición de filtro utilizando los desarrolladores:

1. Llame al método Query::query() para crear una consulta.

2. Pasa el nombre del campo para el filtro y un método de fábrica de la clase Query. Puedes pasar uno o más pares de nombres de campos y criterios en el filtro para aplicar múltiples cláusulas.

El siguiente código muestra la plantilla para crear una definición de filtro utilizando desarrolladores:

$filter = Query::query(
    <field name>: Query::<factory method>(<parameters>),
    <field name>: Query::<factory method>(<parameters>),
    ...
);

Para combinar criterios del query mediante operadores lógicos del query ($and, $or, $not, $nor), puedes utilizar la siguiente plantilla del query:

$filter = Query::<logical operator>(
    Query::query(<field name>: Query::<factory method>(<parameters>)),
    Query::query(<field name>: Query::<factory method>(<parameters>)),
    ...
);

Para obtener más información, consulte Operadores de consulta lógica en el manual de MongoDB Server.

Las siguientes secciones proporcionan ejemplos que utilizan constructores para crear definiciones de filtros para diferentes operaciones.

// Creates a query filter by using builders and
// retrieves matching documents
$docs = $collection->find(
    Query::query(
        feature_type: Query::eq('Wrecks - Visible'),
        coordinates: Query::near(
            Query::geometry(
                type: 'Point',
                coordinates: [-79.9, 9.3],
            ),
            maxDistance: 10000,
        ),
    ),
);
// Prints matching documents
foreach ($docs as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_id":...,"feature_type":"Wrecks - Visible","coordinates":[-79.9137115,9.3390503],...}
{"_id":...,"feature_type":"Wrecks - Visible","coordinates":[-79.9357223,9.3340302],...}
{"_id":...,"feature_type":"Wrecks - Visible","coordinates":[-79.9081268,9.3547792],...}
// Results truncated

// Creates a query filter by using builders
// and deletes the first matching document
$result = $collection->deleteOne(
    Query::or(
        Query::query(feature_type: Query::regex('nondangerous$', '')),
        Query::query(depth: Query::gt(10.0)),
    ),
);
// Prints number of deleted documents
echo 'Deleted documents: ', $result->getDeletedCount(), PHP_EOL;

Deleted documents: 1

Definir un documento de actualización

Puede utilizar métodos de fábrica de la clase constructora Stage para crear documentos de actualización. Actualiza los documentos que describen las actualizaciones a realizar en los documentos objetivo. Para obtener más información sobre cómo actualizar documentos, consulta la guía Actualizar documentos.

Los siguientes pasos describen cómo crear un documento de actualizar utilizando desarrolladores:

1. Crea una instancia de Pipeline.

2. Pase una o más etapas llamando a métodos de la clase Stage como Stage::set() y pasando nombres de campos y valores.

El siguiente código muestra la plantilla para definir una actualización mediante el uso de desarrolladores:

$update = new Pipeline(
    Stage::set(<field name>: <value>),
    Stage::set(<field name>: <value>),
    ...
);

Este ejemplo realiza las siguientes acciones:

• Utiliza el método de fábrica Query::eq() para hacer coincidir documentos en los que el valor del campo watlev es 'partly submerged at high water'

• Utiliza el método Stage::set() para establecer el campo year en 1870

• Llama al método MongoDB\Collection::updateOne() para realizar la actualización

• Imprime el número de documentos actualizados

// Creates a query filter and an update document by
// using builders and updates the first matching document
$result = $collection->updateOne(
    Query::query(watlev: Query::eq('partly submerged at high water')),
    new Pipeline(
        Stage::set(year: 1870),
    ),
);
// Prints number of updated documents
echo 'Updated documents: ', $result->getModifiedCount(), PHP_EOL;

Updated documents: 1

Modifica la salida del flujo de cambios

Puede usar métodos de fábrica de la clase Stage para modificar la salida de un flujo de cambios creando un pipeline. Para obtener más información acerca de Change Streams, consulte la Guía para monitorizar datos con Change Streams.

Los siguientes pasos describen cómo crear un filtro de flujo de cambios mediante el uso de generadores:

1. Crea un arreglo.

2. Pase una o más etapas $match llamando a los métodos de fábrica de la clase Stage y los parámetros requeridos.

El siguiente código muestra la plantilla para modificar la salida de los flujos de cambios usando constructores:

$pipeline = [
    Stage::<factory method>(...),
    Stage::<factory method>(...),
    ...
];

Puedes pasar esta pipeline a los siguientes métodos:

• MongoDB\Client::watch()

• MongoDB\Database::watch()

• MongoDB\Collection::watch()

Este ejemplo realiza las siguientes acciones:

• Utiliza el método Stage::match() para filtrar únicamente los eventos de cambio en operaciones de actualización

• Utiliza el método Stage::project() para generar solo los campos operationType, ns (espacio de nombres) y fullDocument

• Llama al método para abrir el flujo de cambios y establece MongoDB\Collection::watch() la fullDocument opción para generar el documento completo después de la actualización

• Imprime eventos de cambio a medida que ocurren

// Creates a pipeline to filter for update operations and return
// only specific fields
$pipeline = [
    Stage::match(operationType: Query::eq('update')),
    Stage::project(operationType: 1, ns: 1, fullDocument: 1),
];
// Opens the change stream
$changeStream = $collection->watch(
    $pipeline,
    ['fullDocument' => MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP],
);
// Prints change events based on the pipeline specifications
for ($changeStream->rewind(); true; $changeStream->next()) {
    if (! $changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    echo json_encode($event), PHP_EOL;
    if ($event['operationType'] === 'invalidate') {
        break;
    }
}

{
  "_id":...,
  "operationType":"update",
  "fullDocument":{"_id":...,"feature_type":"Wrecks - Visible",...},
  "ns":{"db":"sample_geospatial","coll":"shipwrecks"}
}

Para obtener más información sobre los datos proporcionados por los eventos de cambio, consulte Eventos de Cambio en el manual de MongoDB Server.