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

Definição

$lookup

Alterado na versão 8.0.

Executa uma união externa esquerda em uma collection no mesmo banco de dados para filtrar documentos da collection externa para processamento. O estágio $lookup adiciona um novo campo de array a cada documento de entrada. O novo campo da matriz contém os documentos correspondentes da collection estrangeira. O estágio $lookup passa esses documentos remodelados para o próximo estágio.

A partir do MongoDB 5.1, é possível usar $lookup com coleções fragmentadas.

Para combinar elementos de duas coleções diferentes, use o estágio de pipeline $unionWith.

Importante

$lookup o desempenho, como em qualquer outro desempenho de query, depende do tipo de operação e se o campo estrangeiro está índice. Operações $lookup não indexadas ou de subquery correlacionada em coleções grandes podem reduzir o desempenho da query. Para reduzir a dependência de $lookup, considere um modelo de dados incorporado para armazenar dados relacionados em uma única coleção.

Para obter detalhes sobre o desempenho $lookup por tipo de operação, consulte Considerações sobre desempenho.

Compatibilidade

Você pode utilizar o $lookup para implantações hospedadas nos seguintes ambientes:

MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem

MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Sintaxe

A sintaxe de estágio $lookup:

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

O $lookup aceita um documento com estes campos:

Campo	necessidade	Descrição
from	Obrigatório	Especifica a coleção estrangeira no mesmo banco de dados para ingressar na coleção local. É possível, em alguns casos extremos, substituir `from` por `pipeline` com `$documents` como o primeiro estágio. Para obter um exemplo, consulte Utilizar um estágio $documents em um estágio $lookup. A partir do MongoDB 5.1, a coleção `from` pode ser fragmentada.
localField	Opcional se `pipeline` for especificado	Especifica o campo da entrada de documentos para o estágio `$lookup`. `$lookup` realiza uma correspondência de igualdade entre `localField` e `foreignField` dos documentos da coleção `from`. Se um documento de entrada não contém o `localField`, o `$lookup` trata o campo como tendo um valor de `null` para fins de correspondência.
foreignField	Opcional se `pipeline` for especificado	Especifica o `foreignField` dos documentos estrangeiros para realizar uma correspondência de igualdade com os documentos locais `localField`. Se um documento estrangeiro não contiver um valor `foreignField`, o `$lookup` usará um valor `null` para a correspondência.
let	Opcional	Especifica variáveis a serem usadas nos estágios de pipeline. Use as expressões variáveis para acessar os campos dos documentos da coleção local que são inseridos no `pipeline`. Para fazer referência a variáveis nos estágios do pipeline, use a sintaxe `"$$<variable>"`. As variáveis let podem ser acessadas pelos estágios no pipeline, incluindo estágios `$lookup` adicionais aninhados no `pipeline`. Um estágio `$match` exige o uso de um operador `$expr` para acessar as variáveis. O operador `$expr` permite o uso de expressões de agregação dentro da sintaxe `$match`. Os operadores de comparação `$eq`, `$lt`, `$lte`, `$gt` e `$gte` colocados em um operador `$expr` podem utilizar um índice na coleção `from` referenciada em um estágio `$lookup`. Limitações: Os índices só podem ser usados para comparações entre campos e constantes, portanto, o operando `let` deve ser resolvido para uma constante. Por exemplo, uma comparação entre `$a` e um valor constante pode usar um índice, mas uma comparação entre `$a` e `$b` não pode. Os índices não são usados para comparações onde o operando `let` resolve para um valor vazio ou ausente. Índices multichave, parciais ou esparsos não são usados. Outros estágios (não`$match`) no pipeline não exigem um operador `$expr` para acessar as variáveis.
gasoduto	Opcional se `localField` e `foreignField` forem especificados	Especifica o `pipeline` a ser executado na coleção estrangeira. O `pipeline` retorna documentos da coleção estrangeira. Para retornar todos os documentos, especifique um campo `pipeline: []` vazio. O `pipeline` não pode incluir os estágios `$out` ou `$merge` . A partir dev6.0, o `pipeline` pode conter o estágio Atlas Search `$search` como o primeiro estágio dentro do pipeline. Para saber mais, consulte Compatibilidade do Atlas Search. O `pipeline` não pode acessar campos de documentos de entrada. Como alternativa, defina variáveis para os campos do documento usando a opção let e, em seguida, faça referência às variáveis nos estágios `pipeline`. Para fazer referência a variáveis nos estágios do pipeline, use a sintaxe `"$$<variable>"`. As variáveis let podem ser acessadas pelos estágios no pipeline, incluindo estágios `$lookup` adicionais aninhados no `pipeline`. Um estágio `$match` exige o uso de um operador `$expr` para acessar as variáveis. O operador `$expr` permite o uso de expressões de agregação dentro da sintaxe `$match`. Os operadores de comparação `$eq`, `$lt`, `$lte`, `$gt` e `$gte` colocados em um operador `$expr` podem utilizar um índice na coleção `from` referenciada em um estágio `$lookup`. Limitações: Os índices só podem ser usados para comparações entre campos e constantes, portanto, o operando `let` deve ser resolvido para uma constante. Por exemplo, uma comparação entre `$a` e um valor constante pode usar um índice, mas uma comparação entre `$a` e `$b` não pode. Os índices não são usados para comparações onde o operando `let` resolve para um valor vazio ou ausente. Índices multichave, parciais ou esparsos não são usados. Outros estágios (não`$match`) no pipeline não exigem um operador `$expr` para acessar as variáveis.
como	Obrigatório	Especifica o nome do novo campo de array a ser adicionado aos documentos de entrada. O novo campo de array contém os documentos correspondentes da coleção `from`. Se o nome especificado já existir no documento de entrada, o campo existente será substituído.

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>     }}

Observação

Neste exemplo, pipeline é opcional e executado após o estágio de igualdade local e externa.

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;

Observação

As declarações SQL nesta página estão incluídas para comparação com a sintaxe do pipeline de agregação do MongoDB. As declarações SQL não são executáveis.

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 cada documento de entrada retorna o mesmo resultado. Uma subquery correlacionada é um pipeline em um estágio $lookup que usa os campos da coleção local ou input para retornar resultados correlacionados a cada documento recebido.

Observação

A partir do MongoDB 5.0, para uma sub-query não correlacionada em um estágio de pipeline $lookup que contém um estágio $sample, o operador $sampleRate ou o operador $rand, a sub-query é sempre executada novamente se for repetida. Anteriormente, dependendo do tamanho da saída da sub-query, o resultado da sub-query era armazenado em cache ou a sub-query era executada novamente.

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 collectionWHERE <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

Novidade na versão 5.0.

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 localCollectionWHERE <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

Comportamento

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 do Atlas Search

A partir do MongoDB 6.0, você pode especificar o $search do Atlas Search ou o estágio do $searchMeta no pipeline de $lookup para pesquisar coleções no cluster do Atlas. O estágio $search ou $searchMeta deve ser o primeiro 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, consulte o tutorial Executar uma query $search do Atlas Search usando $lookup, do Atlas Search.

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.

`$lookup` (operação)	Considerações de desempenho
Correspondência de igualdade com uma única junção	`$lookup` As operações que executam correspondências de igualdade com uma única união executam melhor quando a coleção externa contém um índice no `foreignField`. IMPORTANTE: se não houver um índice de suporte no `foreignField`, a operação `$lookup` que executa uma correspondência de igualdade com uma única ligação provavelmente terá um desempenho ruim.
Subconsultas não correlacionadas	`$lookup` operações que contêm subqueries não correlacionadas têm um desempenho melhor se o pipeline interno conseguir referenciar um índice da coleção externa. O MongoDB só precisa executar a subconsulta `$lookup` uma vez antes de armazenar a consulta em cache porque não há relacionamento entre a origem e as coleções externas. A subconsulta não é baseada em nenhum valor na coleção de origem. Este comportamento melhora o desempenho para execuções subsequentes da operação `$lookup`.
Subconsultas correlacionadas	`$lookup` operações que contêm subqueries correlacionadas têm um desempenho melhor quando a coleção estrangeira contém um índice no `foreignField`. Se o pipeline passar um grande número de documentos para a consulta `$lookup`, as estratégias a seguir poderão melhorar o desempenho: Reduz o número de documentos que o MongoDB passa para a consulta do `$lookup`. Por exemplo, defina um filtro mais rigoroso durante o estágio `$match`. Reconsidere o esquema dos dados para garantir que seja ideal para o caso de uso.

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

Exemplos

Os exemplos nesta página usam dados do conjunto de dados sample_mflix. Para obter detalhes sobre como carregar este conjunto de dados em sua implantação do MongoDB autogerenciado, consulte Carregar o conjunto de dados de amostra. Se você fez alguma modificação nos bancos de dados de amostra, talvez seja necessário descartar e recriar os bancos de dados para executar os exemplos nesta página.

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

A operação de agregação a seguir primeiro filtra a coleção movies para filmes com runtime maior que 1000 e, em seguida, une-se à coleção comments nos campos _id e movie_id:

db.movies.aggregate( [   { $match: { runtime: { $gt: 1000 } } },   {      $lookup: {         from: "comments",         localField: "_id",         foreignField: "movie_id",         as: "movie_comments"      }   },   {      $project: {         _id: 0,         title: 1,         year: 1,         "movie_comments.name": 1,         "movie_comments.text": 1,         "movie_comments.date": 1      }   }] )

[  {    title: 'Centennial',    year: 1978,    movie_comments: [      {        name: 'Ellaria Sand',        text: 'Excepturi nam nam eum possimus aspernatur autem. Quis nulla optio praesentium ut distinctio explicabo.',        date: ISODate('1995-08-18T03:01:50.000Z')      }    ]  },  { title: 'Baseball', year: 1994, movie_comments: [] }]

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

SELECT *, movie_commentsFROM moviesWHERE movie_comments IN (   SELECT *   FROM comments   WHERE movie_id = movies._id);

Para obter mais informações, consulte Considerações sobre o desempenho da correspondência de igualdade.

Use `$lookup` com uma array

Se localField for uma array, você poderá fazer a correspondência dos elementos de array com um escalar foreignField sem um estágio $unwind.

A seguinte operação de agregação une a coleção movies à coleção users, fazendo a correspondência do campo de array cast de movies com o campo escalar name de users:

db.movies.aggregate( [   {      $match: {         title: {            $in: [ "Roger & Me", "The Sum of Us",               "Centennial" ]         }      }   },   {      $lookup: {         from: "users",         localField: "cast",         foreignField: "name",         as: "cast_users"      }   },   {      $project: {         _id: 0,         title: 1,         year: 1,         cast: 1,         "cast_users.name": 1,         "cast_users.email": 1      }   },   { $sort: { year: 1 } }] )

[  {    cast: [      'Raymond Burr',      'Barbara Carrera',      'Richard Chamberlain',      'Robert Conrad'    ],    title: 'Centennial',    year: 1978,    cast_users: []  },  {    cast: [      'Michael Moore',      'Roger B. Smith',      'Rhonda Britton',      'Fred Ross'    ],    title: 'Roger & Me',    year: 1989,    cast_users: [ { name: 'Michael Moore', email: 'michael_moore@fakegmail.com' } ]  },  {    cast: [      'Jack Thompson',      'Russell Crowe',      'John Polson',      'Deborah Kennedy'    ],    title: 'The Sum of Us',    year: 1994,    cast_users: [      {        name: 'Deborah Kennedy',        email: 'deborah_kennedy@fakegmail.com'      }    ]  }]

Usar `$lookup` com `$mergeObjects`

O operador $mergeObjects combina vários documentos em um único documento.

A operação a seguir usa $lookup para unir a coleção movies com a coleção comments e, em seguida, usa $mergeObjects em $replaceRoot para mesclar o primeiro document de comentário com o document de filme :

db.movies.aggregate( [   { $match: { runtime: { $gt: 1000 } } },   {      $lookup: {         from: "comments",         localField: "_id",         foreignField: "movie_id",         as: "movie_comments"      }   },   {      $replaceRoot: {         newRoot: {            $mergeObjects: [               { $arrayElemAt: [ "$movie_comments", 0 ] },               "$$ROOT"            ]         }      }   },   {      $project: {         _id: 0,         title: 1,         year: 1,         genres: 1,         name: 1,         email: 1,         text: 1,         date: 1      }   }] )

[  {    name: 'Ellaria Sand',    email: 'indira_varma@gameofthron.es',    text: 'Excepturi nam nam eum possimus aspernatur autem. Quis nulla optio praesentium ut distinctio explicabo.',    date: ISODate('1995-08-18T03:01:50.000Z'),    genres: [ 'Action', 'Adventure', 'Drama' ],    title: 'Centennial',    year: 1978  },  {    genres: [ 'Documentary', 'History', 'Sport' ],    title: 'Baseball',    year: 1994  }]

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

Os pipelines podem ser executados em uma coleção estrangeira e incluir diversas condições de junção. O operador $expr permite condições de junção mais complexas, incluindo conjunções e correspondências de não igualdade.

Uma condição de junção pode fazer referência a um campo na coleção local na qual o método aggregate() foi executado e fazer referência a um campo na coleção estrangeira. Isso permite uma subquery correlacionada entre as duas coleções.

O MongoDB 5.0 é compatível com subconsultas correlacionadas concisas.

O seguinte exemplo:

Une as coleções movies e comments usando os campos _id e movie_id.
Filtra os comentários para incluir apenas os postados após o ano de lançamento do filme.

db.movies.aggregate( [   {      $match: {         title: {            $in: [ "Class Action", "Kafka", "Corpse Bride" ]         }      }   },   {      $lookup: {         from: "comments",         localField: "_id",         foreignField: "movie_id",         let: { movie_year: "$year" },         pipeline: [            {               $match: {                  $expr: {                     $gt: [                        { $year: "$date" }, "$$movie_year"                     ]                  }               }            },            { $project: { _id: 0, name: 1, date: 1 } }         ],         as: "post_release_comments"      }   },   {      $project: {         _id: 0,         title: 1,         year: 1,         post_release_comments: 1      }   }] )

[  {    year: 1991,    title: 'Class Action',    post_release_comments: [      { name: 'Khal Drogo', date: ISODate('2016-12-06T07:17:03.000Z') }    ]  },  {    year: 1991,    title: 'Kafka',    post_release_comments: [      { name: 'Khal Drogo', date: ISODate('1998-05-10T03:10:20.000Z') }    ]  },  { year: 2005, title: 'Corpse Bride', post_release_comments: [] }]

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

SELECT *, post_release_commentsFROM moviesWHERE post_release_comments IN (   SELECT name, date   FROM comments   WHERE movie_id = movies._id   AND YEAR(date) > movies.year);

Os operadores de comparação $eq, $lt, $lte, $gt e $gte colocados em um operador $expr podem utilizar um índice na coleção from referenciada em um estágio $lookup. Limitações:

Os índices só podem ser usados para comparações entre campos e constantes, portanto, o operando let deve ser resolvido para uma constante.

Por exemplo, uma comparação entre $a e um valor constante pode usar um índice, mas uma comparação entre $a e $b não pode.
Os índices não são usados para comparações onde o operando let resolve para um valor vazio ou ausente.
Índices multichave, parciais ou esparsos não são usados.

Por exemplo, se o índice { movie_id: 1 } existir na coleção comments:

A correspondência de igualdade no campo comments.movie_id utiliza o índice.

Dica

Execute uma subconsulta não correlacionada `$lookup`

Um estágio $lookup do pipeline de agregação pode executar um pipeline na coleção estrangeira, o que permite subqueries não correlacionadas. Uma subquery não correlacionada não faz referência aos campos do documento local.

Observação

A operação a seguir une a coleção users a filmes que têm um tempo de execução maior que 1000 minutos da coleção movies:

db.users.aggregate( [   {      $match: {         email: { $in: [            "mark_addy@gameofthron.es",            "lena_headey@gameofthron.es"         ] }      }   },   {      $lookup: {         from: "movies",         pipeline: [            { $match: { runtime: { $gt: 1000 } } },            { $project: { _id: 0, title: 1, year: 1 } }         ],         as: "long_movies"      }   },   {      $project: {         _id: 0, name: 1, email: 1, long_movies: 1      }   }] )

[  {    name: 'Robert Baratheon',    email: 'mark_addy@gameofthron.es',    long_movies: [      { title: 'Centennial', year: 1978 },      { title: 'Baseball', year: 1994 }    ]  },  {    name: 'Cersei Lannister',    email: 'lena_headey@gameofthron.es',    long_movies: [      { title: 'Centennial', year: 1978 },      { title: 'Baseball', year: 1994 }    ]  }]

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

SELECT *, long_moviesFROM usersWHERE long_movies IN (   SELECT title, year   FROM movies   WHERE runtime > 1000);

Para obter mais informações, consulte Considerações sobre desempenho de subconsultas não correlacionadas.

Execute uma subconsulta concisa correlacionada com `$lookup`

Novidade na versão 5.0.

A partir do MongoDB 5.0, um estágio $lookup do pipeline de agregação suporta uma sintaxe de sub-query correlacionada concisa que melhora as uniões entre coleções. A nova sintaxe concisa remove a exigência de uma correspondência de igualdade nos campos externo e local dentro de um operador $expr em um estágio $match.

O seguinte exemplo:

Une as coleções movies e comments combinando o localField _id com o foreignField movie_id. A correspondência é executada antes de pipeline ser executado.
Filtra os comentários para incluir apenas os postados após o ano de lançamento do filme, acessado usando $$movie_year e $date, respectivamente.

db.movies.aggregate( [   {      $match: {         title: { $in: [            "I Don't Kiss",            "Lucky Luke",            "Mississippi Masala"         ] }      }   },   {      $lookup: {         from: "comments",         localField: "_id",         foreignField: "movie_id",         let: { movie_year: "$year" },         pipeline: [            {               $match: {                  $expr: {                     $gt: [                        { $year: "$date" }, "$$movie_year"                     ]                  }               }            },            { $project: { _id: 0, name: 1, date: 1 } }         ],         as: "post_release_comments"      }   },   {      $project: {         _id: 0,         title: 1,         year: 1,         post_release_comments: 1      }   }] )

[  {    title: "I Don't Kiss",    year: 1991,    post_release_comments: [      {        name: 'Brandon Hardy',        date: ISODate('2016-09-18T11:11:34.000Z')      }    ]  },  {    title: 'Lucky Luke',    year: 1991,    post_release_comments: [      {        name: 'Kelsey Smith',        date: ISODate('2010-01-13T17:55:01.000Z')      }    ]  },  {    title: 'Mississippi Masala',    year: 1991,    post_release_comments: [      {        name: 'Phillip Collins',        date: ISODate('2010-05-13T08:04:22.000Z')      }    ]  }]

Este exemplo usa a sintaxe detalhada mais antiga das versões do MongoDB anteriores à 5.0 e retorna os mesmos resultados do exemplo conciso anterior:

db.movies.aggregate( [   {      $match: {         title: { $in: [            "I Don't Kiss",            "Lucky Luke",            "Mississippi Masala"         ] }      }   },   {      $lookup: {         from: "comments",         let: { movie_id: "$_id", movie_year: "$year" },         pipeline: [            {               $match: {                  $expr: {                     $and: [                        { $eq: [ "$movie_id", "$$movie_id" ] },                        { $gt: [                           { $year: "$date" }, "$$movie_year"                        ] }                     ]                  }               }            },            { $project: { _id: 0, name: 1, date: 1 } }         ],         as: "post_release_comments"      }   },   {      $project: {         _id: 0,         title: 1,         year: 1,         post_release_comments: 1      }   }] )

[  {    title: "I Don't Kiss",    year: 1991,    post_release_comments: [      {        name: 'Brandon Hardy',        date: ISODate('2016-09-18T11:11:34.000Z')      }    ]  },  {    title: 'Lucky Luke',    year: 1991,    post_release_comments: [      {        name: 'Kelsey Smith',        date: ISODate('2010-01-13T17:55:01.000Z')      }    ]  },  {    title: 'Mississippi Masala',    year: 1991,    post_release_comments: [      {        name: 'Phillip Collins',        date: ISODate('2010-05-13T08:04:22.000Z')      }    ]  }]

Os exemplos anteriores correspondem a esta declaração pseudo-SQL:

SELECT *, post_release_commentsFROM moviesWHERE post_release_comments IN (   SELECT *   FROM comments   WHERE comments.movie_id = movies._id   AND YEAR(comments.date) > movies.year);

Para mais informações, consulte Considerações sobre o desempenho de subconsultas correlacionadas.

Namespaces em Subpipelines

A partir do MongoDB 8.0, os namespaces em subpipelines dentro $lookup e $unionWith são validados para garantir o uso correto dos campos from e coll:

Por $lookup, omita o campo from se você usar um subpipeline com um estágio que não exija uma coleção especificada. Por exemplo, um estágio $documents.
Da mesma forma, para $unionWith, omita o campo coll.

Comportamento inalterado:

Para um $lookup que começa com um estágio para uma coleção, por exemplo, um subpipeline $match ou $collStats, você deve incluir o campo from e especificar a coleção.
Da mesma forma, para $unionWith, inclua o campo coll e especifique a coleção.

Os exemplos de C# nesta página utilizam o banco de dados sample_mflix a partir dos conjuntos de dados de amostra do Atlas. Para saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de exemplo, consulte Introdução na documentação do driver MongoDB .NET/C#.

A seguinte classe Movie modela os documentos na collection sample_mflix.movies:

[BsonIgnoreExtraElements]public class Movie{    [BsonId]    public ObjectId Id { get; set; }    [BsonElement("title")]    public string Title { get; set; } = null!;    [BsonElement("year")]    public int? Year { get; set; }    [BsonElement("runtime")]    public int? Runtime { get; set; }    [BsonElement("rated")]    public string? Rated { get; set; }    [BsonElement("metacritic")]    public int Metacritic { get; set; }    [BsonElement("plot")]    public string? Plot { get; set; }    [BsonElement("type")]    public string? Type { get; set; }    [BsonElement("cast")]    public string[]? Cast { get; set; }    [BsonElement("directors")]    public string[]? Directors { get; set; }    [BsonElement("writers")]    public string[]? Writers { get; set; }    [BsonElement("imdb")]    public ImdbData? Imdb { get; set; }}

A seguinte classe Comment modela os documentos na collection sample_mflix.comments:

[BsonIgnoreExtraElements]public class Comment{    [BsonId]    public ObjectId Id { get; set; }
    [BsonElement("movie_id")]    public ObjectId MovieId { get; set; }
    [BsonElement("text")]    public string Text { get; set; } = null!;}

A seguinte classe LookupResult armazena a saída do estágio $lookup:

[BsonIgnoreExtraElements]public class LookupResult{    [BsonId]    public ObjectId Id { get; set; }
    [BsonElement("title")]    public string Title { get; set; } = null!;
    public List<Comment> Comments { get; set; } = [];}

Para usar o driver MongoDB .NET/C# para adicionar um estágio $lookup a uma agregação pipeline, chame o método UnionWith() em um objeto PipelineDefinition.

O exemplo abaixo cria um estágio de pipeline que executa uma junção externa esquerda entre as collections movies e comments. O código une o campo Id de cada documento Movie ao campo MovieId nos documentos Comment. Os comentários de cada filme são armazenados em um campo chamado Comments em cada documento LookupResult .

var commentCollection = _client    .GetDatabase("sample_mflix")    .GetCollection<Comment>("comments");
var pipeline = new EmptyPipelineDefinition<Movie>()    .Lookup<Movie, Movie, Comment, LookupResult>(        foreignCollection: commentCollection,        localField: m => m.Id,        foreignField: c => c.MovieId,        @as: r => r.Comments);

{  "_id" : ObjectId("..."),  "title" : "A Corner in Wheat",  "Comments" : [    {      "_id" : ObjectId("..."),      "movie_id" : ObjectId("..."),      "text" : "..."    },    "..."  ]}

Os exemplos do Node.js nesta página utilizam o banco de dados do sample_mflix a partir dos conjuntos de dados de amostra do Atlas. Para saber como criar um cluster gratuito do MongoDB Atlas e carregar os conjuntos de dados de exemplo, consulte Introdução na documentação do driver do MongoDB Node.js

Para usar o driver Node.js do MongoDB para adicionar um estágio $lookup a um pipeline de agregação , use o operador $lookup em um objeto de pipeline.

O exemplo a seguir cria um estágio de pipeline que executa uma junção externa esquerda entre as coleções movies e comments. O código conecta o campo _id de cada documento movie ao campo movie_id nos documentos comment. O campo comments armazena os comentários de cada filme em cada documento movie. O exemplo em seguida executa o pipeline de agregação:

const pipeline = [  {    $lookup: {      from: "comments",      localField: "_id",      foreignField: "movie_id",      as: "comments"    }  }];
const cursor = collection.aggregate(pipeline);return cursor;

Voltar

$listSessions

$match

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

Definição

Compatibilidade

Sintaxe

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

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

Subconsultas correlacionadas usando sintaxe concisa

Comportamento

Visualizações e agrupamento

Restrições

Suporte do Atlas Search

Coleções fragmentadas

Mecanismo de execução de consulta baseado em slot

Considerações de desempenho

Exemplos

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

Use $lookup com uma array

Usar $lookup com $mergeObjects

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

Execute uma subconsulta não correlacionada $lookup

Execute uma subconsulta concisa correlacionada com $lookup

Namespaces em Subpipelines

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

Use `$lookup` com uma array

Usar `$lookup` com `$mergeObjects`

Execute uma subconsulta não correlacionada `$lookup`

Execute uma subconsulta concisa correlacionada com `$lookup`