$lookup (estágio de agregação )

Correspondência de igualdade com uma única condição de junção

Para realizar uma correspondência de igualdade entre um campo dos documentos de entrada e um campo dos documentos da coleção estrangeira, a etapa $lookup tem a seguinte sintaxe:

{
   $lookup:
     {
       from: <collection to join>,
       localField: <field from the input documents>,
       foreignField: <field from the documents of the "from" collection>,
       pipeline: [ <pipeline to run> ],
       as: <output array field>
     }
}

A operação corresponde a esta declaração pseudo-SQL:

SELECT *, (
   SELECT ARRAY_AGG(*)
   FROM <collection to join>
   WHERE <foreignField> = <collection.localField>
) AS <output array field>
FROM collection;

Para exemplos do MongoDB, consulte estas páginas:

• Realizar uma única junção de igualdade com $lookup

• Use $lookup com uma array

• Use $lookup com $mergeObjects

Condições de junção e subqueries em uma coleção estrangeira

MongoDB suporta:

• Executando um pipeline em uma coleção estrangeira.

• Várias condições de junções.

• Subconsultas correlacionadas e não correlacionadas.

No MongoDB, uma subquery não correlacionada significa que todo documento de entrada retornará o mesmo resultado. Uma subquery correlacionada é um pipeline em um estágio$lookup que usa os campos da collection local ou input para retornar resultados correlacionados a cada documento recebido.

As subconsultas correlacionadas do MongoDB são comparáveis às subconsultas correlacionadas do SQL, onde a consulta interna faz referência a valores de consulta externa. Uma subconsulta SQL não correlacionada não faz referência a valores de consulta externa.

O MongoDB 5.0 também suporta subqueries correlacionadas concisas.

Para executar subconsultas correlacionadas e não correlacionadas com duas coleções e executar outras condições de junção além de uma única correspondência de igualdade, use esta sintaxe $lookup:

{
   $lookup:
      {
         from: <foreign collection>,
         let: { <var_1>: <expression>, …, <var_n>: <expression> },
         pipeline: [ <pipeline to run on foreign collection> ],
         as: <output array field>
      }
}

A operação corresponde a esta declaração pseudo-SQL:

SELECT *, <output array field>
FROM collection
WHERE <output array field> IN (
   SELECT <documents as determined from the pipeline>
   FROM <collection to join>
   WHERE <pipeline>
);

Veja os seguintes exemplos:

• Use várias condições de junção e uma subquery correlacionada

• Execute uma subconsulta não correlacionada $lookup

Subconsultas correlacionadas usando sintaxe concisa

A partir do MongoDB 5.0, você pode usar uma sintaxe concisa para uma subquery correlacionada. As subqueries correlacionadas fazem referência a campos de documentos de uma coleção estrangeira e da coleção "local" na qual o método aggregate() foi executado.

A nova sintaxe concisa a seguir remove o requisito de uma correspondência de igualdade nos campos estrangeiros e local dentro de um operador $expr:

{
   $lookup:
      {
         from: <foreign collection>,
         localField: <field from local collection's documents>,
         foreignField: <field from foreign collection's documents>,
         let: { <var_1>: <expression>, …, <var_n>: <expression> },
         pipeline: [ <pipeline to run> ],
         as: <output array field>
      }
}

A operação corresponde a esta declaração pseudo-SQL:

SELECT *, <output array field>
FROM localCollection
WHERE <output array field> IN (
   SELECT <documents as determined from the pipeline>
   FROM <foreignCollection>
   WHERE <foreignCollection.foreignField> = <localCollection.localField>
   AND <pipeline match condition>
);

Veja este exemplo:

• Execute uma subconsulta concisa correlacionada com $lookup

Coleções criptografadas

A partir do MongoDB 8.1, você pode fazer referência a várias coleções criptografadas em um estágio$lookup. No entanto, $lookup não suporta:

• Usando um campo criptografado como campo de junção no localField ou foreignField.

  Observação

  Para drivers que usam a criptografia em nível de campo do lado do cliente, você pode usar um campo criptografado como um campo de junção somente se estiver executando uma operação de autoassociação.

• Usando qualquer campo em uma array criptografada. Uma array é considerada criptografada se contiver elementos criptografados.

  • Por exemplo, você não pode usar nenhum campo dentro do resultante as array da $lookup operação, a menos que esteja usando a Criptografia de Nível de Campo do Lado do Cliente e $unwind o as campo .

Visualizações e agrupamento

Se executar uma agregação que envolva múltiplas visualizações, como com $lookup ou $graphLookup, as visualizações deverão ter o mesmo agrupamento.

Restrições

Você não pode incluir os estágios $out ou $merge no estágio $lookup. Ou seja, ao especificar um pipeline para a coleção estrangeira, você não pode incluir nenhum dos estágios no campo pipeline.

{
   $lookup:
   {
      from: <collection to join>,
      let: { <var_1>: <expression>, …, <var_n>: <expression> },
      pipeline: [ <pipeline to execute on the foreign collection> ],  // Cannot include $out or $merge
      as: <output array field>
   }
}

Suporte de pesquisa do MongoDB

A partir do MongoDB 6.0, você pode especificar o estágio MongoDB Search $search ou $searchMeta no $lookup pipeline para pesquisar collections no Atlas cluster. O $search ou o $searchMeta deve ser o primeiro estágio dentro do pipeline $lookup.

Por exemplo, ao realizar Condições de junção e subqueries em uma coleção estrangeira ou executar Subqueries correlacionadas usando sintaxe concisa, você pode especificar $search ou $searchMeta dentro do pipeline, conforme mostrado abaixo:

[{
  "$lookup": {
    "from": <foreign collection>,
    localField: <field from the input documents>,
    foreignField: <field from the documents of the "from" collection>,
    "as": <output array field>,
    "pipeline": [{
      "$search": {
        "<operator>": {
          <operator-specification>
        }
      },
      ...
    }]
  }
}]

[{
  "$lookup": {
    "from": <foreign collection>,
    localField: <field from the input documents>,
    foreignField: <field from the documents of the "from" collection>,
    "as": <output array field>,
    "pipeline": [{
      "$searchMeta": {
        "<collector>": {
          <collector-specification>
        }
      },
      ...
    }]
  }
}]

Para ver um exemplo de $lookup com $search, veja o tutorial do MongoDB Search Executar uma query do MongoDB Search $search usando $lookup.

Coleções fragmentadas

A partir do MongoDB 5.1, você pode especificar coleções fragmentadas no parâmetro from de $lookup estágios.

A partir do MongoDB 8.0, você pode usar o estágio $lookup em uma transação enquanto visa uma coleção fragmentada.

Mecanismo de execução de consulta baseado em slot

A partir da versão 6.0, o MongoDB pode usar o mecanismo de execução de query baseado em slots para executar $lookup estágios se todos os estágios anteriores no pipeline também puderem ser executados pelo mecanismo de execução baseado em slots e nenhuma das seguintes condições for verdadeira:

• A operação $lookup executa um pipeline em uma coleção estrangeira. Para ver um exemplo desse tipo de operação, consulte Condições de união e subqueries em uma coleção estrangeira.

• Os localField ou foreignField de $lookup especificam componentes numéricos. Por exemplo: { localField: "restaurant.0.review" }.

• O campo from de qualquer $lookup no pipeline especifica uma visualização ou coleção fragmentada.

Para mais informações, consulte Otimização do$lookup.

Considerações de desempenho

$lookup o desempenho depende do tipo de operação executada. Consulte a tabela a seguir para considerações de desempenho para diferentes operações do $lookup.

Para obter estratégias gerais de desempenho, consulte Estratégias de indexação e Otimização de consulta.