Construtor de agregações

Documentos de amostra

Os exemplos seguintes executam pipelines de agregação em uma coleção representada pelo modelo User . Você pode adicionar os dados de amostra executando o seguinte método insert() :

User::insert([
    ['name' => 'Alda Gröndal', 'occupation' => 'engineer', 'birthday' => new UTCDateTime(new DateTimeImmutable('2002-01-01'))],
    ['name' => 'Francois Soma', 'occupation' => 'engineer', 'birthday' => new UTCDateTime(new DateTimeImmutable('1998-02-02'))],
    ['name' => 'Janet Doe', 'occupation' => 'designer', 'birthday' => new UTCDateTime(new DateTimeImmutable('1987-03-03'))],
    ['name' => 'Eliud Nkosana', 'occupation' => 'engineer', 'birthday' => new UTCDateTime(new DateTimeImmutable('1984-04-04'))],
    ['name' => 'Bran Steafan', 'occupation' => 'engineer', 'birthday' => new UTCDateTime(new DateTimeImmutable('1998-05-05'))],
    ['name' => 'Ellis Lee', 'occupation' => 'designer', 'birthday' => new UTCDateTime(new DateTimeImmutable('1996-06-06'))],
]);

Exemplo de estágio de correspondência

Você pode encadear o método match() ao seu pipeline de agregação para especificar um filtro de query. Se você omitir este estágio, o método aggregate() produzirá todos os documentos na collection do modelo para o estágio seguinte.

Esse estágio de agregação geralmente é colocado em primeiro lugar para recuperar os dados usando índices disponíveis e reduzir a quantidade de dados do processo dos estágios subsequentes.

Este exemplo constrói um filtro de query para um estágio de agregação de correspondência usando o construtor MongoDB\Builder\Query . O estágio de correspondência inclui os seguintes critérios:

• Retorna resultados que correspondem a qualquer um dos filtros de query usando a função Query::or()

• Corresponde a documentos que contêm um campo occupation com um valor de "designer" usando as funções Query::query() e Query::eq()

• Corresponde a documentos que contêm um campo name com um valor de "Eliud Nkosana" usando as funções Query::query() e Query::eq()

Clique no botão VIEW OUTPUT para ver os documentos retornados executando o código:

$pipeline = User::aggregate()
    ->match(Query::or(
        Query::query(occupation: Query::eq('designer')),
        Query::query(name: Query::eq('Eliud Nkosana')),
    ));
$result = $pipeline->get();

[
  {
    "_id": ...,
    "name": "Janet Doe",
    "occupation": "designer",
    "birthday": {
      "$date": {
        "$numberLong": "541728000000"
      }
    }
  },
  {
    "_id": ...,
    "name": "Eliud Nkosana",
    "occupation": "engineer",
    "birthday": {
      "$date": {
        "$numberLong": "449884800000"
      }
    }
  },
  {
    "_id": ...,
    "name": "Ellis Lee",
    "occupation": "designer",
    "birthday": {
      "$date": {
        "$numberLong": "834019200000"
      }
    }
  }
]

Exemplo de estágio de grupo

Você pode encadear o método group() ao seu aggregation pipeline para modificar a estrutura dos dados realizando cálculos e agrupando-os por valores de campo comuns.

Esse estágio de agregação geralmente é colocado imediatamente após um estágio de correspondência para reduzir o processo dos estágios subsequentes dos dados.

Este exemplo utiliza o construtor MongoDB\Builder\Expression para definir as chaves de grupo em um estágio de agregação de grupo . O estágio de grupo especifica o seguinte comportamento de agrupamento:

• Define o valor da chave de grupo, representada pelo campo _id , para o valor de campo definido pelo construtor Expression

• Referencia os valores do documento no campo occupation chamando a função Expression::fieldPath()

Clique no botão VIEW OUTPUT para ver os documentos retornados executando o código:

$pipeline = User::aggregate()
    ->group(_id: Expression::fieldPath('occupation'));
$result = $pipeline->get();

[
  { "_id": "engineer" },
  { "_id": "designer" }
]

Exemplo de estágio de classificação

Você pode encadear o método sort() ao aggregation pipeline para especificar a ordem de saída dos documentos.

Você pode adicionar esse estágio de agregação em qualquer lugar do pipeline. Muitas vezes, é colocado após o estágio de grupos, pois pode depender dos dados agrupados. Recomendamos colocar o estágio de classificação o mais tarde possível no pipeline para limitar os dados que ele processa.

Para especificar uma classificação, defina o valor do campo como Sort::Asc enum para uma classificação ascendente ou Sort::Desc enum para uma classificação descendente.

Este exemplo mostra um estágio de pipeline de agregação sort() que classifica os documentos pelo campo name a Sort::Desc, correspondendo à ordem alfabética inversa. Clique no botão VIEW OUTPUT para ver os documentos retornados executando o código:

$pipeline = User::aggregate()
    ->sort(name: Sort::Desc);
$result = $pipeline->get();

[
  {
    "_id": ...,
    "name": "Janet Doe",
    "occupation": "designer",
    "birthday": {
      "$date": {
        "$numberLong": "541728000000"
      }
    }
  },
  {
    "_id": ...,
    "name": "Francois Soma",
    "occupation": "engineer",
    "birthday": {
      "$date": {
        "$numberLong": "886377600000"
      }
    }
  },
  {
    "_id": ...,
    "name": "Ellis Lee",
    "occupation": "designer",
    "birthday": {
      "$date": {
        "$numberLong": "834019200000"
      }
    }
  },
  {
    "_id": ...,
    "name": "Eliud Nkosana",
    "occupation": "engineer",
    "birthday": {
      "$date": {
        "$numberLong": "449884800000"
      }
    }
  },
  {
    "_id": ...,
    "name": "Bran Steafan",
    "occupation": "engineer",
    "birthday": {
      "$date": {
        "$numberLong": "894326400000"
      }
    }
  },
  {
    "_id": ...,
    "name": "Alda Gröndal",
    "occupation": "engineer",
    "birthday": {
      "$date": {
        "$numberLong": "1009843200000"
      }
    }
  }
]

Exemplo de estágio do projeto

Você pode encadear o método project() ao seu aggregation pipeline para especificar quais campos dos documentos devem ser exibidos por esse estágio.

Para especificar campos a serem incluídos, passe o nome de um campo e um valor verdadeiro, como 1 ou true. Todos os outros campos são omitidos da saída.

Como alternativa, para especificar campos a serem excluídos, passe cada nome de campo e um valor falso, como 0 ou false. Todos os outros campos estão incluídos no resultado.

Este exemplo mostra como usar o estágio de agregação do método project() para incluir somente o campo name e excluir todos os outros campos da saída. Clique no botão VIEW OUTPUT para ver os dados retornados executando o código:

$pipeline = User::aggregate()
    ->project(_id: 0, name: 1);
$result = $pipeline->get();

[
  { "name": "Alda Gröndal" },
  { "name": "Francois Soma" },
  { "name": "Janet Doe" },
  { "name": "Eliud Nkosana" },
  { "name": "Bran Steafan" },
  { "name": "Ellis Lee" }
]

Exemplo de pipeline de agregação

Esse exemplo de pipeline de agregação encadeia vários estágios. Cada estágio é executado na saída recuperada de cada estágio anterior. Neste exemplo, os estágios executam as seguintes operações sequencialmente:

• Adicione o campo birth_year aos documentos e defina o valor para o ano extraído do campo birthday .

• Agrupe os documentos pelo valor do campo occupation e calcule o valor médio de birth_year para cada grupo usando a função Accumulator::avg() . Atribua o resultado do cálculo ao campo birth_year_avg .

• Classifique os documentos pelo campo chave de grupo em ordem crescente.

• Crie o campo profession a partir do valor do campo chave de grupo, inclua o campo birth_year_avg e omita o campo _id .

Clique no botão VIEW OUTPUT para ver os dados retornados executando o código:

$pipeline = User::aggregate()
    ->addFields(
        birth_year: Expression::year(
            Expression::dateFieldPath('birthday'),
        ),
    )
    ->group(
        _id: Expression::fieldPath('occupation'),
        birth_year_avg: Accumulator::avg(Expression::numberFieldPath('birth_year')),
    )
    ->sort(_id: Sort::Asc)
    ->project(profession: Expression::fieldPath('_id'), birth_year_avg: 1, _id: 0);

[
  {
    "birth_year_avg": 1991.5,
    "profession": "designer"
  },
  {
    "birth_year_avg": 1995.5,
    "profession": "engineer"
  }
]