MongoDB Integration - Lumina Flow Builder

Visão Geral

A integração MongoDB do Lumina Flow Builder permite que você execute operações completas em bancos de dados MongoDB NoSQL diretamente de seus fluxos WhatsApp, sem escrever código.

O que é MongoDB?

MongoDB é um banco de dados NoSQL orientado a documentos que armazena dados em formato JSON-like (BSON). Diferente de bancos SQL tradicionais, MongoDB oferece:

Flexibilidade de Schema: Documentos podem ter estruturas diferentes
Performance: Otimizado para leitura e escrita em grande escala
Escalabilidade: Fácil de escalar horizontalmente
Documentos Aninhados: Suporte nativo a objetos complexos e arrays

Por que Usar MongoDB no Lumina?

Armazenamento Flexível: Guardar dados de conversas, leads, pedidos sem schema rígido
Performance: Consultas rápidas para dados de chatbot
Análises: Usar aggregation pipelines para relatórios complexos
Integração: Conectar chatbot com sistemas que já usam MongoDB

Operações Disponíveis

O Lumina Flow Builder oferece 8 operações MongoDB completas:

1. FIND - Buscar Múltiplos Documentos

Busca vários documentos com filtros, ordenação e paginação.

{
  "operation": "find",
  "collection": "produtos",
  "query": { "categoria": "eletronicos" },
  "limit": 10,
  "sort": { "preco": -1 }
}

Use quando: Listar produtos, buscar histórico, gerar relatórios

2. FIND_ONE - Buscar Um Documento

Busca apenas o primeiro documento que atende aos critérios.

{
  "operation": "findOne",
  "collection": "clientes",
  "query": { "email": "joao@example.com" }
}

Use quando: Buscar por ID, validar login, verificar duplicatas

3. INSERT - Inserir Documento

Cria um novo documento na coleção.

{
  "operation": "insert",
  "collection": "pedidos",
  "document": {
    "clienteId": "123",
    "total": 299.90,
    "status": "pendente"
  }
}

Use quando: Cadastrar usuário, criar pedido, registrar evento

4. UPDATE - Atualizar Documentos

Atualiza múltiplos documentos que atendem a uma query.

{
  "operation": "update",
  "collection": "produtos",
  "query": { "categoria": "livros" },
  "update": { "frete": "gratis" }
}

Use quando: Atualizar preços, mudar status em lote, corrigir dados

5. DELETE - Remover Documentos

Remove múltiplos documentos que atendem a uma query.

{
  "operation": "delete",
  "collection": "logs",
  "query": { "timestamp": { "$lt": "2024-01-01" } }
}

Use quando: Limpar dados antigos, remover registros temporários, LGPD

6. AGGREGATE - Pipeline de Agregação

Executa pipelines complexos para análises e transformações.

{
  "operation": "aggregate",
  "collection": "vendas",
  "pipeline": [
    { "$match": { "status": "concluido" } },
    { "$group": { "_id": "$categoria", "total": { "$sum": "$valor" } } },
    { "$sort": { "total": -1 } }
  ]
}

Use quando: Relatórios, estatísticas, análises complexas, agrupamentos

7. FIND_ONE_AND_UPDATE - Buscar e Atualizar

Busca um documento e o atualiza em uma operação atômica.

{
  "operation": "findOneAndUpdate",
  "collection": "posts",
  "query": { "slug": "primeiro-post" },
  "update": { "visualizacoes": 101 }
}

Use quando: Incrementar contadores, upsert (criar se não existir), evitar race conditions

8. FIND_ONE_AND_REPLACE - Buscar e Substituir

Busca um documento e o substitui completamente.

{
  "operation": "findOneAndReplace",
  "collection": "configuracoes",
  "query": { "chave": "email" },
  "document": {
    "chave": "email",
    "smtp": "smtp.gmail.com",
    "porta": 587
  }
}

Use quando: Reset de configurações, migração de schema, substituição completa

Configuração de Conexão

Todas as operações requerem um objeto config com credenciais MongoDB:

Opção 1: Connection String

{
  "config": {
    "connectionString": "mongodb://localhost:27017",
    "database": "meu_banco"
  }
}

Opção 2: Configuração Individual

{
  "config": {
    "host": "localhost",
    "port": 27017,
    "database": "meu_banco",
    "user": "admin",
    "password": "senha123"
  }
}

Guia Rápido: Qual Operação Usar?

Preciso...	Use
Listar vários registros	FIND
Buscar um registro específico	FIND_ONE
Criar novo registro	INSERT
Atualizar campos de vários registros	UPDATE
Remover registros	DELETE
Fazer relatórios/análises	AGGREGATE
Atualizar e ver resultado	FIND_ONE_AND_UPDATE
Substituir documento inteiro	FIND_ONE_AND_REPLACE

Casos de Uso Comuns

1. Sistema de E-commerce

FIND → Listar produtos disponíveis
INSERT → Criar pedido
FIND_ONE_AND_UPDATE → Decrementar estoque
UPDATE → Atualizar status do pedido
AGGREGATE → Relatório de vendas

2. CRM (Gestão de Clientes)

FIND_ONE → Buscar cliente por email
INSERT → Cadastrar novo lead
UPDATE → Atualizar dados de contato
AGGREGATE → Análise de conversões
DELETE → Remover dados (LGPD)

3. Sistema de Blog

FIND → Listar posts publicados
INSERT → Criar novo post
FIND_ONE_AND_UPDATE → Incrementar visualizações
FIND_ONE_AND_REPLACE → Publicar rascunho
DELETE → Remover posts antigos

4. Sistema de Notificações

INSERT → Criar notificação
FIND → Buscar notificações não lidas
FIND_ONE_AND_UPDATE → Marcar como lida
DELETE → Limpar notificações antigas
AGGREGATE → Estatísticas de engajamento

Variáveis do Contexto

Todas as operações suportam variáveis com sintaxe {{variavel}}:

{
  "query": {
    "email": "{{userEmail}}",
    "status": "{{orderStatus}}"
  }
}

Variáveis especiais: - {{now}} - Data/hora atual - {{timestamp}} - Timestamp Unix - Qualquer variável definida em nodes anteriores

Armazenamento de Resultados

Use responseVariable para salvar resultados e usar em nodes seguintes:

{
  "operation": "find",
  "collection": "produtos",
  "query": {},
  "responseVariable": "listaProdutos"
}

Depois acesse: - {{listaProdutos.documents}} - Array de documentos - {{listaProdutos.count}} - Quantidade de documentos - {{listaProdutos.documents[0].nome}} - Campo específico

Operadores MongoDB Suportados

Comparação

$eq - Igual
$ne - Diferente
$gt - Maior que
$gte - Maior ou igual
$lt - Menor que
$lte - Menor ou igual
$in - Em array
$nin - Não em array

Lógicos

$and - E lógico
$or - Ou lógico
$not - Negação
$nor - Nem

Elemento

$exists - Campo existe
$type - Tipo do campo

Aggregation (Pipeline)

$match - Filtrar
$group - Agrupar
$project - Projetar campos
$sort - Ordenar
$limit - Limitar
$skip - Pular
$lookup - JOIN
$unwind - Descompactar arrays

Boas Práticas

Performance

✅ SIM: - Use índices em campos frequentemente consultados - Limite resultados com limit para queries grandes - Use $match no início de pipelines aggregate - Projete apenas campos necessários

❌ NÃO: - Não busque todos os documentos sem limit - Não faça queries em campos sem índice em produção - Não use aggregate para queries simples

Segurança

✅ SIM: - Valide entrada do usuário antes de queries - Use variáveis do contexto para dados dinâmicos - Configure autenticação no MongoDB - Faça backup antes de DELETE em massa

❌ NÃO: - Não use credenciais no código (use variáveis de ambiente) - Não execute DELETE com query vazia {} - Não exponha mensagens de erro detalhadas ao usuário

Manutenibilidade

✅ SIM: - Use nomes descritivos para collections - Documente estrutura de documentos - Use responseVariable para rastreabilidade - Combine com CONDITION para tratar erros

❌ NÃO: - Não misture diferentes schemas na mesma collection - Não esqueça de tratar casos onde não há resultados - Não ignore campos de timestamp (createdAt, updatedAt)

Exemplos Práticos Completos

Cadastro de Cliente com Validação

START
  ↓
INPUT (email)
  ↓
FIND_ONE (verificar se email existe)
  ↓
CONDITION (email já existe?)
  ↓ não
INSERT (criar novo cliente)
  ↓
MESSAGE (confirmação)
  ↓
END

Sistema de Carrinho de Compras

START
  ↓
FIND (listar produtos)
  ↓
MESSAGE (mostrar produtos)
  ↓
INPUT (escolher produto)
  ↓
FIND_ONE_AND_UPDATE (decrementar estoque)
  ↓
INSERT (criar pedido)
  ↓
MESSAGE (confirmação)
  ↓
END

Relatório de Vendas

START
  ↓
DATE (período inicial)
  ↓
DATE (período final)
  ↓
AGGREGATE (vendas por categoria)
  ↓
CONDITION (tem vendas?)
  ↓ sim
MESSAGE (mostrar relatório)
  ↓
END

Troubleshooting

Erro: Connection refused

Problema: MongoDB não está rodando ou configuração incorreta

Solução: 1. Verifique se MongoDB está ativo: systemctl status mongodb 2. Confirme host e port corretos 3. Teste conexão: mongo mongodb://host:port

Erro: Authentication failed

Problema: Credenciais incorretas

Solução: 1. Verifique usuário e senha 2. Confirme permissões do usuário no banco 3. Use connection string completa com auth

Query não retorna resultados

Problema: Filtros incorretos ou documentos não existem

Solução: 1. Use FIND sem query para ver todos os documentos 2. Verifique tipos de dados (string vs number) 3. Teste query no MongoDB Compass primeiro

Performance lenta

Problema: Query sem índices ou collection muito grande

Solução: 1. Crie índices em campos consultados 2. Use limit para restringir resultados 3. Otimize pipelines aggregate (use $match primeiro)

Recursos Adicionais

Documentação Oficial

Ferramentas Úteis

MongoDB Compass: GUI para visualizar e testar queries
Studio 3T: IDE completo para MongoDB
mongo shell: CLI para testar conexões

Tutoriais

Suporte

Para dúvidas sobre: - Operações específicas: Consulte a documentação de cada operação - MongoDB em geral: Veja documentação oficial do MongoDB - Lumina Flow Builder: Entre em contato com o suporte

Changelog

v1.0.0 (2025-01-15)

✅ 8 operações MongoDB completas
✅ Suporte a aggregation pipelines
✅ Operações atômicas (findOneAndUpdate/Replace)
✅ Upsert support
✅ Variáveis de contexto
✅ ObjectId conversion automática

Pronto para começar? Escolha uma operação acima e comece a integrar MongoDB em seus fluxos!