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 SecciónGenerador de agregaciones de la guía de agregación.

Usar constructores para crear consultas 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 constructores que puede 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;

Clases del generador de importaciones

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

Puede usar los métodos de fábrica de la Query clase constructora para crear definiciones de filtros que se usarán en operaciones de búsqueda, actualización y eliminación. Al usar el Query::query() método de fábrica para crear consultas, puede usar la sintaxis de argumentos con nombre e implementar la seguridad de tipos. Para obtener más información sobre la creación de filtros, consulte la guía "Especificar una consulta".

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. Pase el nombre del campo por el que se filtrará y un método de fábrica de la clase Query. Puede pasar uno o más pares de nombres de campo y criterios en el filtro para aplicar varias cláusulas.

El siguiente código muestra la plantilla para crear una definición de filtro mediante el uso de constructores:

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

Para combinar criterios de consulta mediante operadores de consulta lógicos ($and, $or, $not, $nor), puede utilizar la siguiente plantilla de consulta:

$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 usar métodos de fábrica de la Stage clase de compilación para crear documentos de actualización. Estos documentos describen las actualizaciones que se deben realizar en los documentos de destino. Para obtener más información sobre la actualización de documentos, consulte la guía "Actualizar documentos".

Los siguientes pasos describen cómo crear un documento de actualización mediante generadores:

1. Crea una instancia 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 constructores:

$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 para realizar la MongoDB\Collection::updateOne() 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

Puedes usar métodos de fábrica de la Stage clase para modificar la salida de un flujo de cambios mediante la creación de una canalización. Para obtener más información sobre los flujos de cambios, consulta la guía "Monitorizar datos con flujos de cambios".

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

1. Crear una matriz.

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 del flujo de cambios mediante el uso de constructores:

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

Puede pasar esta canalización 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 solo eventos de cambio para 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

• Las impresiones cambian los eventos 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 la información proporcionada por los eventos de cambio, consulte Eventos de cambio en el manual de MongoDB Server.