MongoDB\Collection::aggregate()

Definición

MongoDB\Collection::aggregate()

Ejecuta un Operación de canalización del marco de agregación en la colección.

function aggregate(
    array|Pipeline $pipeline,
    array $options = []
): Traversable

Parámetros

$pipeline : matriz|Pipeline

Especifica una operación de canalización de agregación. Puede incluir etapas de agregación en una MongoDB\Builder\Pipeline instancia o en una matriz.

$options : matriz

Una matriz que especifica las opciones deseadas.

Nombre	Tipo	Descripción
allowDiskUse	booleano	Permite escribir en archivos temporales. Cuando se establece en true, las etapas de agregación pueden escribir datos en el subdirectorio _tmp del directorio dbPath.
tamaño del lote	entero	Especifica el tamaño del lote del cursor, que se aplicará tanto al comando aggregate inicial como a cualquier comando getMore posterior. Esto determina el número máximo de documentos que se devolverán en cada respuesta del servidor. Un tamaño de lote de 0 es especial porque solo se aplicará al comando aggregate inicial; los comandos getMore posteriores usarán el tamaño de lote predeterminado del servidor. Esto puede ser útil para devolver rápidamente un cursor o un fallo de aggregate sin realizar un trabajo significativo en el servidor.
bypassDocumentValidation	booleano	Si es true, permite que la operación de escritura evite la validación a nivel de documento. El valor predeterminado es false. Esto solo se aplica cuando se utilizan las etapas $out y $out.
codec	MongoDB\Códec\DocumentCodec	El Codificar datos con códecs de tipo para codificar o decodificar documentos. Esta opción es mutuamente excluyente con la typeMap opción. El valor predeterminado es el códec de la colección. La herencia de la opción predeterminada codec prevalece sobre la de la opción typeMap. Nuevo en la versión 1.17.
intercalación	matriz|objeto	Laintercalación permite a los usuarios especificar reglas específicas del idioma para la comparación de cadenas, como el uso de mayúsculas y minúsculas y tildes. Al especificar la intercalación, el locale campo es obligatorio; todos los demás campos son opcionales. Para obtener descripciones de los campos, consulte el documento de intercalación. Si no se especifica la intercalación, pero la colección tiene una predeterminada, la operación utiliza la intercalación especificada para la colección. Si no se especifica ninguna intercalación para la colección ni para la operación, MongoDB utiliza la comparación binaria simple utilizada en versiones anteriores para las comparaciones de cadenas.
comment	mixto	Permite a los usuarios especificar un comentario arbitrario para ayudar a rastrear la operación a través del generador de perfiles de base de datos, la salidacurrentOp y los registros. El comentario puede ser cualquier tipo BSON válido para las versiones de servidor 4.4 y superiores. Las versiones anteriores solo admiten valores de cadena. Nuevo en la versión 1.3.
explicar	booleano	Especifica si se debe devolver o no la información sobre el procesamiento de la canalización. Nuevo en la versión 1.4.
hint	cadena|matriz|objeto	El índice a utilizar. Especifique el nombre del índice como una cadena o el patrón de clave del índice como un documento. Si se especifica, el sistema de consultas solo considerará los planes que utilicen el índice sugerido. Nuevo en la versión 1.3.
permitir	matriz|objeto	Mapa de nombres y valores de parámetros. Los valores deben ser constantes o expresiones cerradas que no hagan referencia a campos del documento. Se puede acceder a los parámetros como variables en un contexto de expresión agregada (p. ej., $$var). Esto no es compatible con versiones de servidor anteriores a 5.0 y generará una excepción en el momento de ejecución si se utiliza. Nuevo en la versión 1.9.
maxTimeMS	entero	El límite de tiempo acumulado en milisegundos para procesar operaciones en el cursor. MongoDB cancela la operación en el punto de interrupción posterior más cercano.
readConcern	MongoDB\Driver\ReadConcern	Preocupación de lectura para la operación. El valor predeterminado es la preocupación de lectura de la colección. No es posible especificar una preocupación de lectura para operaciones individuales como parte de una transacción. En su lugar, configure la readConcern opción al iniciar la transacción.
readPreference	MongoDB\Controlador\Preferencia de lectura	Preferencia de lectura para la operación. El valor predeterminado es la preferencia de lectura de la colección.
sesión	MongoDB\Controlador\Sesión	Sesión de cliente para asociar a la operación. Nuevo en la versión 1.3.
typeMap	arreglo	El mapa de tipos que se aplica a los cursores y que determina cómo se convierten los documentos BSON a valores PHP. El valor predeterminado es el mapa de tipos de la colección.
writeConcern	MongoDB\Driver\WriteConcern	Escriba la preocupación que se usará para la operación. El valor predeterminado es la preocupación de escritura de la colección. No es posible especificar una preocupación de escritura para operaciones individuales como parte de una transacción. En su lugar, configure la writeConcern opción al iniciar la transacción. Esto solo se aplica cuando se especifica una etapa $out o $merge.

Return Values

Un objeto MongoDB\Driver\Cursor o ArrayIterator. En ambos casos, el valor de retorno será Traversable.

Errores/Excepciones

MongoDB\Exception\UnexpectedValueException si la respuesta del comando del servidor era incorrecta.

MongoDB\Exception\UnsupportedException si se utilizan opciones que no son compatibles con el servidor seleccionado (porcollation readConcernwriteConcernejemplo,,,).

MongoDB\Exception\InvalidArgumentException para errores relacionados con el análisis de parámetros u opciones.

MongoDB\Driver\Exception\RuntimeException para otros errores en el nivel de extensión (por ejemplo, errores de conexión).

Comportamiento

MongoDB\Collection::aggregate()devuelve un objeto MongoDB\Driver\Cursor.

Ejemplos

El siguiente ejemplo de agregación utiliza una colección llamada names y agrupa el campo first_name, cuenta la cantidad total de resultados en cada grupo y ordena los resultados por nombre.

<?php
$collection = (new MongoDB\Client)->test->names;
$cursor = $collection->aggregate(
    [
        ['$group' => ['_id' => '$first_name', 'name_count' => ['$sum' => 1]]],
        ['$sort' => ['_id' => 1]],
    ]
);

Ver también

• Operaciones de agregación

• MongoDB\Database::aggregate()

• Referencia del comando de agregado en el manual de MongoDB

• Documentación de lacanalización de agregación en el Manual de MongoDB