zplCloud Blog
MongoDB como fuente de datos: sin exportar, sin copia en la nube
Los filtros se convierten en documentos de consulta nativos que ejecuta el agente en tu red. La cadena de conexión se queda en tu máquina.
Sin exportar, sin copia de tu colección en la nube
Datos de producto, artículos de pedido, números de serie: si ya viven en MongoDB, exportarlos a CSV para que una etiqueta pueda imprimirlos es pura sobrecarga, y el export está obsoleto en el mismo momento en que se escribe.
El data hub de zplCloud conecta la colección directamente. Un agente CLI en tu red guarda la cadena de conexión, la plataforma describe la consulta y el agente devuelve solo los documentos que coinciden. La base de datos permanece inaccesible desde internet.
Arquitectura
zplcloud proxy mantiene una conexión TLS saliente con api.zplcloud.com. Nada escucha en tu lado, así que no hay puertos de entrada ni excepciones de cortafuegos. La consulta, la ordenación y la paginación se empujan hacia abajo: el agente construye una consulta MongoDB real y llama a Find(filter).Sort(…).Skip(n).Limit(m). La colección nunca se descarga.
Paso 1 - inicia el agente con tu MongoDB
# Se permiten varias banderas --mongo; el NOMBRE es lo que eliges en la plataforma.
zplcloud proxy --agent "Lager" \
--mongo LOCAL="mongodb://admin:…@127.0.0.1:27017/products" \
--mongo PROD="mongodb://admin:…@mongo.internal.lan:27017/erp"
La cadena de conexión debe incluir el nombre de la base de datos: es la parte después del host, …:27017/products. Sin ella, el agente tiene un servidor pero ninguna base de datos que consultar.
Es mejor mantener los secretos fuera del historial del shell:
$env:ZPLCLOUD_MONGO_LOCAL_CONNECTION = "mongodb://admin:…@127.0.0.1:27017/products"
zplcloud proxy --agent "Lager"
El banner confirma lo registrado: MongoDB servers: LOCAL, PROD. Autentícate contra la plataforma con --api-key <key> o ZPLCLOUD_API_KEY; hazlo permanente con --service-install (systemd en Linux/Raspberry Pi, tarea programada en Windows) o con ZPLCLOUD_MONGO_LOCAL_CONNECTION en docker-compose.agent.yml.
Dale al agente un usuario de solo lectura limitado a la base de datos que necesita. El agente ejecuta con ese usuario, así que el propio modelo de roles de MongoDB es la frontera de permisos.
Paso 2 - crea la fuente de datos
En Fuentes de datos el agente aparece bajo Remote SQL Server con un chip por instancia de MongoDB. Al hacer clic se rellena el formulario.
| Campo | Valor |
|---|---|
| Nombre | Lager-Artikel |
| Tipo | MongoDB |
| Servidor | LOCAL (el nombre de --mongo LOCAL=…) |
| Colección | products |
Probar hace ping a la instancia y devuelve servidor · base de datos. Campos muestrea un documento y lista los nombres de campo con sus tipos BSON.
El descubrimiento de campos funciona a partir de una muestra, lo que importa en un almacén sin esquema: si los primeros documentos carecen de un campo que documentos posteriores sí tienen, no aparecerá en la lista. Añádelo manualmente en el binding si sabes que existe.
Paso 3 - cómo se ejecuta un filtro
La fila de filtro que construyes en Consulta - columna, operador, valor - se traduce a un documento de filtro MongoDB y la ejecuta el agente:
| Operador en la UI | MongoDB |
|---|---|
contiene | { ean: { $regex: "40063813" } } |
empieza con | { ean: { $regex: "^40063813" } } |
= | { ean: "40063813" } |
> / < | { price: { $gt: 10 } } / { $lt: … } |
Dos consecuencias que vale la pena decir claramente:
- No hay superficie de inyección. Un filtro MongoDB es un documento BSON - datos, no una cadena que se analiza como código. Un valor que contenga
$o{}sigue siendo solo un valor. $regexsin ancla no puede usar un índice.contieneen una colección grande es un escaneo completo.empieza conproduce^…, que un índice normal en ese campo puede servir. En colecciones grandes, prefíerelo.
Los límites duros (del código fuente del agente)
| Límite | Valor |
|---|---|
| Filas por solicitud | 1000 - limit se limita, el valor por defecto es 100 |
| Timeout de selección de servidor | 15 s - un replica set inalcanzable falla aquí, no después de minutos |
| Operación ejecutada | solo lectura: Find con sort, skip y limit |
Los conjuntos de resultados más grandes se paginan: la plataforma solicita página tras página con un Skip creciente, cada una limitada a 1000 documentos. La impresión por lotes de 10 000 etiquetas nunca mantiene más de una página en memoria, en ninguno de los lados.
Ten en cuenta que Skip con un offset grande hace que MongoDB recorra los documentos omitidos. Para catálogos de cientos de miles, un campo de ordenación indexado mantiene eso barato; una ordenación sin índice no lo hará.
Paso 4 - úsalo en el diseñador y en Print Views
- Diseñador → pestaña Datos de prueba → Fuente de datos: elige la fuente de datos, pulsa Cargar, y cada binding se renderiza con documentos reales. Las longitudes de campo, los valores faltantes y los problemas de codificación aparecen aquí y no en el rollo de etiquetas.
- Print Views → configuración → Fuente de datos (Data Hub): la vista previa y la impresión usan la consulta en vivo. El operador nunca ve que MongoDB está detrás.
Modos de fallo
| Síntoma | Causa |
|---|---|
| El agente corre, no hay chip en el data hub | falta el nombre --mongo, o la clave API pertenece a otro workspace |
Probar falla después de ~15 s | timeout de selección de servidor - host inalcanzable desde la máquina del agente, puerto incorrecto, o un replica set cuyos miembros anuncian nombres que el agente no puede resolver |
Probar falla al instante con error de auth | usuario/contraseña incorrectos, o la base de datos de autenticación difiere de la de datos (?authSource=admin) |
Campos se pierde un campo | el documento muestreado no lo contiene - las colecciones sin esquema necesitan una muestra representativa |
| El filtro no devuelve nada con un valor que ves | desajuste de tipo: un campo numérico comparado con una cadena. Comprueba el tipo en la lista de campos |
Plan
El data hub (fuentes de datos MongoDB y SQL Server a través del agente CLI) es parte del plan Pro. Consulta la página de precios.