Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.
Menu Docs
Página inicial do Docs
/ /
Estágios de aggregation
Página inicial do Docs
/
Desenvolvimento
/
Linguagem de query
/
Estágios de aggregation
Página inicial do Docs
/
Desenvolvimento
/
Linguagem de query
/
Estágios de aggregation

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

Definição

Observação

Esta página descreve o estágio $merge, que gera resultados do pipeline de agregação para uma coleção. Para o operador $mergeObjects, que mescla documentos em um único documento, consulte $mergeObjects.

$merge

Grava os resultados do pipeline de agregação para uma coleção especificada. O operador $merge deve ser o último estágio do pipeline.

O estágio $merge:

  • Pode enviar para uma coleção no mesmo banco de dados ou em um banco de dados diferente.

  • Pode gerar saída para a mesma coleção que está sendo agregada. Para obter mais informações, consulte Saída para a mesma coleção que está sendo agregada.

  • Considere os seguintes pontos ao usar os $merge estágios ou em $out um agregação pipeline:

    • A partir do MongoDB 5.0, os pipelines com um estágio $merge poderão ser executados em nós secundários do conjunto de réplicas se todos os nós do cluster tiverem o featureCompatibilityVersion definido como 5.0 ou superior e a preferência de leitura permitir leituras secundárias.

      • $merge e os estágios $out são executados em nós secundários, mas as operações de gravação são enviadas para o nó primário.

      • Nem todas as versões do driver suportam operações $merge enviadas aos nós secundários. Para obter detalhes, consulte a documentação do driver.

    • nas versões anteriores do MongoDB , os pipelines com estágios $out ou $merge sempre são executados no nó principal, e a preferência de leitura não é considerada.

  • Cria uma nova coleta se a coleta de saída ainda não existir.

  • Pode incorporar resultados (inserir novos documentos, mesclar documentos, substituir documentos, manter documentos existentes, falhar a operação, processar documentos com um pipeline de atualização personalizado) a uma coleção existente.

  • Pode gerar saída para uma coleção fragmentada. A coleta de entrada também pode ser fragmentada.

Para uma comparação com o estágio, que também gera os resultados da agregação em uma $out coleção,$merge $out consulte Comparação e .

Observação

Visualizações materializadas sob demanda

$merge pode incorporar os resultados do pipeline em uma coleção de saída existente em vez de executar uma substituição completa da coleção. Essa funcionalidade permite que os usuários criem exibições materializadas sob demanda, em que o conteúdo da coleção de saída é atualizado de forma incremental quando o pipeline é executado.

Para obter mais informações sobre esse caso de uso, consulte Exibições materializadas sob demanda , bem como os exemplos nesta página.

As visualizações materializadas são separadas das exibições somente para leitura. Para obter informações sobre como criar visualizações somente para leitura, consulte exibições somente para leitura.

Compatibilidade

Você pode utilizar o $merge 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

$merge tem a seguinte sintaxe:

{ $merge: {
     into: <collection> -or- { db: <db>, coll: <collection> },
     on: <identifier field> -or- [ <identifier field1>, ...],  // Optional
     let: <variables>,                                         // Optional
     whenMatched: <replace|keepExisting|merge|fail|pipeline>,  // Optional
     whenNotMatched: <insert|discard|fail>                     // Optional
} }

Por exemplo:

{ $merge: { into: "myOutput", on: "_id", whenMatched: "replace", whenNotMatched: "insert" } }

Se utilizar todas as opções padrão para $merge, inclusive gravar em uma coleção no mesmo banco de dados, você poderá utilizar o formulário simplificado:

{ $merge: <collection> } // Output collection is in the same database

O estágio $merge recebe um documento com os seguintes campos:

Campo
Descrição

em

A coleção de saída. Especifique uma das seguintes opções:

  • O nome da coleção como uma string para saída para uma coleção no mesmo banco de dados onde a agregação é executada. Por exemplo:

    into: "myOutput"

  • O nome do banco de dados e da coleção em um documento para saída para uma coleção no banco de dados especificado. Por exemplo:

    into: { db:"myDB", coll:"myOutput" }

Se a coleção de saída não existir, o $merge criará a coleção:

  • Para um conjunto de réplicas ou um standalone, se o banco de dados de saída não existir, $merge também criará o banco de dados.

  • Para um cluster fragmentado, o banco de dados de saída especificado já deve existir.

A coleção de saída pode ser uma coleção fragmentada.

em

Opcional. Campo ou campos que atuam como um identificador exclusivo para um documento. O identificador determina se um documento de resultados corresponde a um documento existente na coleção de resultados. Especifique uma das seguintes opções:

  • Um único nome de campo como uma string. Por exemplo:

    on: "_id"

  • Uma combinação de campos em uma array. Por exemplo:

    on: [ "date", "customerId" ]

    A ordem dos campos na array não importa, e você não pode especificar o mesmo campo várias vezes.

Para o campo ou campos especificados:

  • Os documentos de resultados da agregação devem conter o(s) campo(s) especificado(s) em on, a menos que o campo on seja o campo _id. Se o campo _id estiver faltando em um documento de resultados, o MongoDB o adicionará automaticamente.

  • Para sistemas que executam o MongoDB 8.0 e versões anteriores, o campo ou os campos especificados para on não podem estar ausentes ou conter um valor nulo. A partir do MongoDB,8.1 se o índice de suporte não for esparso, o campo ou campos on especificados para podem estar ausentes ou conter um valor nulo.

  • O campo ou campos especificados não podem conter um valor de array.

$merge requer um índice único com chaves que correspondam aos campos do identificador ligado. Embora a ordem da especificação da chave do índice não seja importante, o índice único deve conter apenas os campos on como suas chaves.

  • O índice também deve ter o mesmo agrupamento que o agrupamento da agregação.

  • O índice exclusivo pode ser um índice esparso .

  • O índice único não pode ser um índice parcial.

  • Para coleções de saída que já existem, o índice correspondente já deve existir.

O valor padrão para ativado depende da coleção de saída:

  • Se a coleção de saída não existir, o identificador on deverá ser e será padronizado para o _id campo . O índice exclusivo correspondente _id é criado automaticamente.

    • Para usar um campo de identificador diferente em uma coleção que não existe, você pode criar a coleção primeiro, criando um índice exclusivo no(s) campo(s) desejado(s). Consulte a seção sobre coleção de saída inexistente para obter um exemplo.

    • A partir do MongoDB 8.3, o servidor verifica se o índice _id criado automaticamente corresponde ao agrupamento da query. Se os agrupamentos não corresponderem, o índice _id não poderá fornecer exclusividade para a query e a query não será executada.

  • Se a coleção de saída existente não estiver fragmentada, o identificador on assumirá como padrão o campo _id.

  • Se a coleção de saída existente for uma coleção fragmentada, o identificador ligado terá como padrão todos os campos de chave fragmentada e o _id campo. Se especificar um on identificador diferente, o on deverá conter todos os campos de chave de fragmento.

quando combinado

Opcional. O comportamento de $merge se um documento de resultado e um documento existente na coleção tiverem o mesmo valor para o(s) campo(s) especificado(s).

Você pode especificar:

  • Uma das strings de ação predefinidas:

    em ação
    Descrição

    "substituir"

    Substitua o documento existente na coleção de resultados pelo documento de resultados correspondente.

    Ao executar uma substituição, o documento de substituição não pode resultar em uma modificação do valor _id ou, se a coleção de saída for fragmentada, o valor da chave de estilhaço. Caso contrário, a operação gera um erro.

    Para evitar esse erro, se o campo on não incluir o _id campo, remova o _id campo nos resultados da agregação para evitar o erro, como em um $unset estágio de anterior e assim por diante.

    " Continue existindo "

    Mantenha o documento existente na coleção de resultados.

    "merge" (Padrão)

    Mesclar os documentos correspondentes (semelhante ao operador $mergeObjects).

    • Se o documento de resultados contiver campos que não estejam no documento existente, adicione esses novos campos ao documento existente.

    • Se o documento de resultados contiver campos no documento existente, substitua os valores de campo existentes pelos valores do documento de resultados.

    Por exemplo, se a coleção de saída tiver o documento:

    { _id: 1, a: 1, b: 1 }

    E os resultados da agregação tiverem o documento:

    { _id: 1, b: 5, z: 1 }

    Em seguida, o documento mesclado é:

    { _id: 1, a: 1, b: 5, z: 1 }

    Ao realizar uma mesclagem, o documento mesclado não pode resultar em uma modificação do valor _id ou, se a coleção de saída for fragmentada, do valor da chave fragmentada. Caso contrário, a operação gera um erro.

    Para evitar esse erro, se o campo on não incluir o _id campo, remova o _id campo nos resultados da agregação para evitar o erro, como em um $unset estágio de anterior e assim por diante.

    "falha"

    Pare e falhe a operação de agregação. Quaisquer alterações na coleção de saída de documentos anteriores não serão revertidas.

  • Um pipeline de agregação para atualizar o documento na coleção.

    [ <stage1>, <stage2> ... ]

    O pipeline só pode consistir nas seguintes etapas:

    O pipeline não pode modificar o valor do campo ligado. Por exemplo, se você estiver correspondendo no month campo, o pipeline não poderá modificar o month campo.

    O whenMatched pipeline pode acessar diretamente os campos dos documentos existentes na coleção de saída utilizando $<field>.

    Para acessar os campos a partir dos documentos de resultados de agregação, use:

    • A variável $$new embutida para acessar o campo. Especificamente, $$new.<field>. A variável $$new só está disponível se a especificação let for omitida.

    • As variáveis definidas pelo usuário no campo let.

      Especifique o prefixo do sinal de dólar duplo ($$) juntamente com o nome da variável no formulário $$<variable_name>. Por exemplo, $$year. Se a variável estiver definida para um documento, você também poderá incluir um campo de documento no formulário $$<variable_name>.<field>. Por exemplo, $$year.month.

      Para obter mais exemplos, consulte Usar variáveis para personalizar a fusão.

let

Opcional. Especifica variáveis para uso no pipeline whenMatched.

Especifique um documento com os nomes de variáveis e expressões de valor:

{ <variable_name_1>: <expression_1>,
  ...,
  <variable_name_n>: <expression_n> }

Se não for especificado,{ new: "$$ROOT" } ROOTo padrão será (consulte). O pipeline whenMatched pode acessar a $$new variável .

Para acessar as variáveis no pipeline whenMatched:

Especifique o prefixo do sinal de dólar duplo ($$) juntamente com o nome da variável no formulário $$<variable_name>. Por exemplo, $$year. Se a variável estiver definida para um documento, você também poderá incluir um campo de documento no formulário $$<variable_name>.<field>. Por exemplo, $$year.month.

Para obter exemplos, consulte Use Variables to Customize the Merge (Usar variáveis para personalizar a mesclagem).

quandoNotMatched

Opcional. O comportamento de $merge se um documento de resultado não corresponder a um documento existente na coleção de saída.

Você pode especificar uma das strings de ação predefinidas:

em ação
Descrição

"insert" (Padrão)

Insira o documento na coleção de saída.

"descartar"

Descarte o documento. Especificamente, o $merge não insere o documento na coleção de resultados.

"falha"

Pare e falhe a operação de agregação. Quaisquer alterações já gravadas na coleção de saída não serão revertidas.

Considerações

_id Geração de campo

Se o campo _id não estiver presente em um documento dos resultados do pipeline de agregação, o estágio $merge o gerará automaticamente.

Por exemplo, no seguinte pipeline de agregação, $project exclui o campo _id dos documentos passados para $merge. Quando $merge grava esses documentos para o "newCollection", $merge gera um novo campo _id e um novo valor.

db.movies.aggregate( [
   { $project: { _id: 0 } },
   { $merge : { into : "newCollection" } }
] )

Criar uma nova coleção se a coleta de saída não for existente

A operação $merge cria uma nova coleção se a coleção de saída especificada não existir.

  • A coleção de saída é criada quando $merge grava o primeiro documento na coleção e fica imediatamente visível.

  • Se a agregação falhar, quaisquer gravações concluídas pelo $merge antes do erro não serão revertidas.

Observação

Para um conjunto de réplicas ou um standalone, se o banco de dados de saída não existir, $merge também criará o banco de dados.

Para um cluster fragmentado, o banco de dados de saída especificado já deve existir.

Se a coleção de saída não existir, $merge exigirá que o identificador on seja o _id campo. Para usar um on valor de campo diferente para uma coleção que não existe, você pode criar a coleção primeiro criando um índice único no(s) campo(s) desejado(s) primeiro. Por exemplo, se a coleção de saída newDailyCommentCount não existir e você quiser especificar o commentDate campo como o identificador ligado:

db.newDailyCommentCount.createIndex(
   { commentDate: 1 }, { unique: true } )
db.comments.aggregate( [
   { $match: { date: { $gte: new Date("2002-01-01"),
     $lt: new Date("2002-02-01") } } },
   { $group: { _id: { $dateToString: { format: "%Y-%m-%d",
     date: "$date" } }, count: { $sum: 1 } } },
   { $project: { _id: 0, commentDate: { $toDate: "$_id" },
     count: 1 } },
   { $merge : { into : "newDailyCommentCount",
     on: "commentDate" } }
] )

Saída para uma coleção compartilhada

O estágio $merge pode gerar saída para uma coleção fragmentada. Quando a coleção de saída é fragmentada, $merge usa o campo _id e todos os campos da chave de shard com hash como identificador padrão. Se você substituir o padrão, o identificador ativado deverá incluir todos os campos de chave de fragmento :

{ $merge: {
   into: "<shardedColl>" or { db:"<sharding enabled db>", coll: "<shardedColl>" },
   on: [ "<shardkeyfield1>", "<shardkeyfield2>",... ], // Shard key fields and any additional fields
   let: <variables>,                                         // Optional
   whenMatched: <replace|keepExisting|merge|fail|pipeline>,  // Optional
   whenNotMatched: <insert|discard|fail>                     // Optional
} }

Por exemplo, utilize o método sh.shardCollection() para criar uma nova coleção fragmentada moviesByYearAndRating com o campo rated como a chave fragmentada.

sh.shardCollection(
   "sample_mflix.moviesByYearAndRating",  // Namespace of the collection to shard
   { rated: 1 },                       // Shard key
);

A moviesByYearAndRating coleção conterá documentos com estatísticas de filmes por ano (year campo) e classificação de conteúdo (chave de shard); especificamente, o identificador ligado é ["year", "rated"] (a ordem dos campos não importa). Como $merge requer um índice único com chaves que correspondam aos campos do identificador ligado, crie o índice único (a ordem dos campos não importa): []1

db.moviesByYearAndRating.createIndex(
   { rated: 1, year: 1 }, { unique: true } )

Com a coleção fragmentada moviesByYearAndRating e o índice único criado, você pode usar $merge para gerar os resultados da agregação para essa coleção, correspondendo a [ "year", "rated" ], como neste exemplo:

db.movies.aggregate( [
   { $match: { rated: { $ne: null }, year: { $ne: null } } },
   { $group: {
      _id: { year: "$year", rated: "$rated" },
      movieCount: { $sum: 1 } } },
   { $project: { _id: 0, year: "$_id.year", rated: "$_id.rated",
     movieCount: 1 } },
   { $merge: { into: "moviesByYearAndRating",
     "on": [ "year", "rated" ], whenMatched: "replace",
     whenNotMatched: "insert" } }
] )
[1]

O método sh.shardCollection() também pode criar um índice único na chave de shard com hash quando a opção { unique: true } for passada se: a chave de shard com hash for baseada em faixa, a coleção estiver vazia e um índice único na chave de shard com hash ainda não existir.

No exemplo anterior, como o identificador on é a chave de shard com hash e outro campo, é necessária uma operação separada para criar o índice correspondente.

Substituir documentos ($merge) versus Substituir coleção ($out)

$merge pode substituir um documento existente na coleção de saída se os resultados da agregação contiverem um documento ou documentos que correspondam com base na especificação. Como tal, $merge pode substituir todos os documentos na coleção existente se os resultados da agregação incluírem documentos correspondentes para todos os documentos existentes na coleção e você especificar "substituir" para whenMatched.

No entanto, para substituir uma coleção existente, independentemente dos resultados da agregação, use $out em vez disso.

Documentos existentes, _id e valores da chave de fragmento

Os erros do $merge se o $merge resultar em uma alteração no valor de _id de um documento existente.

Dica

Para evitar esse erro, se o campo on não incluir o _id campo, remova o _id campo nos resultados da agregação para evitar o erro, como em um $unset estágio de anterior e assim por diante.

Além disso, para uma coleção fragmentada, $merge também gera um erro se resultar em uma alteração no valor da chave fragmentada de um documento existente.

As gravações concluídas pelo $merge antes do erro não serão revertidas.

Restrições de índice único

Se o índice único usado por $merge para o(s) campo(s) for descartado no meio da agregação, não haverá garantias de que a agregação será eliminada. Se a agregação continuar, não haverá garantias de que os documentos não tenham on valores de campo duplicados.

Se o $merge tentar gravar um documento que viole qualquer índice exclusivo na coleção de saída, a operação gerará um erro. Por exemplo:

Validação de esquema

Se sua coleção usar validação de esquema e tiver validationAction definido como error, inserir um documento inválido ou atualizar um documento com valores inválidos com $merge gerará um MongoServerError e o documento não será gravado na coleção de destino. Se houver vários documentos inválidos, apenas o primeiro documento inválido encontrado gerará um erro. Todos os documentos válidos são gravados na coleção de destino e todos os documentos inválidos não são gravados.

whenMatched Comportamento de pipeline

$merge insere o documento diretamente na coleção de saída quando todas as seguintes condições forem verdadeiras:

  • O valor de whenMatched é um pipeline de agregação .

  • O valor de whenNotMatched inserté.

  • Não há correspondência para um documento na coleção de saída.

$merge e comparação $out

Com a introdução de $merge, o MongoDB fornece dois estágios, $merge e $out, para gravar os resultados do pipeline de agregação em uma coleção:

$merge
  • Pode enviar para uma coleção no mesmo banco de dados ou em um banco de dados diferente.
  • Pode enviar para uma coleção no mesmo banco de dados ou em um banco de dados diferente.
  • Cria uma nova coleta se a coleta de saída ainda não existir.
  • Cria uma nova coleta se a coleta de saída ainda não existir.

  • Pode incorporar resultados (inserir novos documentos, mesclar documentos, substituir documentos, manter documentos existentes, falhar a operação, processar documentos com um pipeline de atualização personalizado) a uma coleção existente.

    Consulte$merge $outtambém Substituir documentos () vs Substituir coleção ().

  • Substitui completamente a coleção de saída se ela já existir.
  • Pode gerar saída para uma coleção fragmentada. A coleta de entrada também pode ser fragmentada.
  • Não é possível gerar saída para uma coleção fragmentada. A coleção de entrada, no entanto, pode ser fragmentada.

  • Corresponde a declarações SQL:

    • MERGE.

    • INSERT INTO T2 SELECT FROM T1.

    • SELECT INTO T2 FROM T1.

    • Criar/Atualizar visualizações materializadas.

  • Corresponde à declaração SQL:

    • INSERT INTO T2 SELECT FROM T1.

    • SELECT INTO T2 FROM T1.

Saída para a mesma coleção que está sendo agregada

Aviso

Quando$mergegera saídas para a mesma coleção que está sendo agregada, os documentos podem ser atualizados várias vezes ou a operação pode resultar em um loop infinito. Esse comportamento ocorre quando a atualização realizada pelo$mergealtera a localização física dos documentos armazenados no disco. Quando a localização física de um documento muda, $mergepode considerá-lo um documento totalmente novo , resultando em atualizações adicionais. Para obter mais informações sobre esse comportamento, consulte Problema de Halloween.

$merge pode gerar saída para a mesma coleção que está sendo agregada. Você também pode gerar saída para uma coleção que aparece em outros estágios do pipeline,$lookup como.

Restrições

Restrições
Descrição

transações

Um pipeline de agregação não pode usar $merge dentro de uma transação.

Coleções de Time Series

Um pipeline de agregação não pode usar $merge para gerar uma coleção de séries temporais.

ver definição
Separar da exibição materializada

Uma definição de visualização não pode incluir o estágio $merge. Se a definição de visualização incluir pipeline aninhado (por exemplo, a definição de visualização inclui o estágio $facet), essa restrição de estágio $merge também se aplica aos pipelines aninhados.

$lookup estágio

O $lookup estágio do pipeline aninhado não pode incluir o estágio $merge.

$facet estágio

O $facet estágio do pipeline aninhado não pode incluir o estágio $merge.

$unionWith estágio

O $unionWith estágio do pipeline aninhado não pode incluir o estágio $merge.

"linearizable" Leia a preocupação

O estágio$mergenão pode ser usado em conjunto com preocupação de leitura"linearizable". Ou seja, se você especificar a preocupação de leitura"linearizable"paradb.collection.aggregate(), não poderá incluir o estágio$mergeno pipeline.

Exemplos

Voltar
$match
Próximo
$out
Avalie esta página

Nesta página