MongoDB
Recolección MONGODB y Entrega MONGODB_WRITE.
Una sola Conexión Externa atiende cuatro servicios: MongoDB instalado por el cliente, MongoDB Atlas, Azure Cosmos DB (API Mongo) y AWS DocumentDB. No son protocolos distintos — es el mismo driver y la misma conversación de red; lo que cambia son valores por defecto y validaciones, y eso es lo que lleva el campo Servicio.
| Servicio | Qué cambia en la conexión |
|---|---|
| MongoDB (propio/on-premise) | Sin restricciones. Es el único donde aplica el campo Replica set |
| MongoDB Atlas | Exige URI mongodb+srv:// y TLS. Una falla de red se convierte en una pista sobre la IP Access List del proyecto |
| Azure Cosmos DB (API Mongo) | TLS obligatorio y retryable writes desactivado — el servicio no implementa la función |
| AWS DocumentDB | TLS obligatorio, retryable writes desactivado, y el certificado de la CA de Amazon en el campo de certificado |
Conexión
| Campo | Para qué sirve |
|---|---|
| Servicio | Define los valores anteriores. Elegir mal suele aparecer como rechazo en el handshake, sin explicación |
| URI de conexión | Solo la dirección: mongodb://mongo:27017 o mongodb+srv://cluster0.abcde.mongodb.net. Sin usuario ni contraseña |
| Database | Database por defecto de la conexión |
| Colección de prueba | Opcional. Si se completa, el Keep Alive también prueba que la colección responde a la lectura |
| Usuario / Contraseña | Credencial de acceso. La contraseña se cifra en reposo y nunca vuelve a la pantalla |
| Base de datos de autenticación | El authSource — donde fue creado el usuario. admin en la mayoría de las instalaciones |
| Replica set | Solo en el servicio propio, cuando la conexión se hace directo a los nodos |
| Timeout (ms) | Vale para los tres límites del driver: selección de nodo, conexión y operación |
| Conectar con TLS | En los servicios gestionados ya va activado, porque en ellos TLS es obligatorio |
| Validar certificado TLS / Certificado de la CA | Misma semántica que las demás conexiones. La CA es necesaria con certificado de CA interna — y en DocumentDB, que exige el certificado de Amazon |
| Reenviar escritura tras falla de red | retryable writes. Solo en el servicio propio: Cosmos DB y DocumentDB no lo admiten, y la conexión se hace con la función desactivada |
La URI no acepta credencial embebida (mongodb://usuario:contraseña@host). La URI aparece en el
listado de la pantalla de Conexiones Externas y en los archivos de exportación de configuración —
una contraseña allí se filtraría en ambos lugares. El CMS rechaza esa URI y pide la credencial en
sus campos propios, donde queda cifrada.
Como la credencial va fuera de la URI, una contraseña con @, : o / funciona sin escape. Es
lo contrario de lo que ocurre en herramientas que exigen la cadena de conexión completa, donde ese
detalle suele ser la causa de un “authentication failed” que nadie explica.
Probar Conexión
La prueba corre en tres etapas, y cada una falla por un motivo distinto:
- Ping — valida URI, TLS, ruta y credencial de una vez. Es la etapa que separa “no alcancé el servidor” de “el servidor rechazó la credencial”.
- Listado de colecciones del database — prueba que el database configurado existe y es accesible
por este usuario, algo que el ping no dice (el ping corre contra
admin). - Colección de prueba — si se completa, prueba que la lectura funciona de verdad.
El resultado trae la versión informada por el servidor. En Cosmos DB y DocumentDB ese número es el de la versión del protocolo que emulan, no el de un MongoDB real — y esa es justamente la información útil, porque determina qué recursos van a funcionar.
Keep Alive
Apunte la Aplicación a la Conexión Externa y elija el tipo de Keep Alive MongoDB. Cada ciclo repite la prueba anterior. Con la Colección de prueba completada, el ciclo usa el conteo estimado de documentos — que lee metadatos y no recorre la colección, así que no pesa en la base del cliente.
Recolección
La Recolección lee la colección en el intervalo programado y convierte cada documento en mensaje, con el mismo Modo del Resultado de las Recolecciones SQL (todos los documentos en un payload, o un mensaje por documento).
| Campo | Para qué sirve |
|---|---|
| Operación | find (filtro) o aggregate (pipeline). El pipeline es el camino cuando el dato necesita agruparse, unirse o remodelarse en el servidor |
| Colección | Colección leída |
| Filtro / Pipeline | JSON — el filtro del find o el array de etapas del aggregate |
| Proyección / Orden | JSON, solo en find ({"tag": 1} / {"dataEvento": -1}). En el pipeline, $project y $sort cumplen ese papel |
| Límite de documentos | Tope por ejecución. Existe para que un filtro mal escrito no traiga la colección entera a la memoria |
| Formato del payload | Simple convierte ObjectId y Decimal128 a texto y Date a ISO 8601 — lo que el Transformador y el destino esperan. EJSON preserva el tipo exacto de cada valor |
| Comando pos-recolección | Update aplicado a los documentos leídos, en JSON |
No hay campo de database en la Recolección ni en la Entrega: siempre viene de la Conexión Externa de la Aplicación, como en PostgreSQL y SQL Server. Para leer o grabar en varios databases del mismo clúster, registre una Conexión Externa por database — así el Keep Alive sigue monitoreando exactamente el database que usa la integración.
Barrido incremental
Como en InfluxDB, la ventana viene de la propia consulta. {{ultimaExecucao}} marca dónde se detuvo
la ejecución anterior:
{ "dataEvento": { "$gt": { "$date": "{{ultimaExecucao}}" } } }El {"$date": ...} alrededor del placeholder no es opcional. Sin él, MongoDB compara una fecha
con un texto — y el filtro simplemente no coincide con nada, sin ningún error. Es el error más fácil
de cometer aquí.
En la primera ejecución, cuando todavía no hay marca de agua, {{ultimaExecucao}} resuelve a
1970-01-01: el primer barrido trae todo lo que el filtro alcance, contenido por el Límite de
documentos.
Comando pos-recolección
A diferencia de InfluxDB, aquí sí existe “marcar como leído” — un documento tiene _id estable. Es el
patrón de quien usa una colección como cola de salida:
{ "$set": { "processado": true } }El filtro de ese update no es configurable: el CMS lo aplica siempre sobre los _id que esa
ejecución leyó. Un filtro libre podría marcar como procesado un documento que la Recolección nunca
entregó — incluso uno que llegó entre la lectura y el update, que se perdería sin que nadie lo note.
Parámetros de entrada y seguridad
La Recolección acepta Parámetros de Entrada (API dinámica de Recolección) y Variables dentro del
filtro, con {{alias}}. La sustitución ocurre en el valor ya estructurado, nunca en el texto del
JSON: un productor que enviara {"$ne": null} en un parámetro vería eso convertirse en el texto
literal {"$ne":null}, no en un operador — el filtro sigue buscando ese valor y no devuelve la
colección entera.
Un placeholder en el nombre de un campo se rechaza al guardar, por el mismo motivo.
El CMS también rechaza, en una Recolección: $where, $function y $accumulator (ejecutan
JavaScript en el servidor de MongoDB), $out y $merge (graban a partir de una consulta) y etapas de
agregación desconocidas. $lookup, $graphLookup y $unionWith están permitidos — son lectura.
Entrega
MONGODB_WRITE graba el mensaje como documento. Es la Entrega más simple del CMS, y a propósito: el
payload ya es JSON y MongoDB guarda JSON, así que no hay mapa de campos para configurar — el
documento grabado es la salida del Transformador.
| Campo | Para qué sirve |
|---|---|
| Modo de grabación | Ver la tabla de abajo |
| Colección de destino | Dónde grabar |
| Campos de la clave | Solo en los modos que coinciden con documento existente: campos del payload que identifican el documento, separados por coma |
| Campo de fecha de grabación | Opcional. Donde el CMS marca el instante de la grabación, como fecha real |
| Modelo de Contenido | Opcional. Moldea el documento antes de grabar; vacío graba el payload entero |
| Modo | Qué hace | Cuándo usarlo |
|---|---|---|
| Insertar un documento | Crea un documento nuevo | Histórico, log, evento — cada mensaje es un hecho propio |
| Insertar por lote | Crea N documentos a partir de un array | Una Recolección que emitió varias filas en un solo mensaje |
| Actualizar o crear (upsert) | Coincide por la clave; crea cuando no existe | “Estado actual” de cada equipo/línea |
| Solo actualizar | Coincide por la clave; nunca crea | Cuando el documento debe existir antes — el mensaje no debe crear registros |
El lote se graba con ordered: false: un documento rechazado (clave duplicada, por ejemplo) no impide
la grabación de los demás. Y el retorno de la entrega trae lo que ocurrió de verdad en el destino
(insertados, encontrados, modificados, creados por upsert), visible en la pantalla de detalle del
mensaje.
Errores comunes
| Síntoma | Causa probable | Corrección |
|---|---|---|
| “Ningún nodo respondió dentro del tiempo límite” en Atlas | La IP del servidor del CMS no está en la Network Access del proyecto | Habilite la IP en Atlas. La credencial no tiene nada que ver |
| “MongoDB rechazó la credencial” con usuario y contraseña correctos | authSource equivocado — el usuario existe en un database específico, no en admin | Ajuste la Base de datos de autenticación |
| Conexión rechazada de inmediato en DocumentDB | retryable writes — el servicio no lo implementa | Elija el servicio AWS DocumentDB en el combo; el CMS desactiva la función solo |
| Error de certificado TLS | CA interna, o el certificado de Amazon ausente en DocumentDB | Pegue el certificado en el campo Certificado de la CA |
| “La colección no existe en el database” | Nombre de la colección equivocado, o database equivocado | La prueba distingue esto de la falta de permiso a propósito — verifique ambos campos |
| La Recolección no trae nada, sin error | Falta el {"$date": ...} alrededor de {{ultimaExecucao}} | Envuelva el placeholder, como en la sección de barrido incremental |
| “El payload para una Entrega MongoDB debe ser un objeto JSON” | El Transformador devolvió texto, número o array de escalares | Ajuste el Transformador, o use el Modelo de Contenido para armar el documento |
| “Campo(s) de la clave de upsert sin valor” | El mensaje no trajo uno de los campos de la clave | No se grabó nada, a propósito — corrija el origen o el Transformador |