MongoDB\Collection::aggregate()

Definição

MongoDB\Collection::aggregate()

Executa uma operação de pipeline de framework de agregação na coleção.

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

Parâmetros

$pipeline : array

Especifica uma operação de pipeline de agregação.

$options : array

Uma array especificando as opções desejadas.

Nome	Tipo	Descrição
allowDiskUse	booleano	Permite escrever em arquivos temporários. Ao definir como true, os estágios de aggregation podem escrever dados no subdiretório _tmp do diretório dbPath.
batchSize	inteiro	Especifica o tamanho do lote para o cursor, que se aplicará ao comando aggregate inicial e quaisquer comandos getMore subsequentes. Isso determina o número máximo de documentos para retornar em cada resposta do servidor. Um batchSize de 0 é especial para isso e só se aplica ao comando aggregate inicial; os comandos getMore subsequentes usam o tamanho de lote padrão do servidor. Isso pode ser útil para retornar rapidamente um cursor ou uma falha do aggregate sem fazer um trabalho significativo do lado do servidor.
bypassDocumentValidation	booleano	Se true, permite que a operação de gravação contorne a validação do nível do documento. O padrão é false. Isso só se aplica ao usar os estágios $out e $out.
Codec	MongoDB\Codec\DocumentCodec	Ocodec a ser usado para codificar ou decodificar documentos. Esta opção é mutuamente exclusiva com a opção typeMap . O padrão é o codec da coleção. A herança de uma opção codec padrão tem precedência sobre a da opção typeMap. Novidade na versão 1.17.
agrupamento	array|object	A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de string , como regras para letras maiúsculas e marcas de acento. Ao especificar agrupamento, o campo locale é obrigatório; todos os outros campos de agrupamento são opcionais. Para obter descrições dos campos, consulte Documento de agrupamento. Se o agrupamento não for especificado, mas a coleção tiver um agrupamento padrão, a operação usará o agrupamento especificado para a coleção. Se nenhum agrupamento for especificado para a coleção nem para a operação, o MongoDB usará a comparação binária simples usada nas versões anteriores para comparações de strings.
comment	misto	Permite ao usuário especificar um comentário arbitrário para ajudar a rastrear a operação por meio do profiler de banco de dados, da saída currentOp e dos registros. O comentário pode ser qualquer tipo de BSON válido para as versões 4.4 e superiores do servidor. As versões anteriores do servidor suportam apenas valores de string. Novidade na versão 1.3.
explicar	booleano	Especifica se deseja ou não retornar as informações sobre o processamento do pipeline. Novidade na versão 1.4.
dica	string|array|objeto	O índice a ser utilizado. Especifique o nome do índice como uma string ou o padrão da chave do índice como um documento. Se especificado, o sistema de query considerará apenas os planos usando o índice sugerido. Novidade na versão 1.3.
let	array|object	Mapa de nomes e valores de parâmetros. Os valores devem ser expressões constantes ou fechadas que não façam referência aos campos do documento. Os parâmetros podem ser acessados como variáveis em um contexto de expressão agregada (como $$var). Isto não é suportado para versões de servidor anteriores à 5.0 e resultará em uma exceção no tempo de execução se utilizado. Novidades na versão 1.9.
maxTimeMS	inteiro	O limite de tempo cumulativo em milésimos de segundo para operações de processamento no cursor. O MongoDB aborta a operação o mais cedo possível após o ponto de interrupção.
readConcern	MongoDB\Driver\ReadConcern	Preocupação de leitura a ser usada para a operação. O padrão é a preocupação de leitura da coleção. Não é possível especificar uma preocupação de leitura para operações individuais como parte de uma transação. Em vez disso, defina a opção readConcern ao iniciar a transação.
readPreference	MongoDB\Driver\ReadPreference	Preferência de leitura a ser usada na operação. O padrão é a preferência de leitura da coleção.
session	MongoDB\Driver\Session	Sessão do cliente a ser associada à operação. Novidade na versão 1.3.
typeMap	array	O mapa de tipos para aplicar aos cursores, que determina como os documentos BSON são convertidos para valores PHP. O padrão é o mapa de tipos da coleção.
writeConcern	MongoDB\Driver\WriteConcern	Preocupação de gravação a ser usada na operação. O padrão é a preocupação de gravação da coleção. Não é possível especificar uma preocupação de gravação para operações individuais como parte de uma transação. Em vez disso, defina a opção writeConcern ao iniciar a transação. Isto só se aplica quando um estágio $out ou $merge é especificado.

Return Values

Um MongoDB\Driver\Cursor ou ArrayIterator evento. Em ambos os casos, o valor de retorno será Traversable.

Erros/exceções

MongoDB\Exception\UnexpectedValueException se a resposta do comando do servidor estiver malformada.

MongoDB\Exception\UnsupportedException se as opções forem usadas e não aceitas pelo servidor selecionado (p. ex., collation, readConcern, writeConcern).

MongoDB\Exception\InvalidArgumentException para erros relacionados à análise de parâmetros ou opções.

MongoDB\Driver\Exception\RuntimeException para outros erros no nível da extensão (por exemplo erros de conexão).

Comportamento

MongoDB\Collection::aggregate()retorna um MongoDB\Driver\Cursor objeto.

Exemplos

O exemplo de aggregation seguinte utiliza uma collection denominada names e agrupa o campo first_name, conta o número total de resultados em cada grupo e classifica os resultados por nome.

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

Veja também

• MongoDB\Database::aggregate()

• referência do comando aggregate no manual do MongoDB

• Documentação do aggregation pipeline no Manual do MongoDB