MongoDB

Coleta MONGODB e Entrega MONGODB_WRITE.

Uma única Conexão Externa atende quatro serviços: MongoDB instalado pelo cliente, MongoDB Atlas, Azure Cosmos DB (API Mongo) e AWS DocumentDB. Não são protocolos diferentes — é o mesmo driver e a mesma conversa de rede; o que muda são padrões e validações, e é isso que o campo Serviço carrega.

Serviço	O que ele muda na conexão
MongoDB (próprio/on-premise)	Sem restrição. É o único em que o campo Replica set se aplica
MongoDB Atlas	Exige URI `mongodb+srv://` e TLS. Falha de rede vira uma dica sobre a IP Access List do projeto
Azure Cosmos DB (API Mongo)	TLS obrigatório e retryable writes desligado — o serviço não implementa o recurso
AWS DocumentDB	TLS obrigatório, retryable writes desligado, e o certificado da CA da Amazon no campo de certificado

Conexão

Campo	Para que serve
Serviço	Define os padrões acima. Escolher errado costuma aparecer como recusa no handshake, sem explicação
URI de conexão	Só o endereço: `mongodb://mongo:27017` ou `mongodb+srv://cluster0.abcde.mongodb.net`. Sem usuário e senha
Database	Database padrão da conexão
Coleção de teste	Opcional. Preenchida, o Keep Alive também prova que a coleção responde à leitura
Usuário / Senha	Credencial de acesso. A senha é cifrada em repouso e nunca volta para a tela
Database de autenticação	O `authSource` — onde o usuário foi criado. `admin` na maioria das instalações
Replica set	Só no serviço próprio, quando a conexão é feita direto nos nós
Timeout (ms)	Vale para os três tetos do driver: seleção de nó, conexão e operação
Conectar com TLS	Nos serviços gerenciados já vai ligado, porque neles TLS é obrigatório
Validar certificado TLS / Certificado da CA	Mesma semântica das demais conexões. A CA é necessária com certificado de CA interna — e no DocumentDB, que exige o certificado da Amazon
Reenviar escrita após falha de rede	retryable writes. Só no serviço próprio: Cosmos DB e DocumentDB não suportam, e a conexão é feita com o recurso desligado

A URI não aceita credencial embutida (mongodb://usuario:senha@host). A URI aparece na listagem da tela de Conexões Externas e nos arquivos de exportação de configuração — uma senha ali vazaria nos dois lugares. O CMS recusa a URI e pede a credencial nos campos próprios, onde ela é cifrada.

Como a credencial vai fora da URI, senha com @, : ou / funciona sem escape. É o oposto do que acontece nas ferramentas que exigem a string de conexão inteira, onde esse detalhe costuma ser a causa de um “authentication failed” que ninguém explica.

Testar Conexão

O teste roda em três etapas, e cada uma falha por um motivo diferente:

Ping — valida URI, TLS, rota e credencial de uma vez. É a etapa que separa “não alcancei o servidor” de “o servidor recusou a credencial”.
Listagem de coleções do database — prova que o database configurado existe e é acessível por este usuário, o que o ping não diz (o ping roda contra o admin).
Coleção de teste — quando preenchida, prova que dá para ler de verdade.

O resultado traz a versão relatada pelo servidor. Em Cosmos DB e DocumentDB esse número é o da versão do protocolo que eles emulam, não o de um MongoDB — e é justamente essa a informação útil, porque é ela que determina quais recursos vão funcionar.

Keep Alive

Aponte a Aplicação para a Conexão Externa e escolha o tipo de Keep Alive MongoDB. Cada ciclo repete o teste acima. Com a Coleção de teste preenchida, o ciclo usa a contagem estimada de documentos — que lê metadados e não varre a coleção, então não pesa no banco do cliente.

Coleta

A Coleta lê a coleção no intervalo agendado e transforma cada documento em mensagem, com o mesmo Modo do Resultado das Coletas SQL (todos os documentos num payload, ou uma mensagem por documento).

Campo	Para que serve
Operação	`find` (filtro) ou `aggregate` (pipeline). O pipeline é o caminho quando o dado precisa ser agrupado, juntado ou remodelado no servidor
Coleção	Coleção lida
Filtro / Pipeline	JSON — o filtro do `find` ou o array de estágios do `aggregate`
Projeção / Ordenação	JSON, só no `find` (`{"tag": 1}` / `{"dataEvento": -1}`). No pipeline, `$project` e `$sort` fazem esse papel
Limite de documentos	Teto por execução. Existe para que um filtro escrito errado não traga a coleção inteira para a memória
Formato do payload	Simples converte ObjectId e Decimal128 para texto e Date para ISO 8601 — é o que o Transformador e o destino esperam. EJSON preserva o tipo exato de cada valor
Comando pós-coleta	Update aplicado aos documentos lidos, em JSON

Não há campo de database na Coleta nem na Entrega: ele vem sempre da Conexão Externa da Aplicação, como em PostgreSQL e SQL Server. Para ler ou gravar em vários databases do mesmo cluster, cadastre uma Conexão Externa por database — assim o Keep Alive continua monitorando exatamente o database que a integração usa.

Varredura incremental

Como no InfluxDB, a janela vem da própria consulta. O {{ultimaExecucao}} marca onde a execução anterior parou:


{ "dataEvento": { "$gt": { "$date": "{{ultimaExecucao}}" } } }

O {"$date": ...} em volta do placeholder não é opcional. Sem ele, o MongoDB compara uma data com um texto — e o filtro simplesmente não casa nada, sem erro nenhum. É o engano mais fácil de cometer aqui.

Na primeira execução, quando ainda não há marca d’água, {{ultimaExecucao}} resolve para 1970-01-01: a primeira varredura traz tudo o que o filtro alcançar, contida pelo Limite de documentos.

Comando pós-coleta

Diferente do InfluxDB, aqui existe “marcar como lido” — documento tem _id estável. É o padrão de quem usa uma coleção como fila de saída:


{ "$set": { "processado": true } }

O filtro desse update não é configurável: o CMS aplica sempre sobre os _id que aquela execução leu. Um filtro livre poderia marcar como processado um documento que a Coleta nunca entregou — inclusive um que chegou entre a leitura e o update, que se perderia sem ninguém notar.

Parâmetros de entrada e segurança

A Coleta aceita Parâmetros de Entrada (API dinâmica de Coleta) e Variáveis dentro do filtro, com {{alias}}. A substituição acontece no valor já estruturado, nunca no texto do JSON: um produtor que enviasse {"$ne": null} num parâmetro veria isso virar o texto literal {"$ne":null}, não um operador — o filtro continua procurando pelo valor, e não devolve a coleção inteira.

Placeholder em nome de campo é recusado ao salvar, pelo mesmo motivo.

O CMS também recusa, na Coleta: $where, $function e $accumulator (executam JavaScript no servidor do MongoDB), $out e $merge (gravam a partir de uma consulta) e estágios de agregação desconhecidos. $lookup, $graphLookup e $unionWith são permitidos — são leitura.

Entrega

MONGODB_WRITE grava a mensagem como documento. É a Entrega mais simples do CMS, e de propósito: o payload já é JSON e o MongoDB guarda JSON, então não há mapa de campos para configurar — o documento gravado é a saída do Transformador.

Campo	Para que serve
Modo de gravação	Ver a tabela abaixo
Coleção de destino	Onde gravar
Campos da chave	Só nos modos que casam com documento existente: campos do payload que identificam o documento, separados por vírgula
Campo de data da gravação	Opcional. Onde o CMS carimba o instante da gravação, como data de verdade
Modelo de Conteúdo	Opcional. Molda o documento antes da gravação; vazio grava o payload inteiro

Modo	O que faz	Quando usar
Inserir um documento	Cria um documento novo	Histórico, log, evento — cada mensagem é um fato próprio
Inserir em lote	Cria N documentos a partir de um array	Uma Coleta que emitiu várias linhas numa mensagem só
Atualizar ou criar (upsert)	Casa pela chave; cria quando não existe	“Estado atual” de cada equipamento/linha
Somente atualizar	Casa pela chave; não cria	Quando o documento tem de existir antes — a mensagem não deve criar cadastro

O lote é gravado com ordered: false: um documento recusado (chave duplicada, por exemplo) não impede a gravação dos demais. E o retorno da entrega traz o que aconteceu de fato no destino (inseridos, encontrados, modificados, criados por upsert), visível na tela de detalhe da mensagem.

Erros comuns

Sintoma	Causa provável	Correção
“Nenhum nó respondeu dentro do tempo limite” no Atlas	O IP do servidor do CMS não está na Network Access do projeto	Libere o IP no Atlas. A credencial não tem nada a ver com isso
“O MongoDB recusou a credencial” com usuário e senha corretos	`authSource` errado — o usuário existe num database específico, não no `admin`	Ajuste o Database de autenticação
Conexão recusada logo no início, no DocumentDB	retryable writes — o serviço não implementa	Escolha o serviço AWS DocumentDB no combo; o CMS desliga o recurso sozinho
Erro de certificado TLS	CA interna, ou o certificado da Amazon ausente no DocumentDB	Cole o certificado no campo Certificado da CA
“A coleção não existe no database”	Nome da coleção errado, ou database errado	O teste distingue isso de falta de permissão de propósito — confira os dois campos
A Coleta não traz nada, sem erro	Falta o `{"$date": ...}` em volta de `{{ultimaExecucao}}`	Envolva o placeholder, como na seção de varredura incremental
“Payload para Entrega MongoDB precisa ser um objeto JSON”	O Transformador devolveu texto, número ou array de escalares	Ajuste o Transformador, ou use o Modelo de Conteúdo para montar o documento
“Campo(s) da chave de upsert sem valor”	A mensagem não trouxe um dos campos da chave	Nada foi gravado, de propósito — corrija a origem ou o Transformador