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.

Sincronização filtrada

Novidades na versão 1.1.

O Mongosync migra dados entre dois clusters MongoDB . Você pode usar a sincronização filtrada para especificar quais bancos de dados e coleções o utilitário mongosync transfere entre os clusters de origem e de destino.

A partir do 1.1, o mongosync suporta filtros de inclusão para especificar quais bancos de dados e coleções devem ser incluídos em sincronização. A partir de 1.6, mongosync também oferece suporte a filtros de exclusão e expressões regulares.

  • Com filtros de inclusão, mongosync sincroniza bancos de dados e coleções correspondentes.

  • Com filtros de exclusão, o mongosync sincroniza todos os bancos de dados e coleções, exceto aqueles que correspondem aos filtros.

  • Com os filtros de inclusão e exclusão, o mongosync sincroniza apenas bancos de dados e coleções que correspondem aos filtros de inclusão e exclui aqueles que também correspondem aos filtros de exclusão.

  • Sem filtros, o mongosync sincroniza todos os banco de dados e todas as coleções.

O endpoint da API start aceita dois campos que configuram a sincronização filtrada: includeNamespaces e excludeNamespaces. Cada campo usa um array de filtros que especifica os bancos de dados e coleções a serem incluídos ou excluídos da sincronização.

Observação

Se a chamada start usar os parâmetros includeNamespaces e excludeNamespaces, mongosync primeiro fará correspondência com os bancos de dados e as coleções dos filtros de inclusão e, em seguida, excluirá aqueles que também corresponderem a um filtro de exclusão.

Os filtros têm a seguinte sintaxe:

"includeNamespaces": [ { "database": "<database-name>", "collections": [ "<collection-name>" ] "databaseRegex": { "pattern": "<regex-pattern>", "options": "<options>" }, "collectionsRegex": { "pattern": "<regex-pattern>", "options": "<options>" } } ], "excludeNamespaces": [ { "database": "<database-name>", "collections": [ "<collection-name>" ] "databaseRegex": { "pattern": "<regex-pattern>", "options": "<options>" }, "collectionsRegex": { "pattern": "<regex-pattern>", "options": "<options>" } } ]

Para saber mais sobre a sintaxe de expressão regular pattern e options, consulte Expressões regulares em filtros.

Os filtros devem incluir o campo database ou o campo databaseRegex.

Se precisar que o filtro corresponda a coleção específicas, você pode usar a array collections para especificar coleção individualmente ou definir uma expressão regular usando o campo collectionsRegex.

Importante

Depois de iniciar o mongosync com um filtro instalado, o filtro não poderá ser modificado. Se você precisar criar um novo filtro, consulte: Reiniciar mongosync.

1

Identifique os banco de dados e as coleções que você deseja sincronizar com o cluster de destino.

  • Ao adicionar um conjunto de bancos de dados ao filtro, você também exclui quaisquer outros bancos de dados no cluster.

  • Ao especificar uma coleção em seu filtro, você também exclui quaisquer outras coleções que estejam no mesmo banco de dados.

2

A API start aceita dois parâmetros que configuram filtros opcionais:

  • O parâmetro includeNamespaces aplica uma array de filtros, que são usados para determinar bancos de dados e coleções mongosync devem ser incluídos na sincronização.

  • O parâmetro excludeNamespaces aplica uma array de filtros, que são usados para determinar quais bancos de dados e coleções mongosync devem ser excluídos da sincronização.

Se você não especificar um filtro, o mongosync executará uma sincronização completa do cluster.

Crie filtros de inclusão e/ou exclusão para identificar os bancos de dados e coleções que você deseja sincronizar.

Por exemplo, esse filtro de inclusão configuraria mongosync para sincronizar somente coleções cujos nomes comecem com accounts_ do banco de dados sales, exceto pela coleção accounts_old:

"includeNamespaces": [ { "database": "sales", "collectionsRegex": { "pattern": "^accounts_.+?$", "options": "ms" }],"excludeNamespaces": [ { "database": "sales", "collections": [ "accounts_old" ] }]

Para obter mais informações sobre filtros, consulte a página Sintaxe de filtro.

3

Para usar o filtro, anexe o filtro json ao fazer a chamada de API /start para começar a sincronização.

curl -X POST "http://localhost:27182/api/v1/start" --data ' { "source": "cluster0", "destination": "cluster1", "includeNamespaces": [ { "database": "sales", "collectionsRegex": { "pattern": "^accounts_.+$", "options": "i" } }, { "database": "marketing" } ] } '

Para obter um exemplo de configuração, consulte a página Como executar o mongosync com um filtro.

Você não pode atualizar um filtro existente. Você deve interromper o processo de sincronização em andamento, preparar o cluster de destino e reiniciar mongosync com um novo filtro. Para reiniciar mongosync, consulte Reiniciar mongosync.

Você pode, com algumas restrições, adicionar ou rename a collection durante uma sincronização filtrada.

Aviso

Se sua operação de renomeação violar as restrições de renomeação, mongosync interromperá a sincronização e reportará um erro.

Para limpar e reiniciar após um erro, siga as etapas para substituir um filtro existente.

Você poderá adicionar novas coleções ou renomear uma coleção existente se todo o banco de dados fizer parte do filtro.

Você também pode renomear uma coleção se o nome antigo e o novo nome forem especificados no filtro.

Veja os exemplos de renomeação.

Só é possível renomear uma coleção entre bancos de dados se todo o banco de dados de destino fizer parte de um filtro. Se o filtro especificar coleções individuais no banco de dados de destino, a renomeação entre bancos de dados não funcionará.

Veja os exemplos de renomeação.

Para usar o estágio de agregação $out ou o comando mapReduce (quando definido para criar ou substituir uma coleção) com filtragem, é necessário filtrar todo o banco de dados e não só a coleção especificada.

Por exemplo, considere este pipeline de agregação:

use librarydb.books.aggregate( [ { $group : { _id : "$author", titles: { $push: "$title" } } }, { $out : "authors" }] )

O estágio $out cria a coleção authors no banco de dados library. Se desejar sincronizar a coleção authors, especifique todo o banco de dados library no filtro. O filtro não funcionará se você especificar apenas a coleção authors.

Este filtro funciona:

"includeNamespaces": [ { "database": "library" }]

Este filtro não funciona:

"includeNamespaces": [ { "database": "library", "collections": [ "authors", "books" ] // DOES NOT WORK WITH $OUT }]
  • A filtragem não é compatível com a sincronização reversível.

  • O cluster de destino não deve conter dados do usuário antes de iniciar, a menos que você defina o parâmetro preExistingDestinationData como true ao chamar /start.

  • O cluster de destino não deve conter o banco de dados do sistema __mdb_internal_mongosync antes de iniciar.

  • Não é possível modificar um filtro em uso. Para criar um novo filtro, consulte Como substituir um filtro existente.

  • Só é possível renomear coleções em determinadas situações. Para obter mais detalhes, consulte a página Como adicionar e renomear coleções.

  • Se um filtro incluir um modo de exibição, mas não a coleção base, somente os metadados do modo de exibição serão sincronizados com o cluster de destino. Para incluir os documentos de visualização, você também deve sincronizar a coleção base.

  • Não é possível especificar coleções do sistema ou bancos de dados do sistema em um filtro.

  • Para utilizar o estágio de agregação $out ou o comando mapReduce (quando definido para criar ou substituir uma coleção) com filtragem, você deve configurar o filtro para utilizar o banco de dados inteiro. Você não pode limitar o filtro às coleções dentro do banco de dados.

    Para obter mais informações, consulte Filtragem com mapReduce e $out.

O exemplo a seguir inicia um tarefa de sincronização entre o cluster de origem cluster0 e o cluster de destino cluster1.

cluster0 contém o reconhecimento de data center sales, marketing e engineering.

O banco de dados sales contém as coleções EMEA, APAC e AMER.

O array includeNamespaces neste exemplo define um filtro em dois dos bancos de dados: sales e marketing.

O banco de dados sales também filtra as coleções EMEA e APAC.

"includeNamespaces" : [ { "database" : "sales", "collections": [ "EMEA", "APAC" ] }, { "database" : "marketing" } ]

Depois de chamar a API /start com este filtro em vigor, mongosync:

  • Sincroniza todas as coleções no banco de dados do marketing

  • Filtra o banco de dados engineering

  • Sincroniza as coleções EMEA e APAC a partir do banco de dados do sales

  • Filtra a coleção AMER

O exemplo a seguir inicia um tarefa de sincronização entre o cluster de origem cluster0 e o cluster de destino cluster1.

cluster0 contém o reconhecimento de data center students, staff e prospects.

  • O banco de dados students contém as coleções undergrad, graduate e adjuncts.

  • O banco de dados staff contém as coleções employees e contractors.

A array includeNamespaces deste exemplo define um filtro em dois bancos de dados:

{ "source": "cluster0", "destination": "cluster1", "includeNamespaces": [ { "database" : "students", "collections": ["undergrad", "graduate", "adjuncts"] }, { "database" : "staff" } ]}

Com este filtro em vigor, mongosync sincroniza:

  • Todo o banco de dados staff

  • As coleções undergrad, graduate e adjuncts no banco de dados students

mongosync não sincroniza nenhuma informação do banco de dados prospects .

mongosync sincroniza todo o reconhecimento de data center do staff . Se você adicionar novas collection ao reconhecimento de data center do staff , o mongosync também as sincronizará.

mongosync não sincroniza novas collection adicionadas ao reconhecimento de data center students , a menos que a collection faça parte do filtro.

Por exemplo, o mongosync não sincroniza a nova coleção se você adicionar a coleção postdocs ao banco de dados students. Se você adicionar a coleção adjuncts, o mongosync sincroniza essa coleção, pois adjuncts faz parte do filtro.

Você pode renomear qualquer coleção no banco de dados staff.

// This code works use admindb.runCommand( { renameCollection: "staff.employees", to: "staff.salaried" } )

Você só pode renomear uma collection dentro do banco de dados students se os nomes novo e antigo estiverem no filtro. Se um dos nomes não estiver no filtro, monogsync relatará um erro e sairá.

// This code works use admindb.runCommand( { renameCollection: "students.graduate", to: "students.adjuncts" } )

Se uma coleção for especificada no filtro, você poderá descartá-la, mas não poderá renomeá-la para removê-la do filtro.

// This code produces an error and mongosync stops syncing use admindb.runCommand( { renameCollection: "students.graduate", to: "students.notAFilteredCollection" } )

Quando todo o banco de dados de destino é incluído no filtro, você pode renomear coleções para adicioná-las ao filtro:

  • A coleção de origem é especificada no filtro

    use admindb.runCommand( { renameCollection: "students.adjuncts", to: "staff.adjuncts" } )
  • A coleção de origem não está especificada no filtro

    use admindb.runCommand( { renameCollection: "prospects.current", to: "staff.newHires" } )

Você também pode renomear coleção no banco de dados de origem quando todo o banco de dados de destino estiver no filtro:

use admindb.runCommand( { renameCollection: "staff.employees", to: "staff.onPayroll" } )

Importante

Se você pretende renomear as coleção, considere adicionar o banco de dados inteiro ao filtro em vez de especificar coleção individuais.