Pular para conteúdo

MONGODB INSERT - Inserir Documento no MongoDB

O que é este Node?

O MONGODB INSERT é o node responsável por inserir um novo documento em uma coleção MongoDB, retornando o ID do documento criado.

Por que este Node existe?

Criar novos registros em um banco de dados NoSQL requer uma operação específica de inserção. O MONGODB INSERT existe para:

  1. Criar novos documentos: Adicionar registros únicos em uma coleção
  2. Gerar IDs automáticos: MongoDB cria automaticamente um _id único
  3. Armazenar dados complexos: Inserir objetos aninhados e arrays
  4. Confirmar inserção: Retornar ID gerado e status da operação

Como funciona internamente?

Quando o MONGODB INSERT é executado, o sistema:

  1. Valida configuração: Verifica se as credenciais MongoDB foram fornecidas
  2. Estabelece conexão: Conecta ao servidor MongoDB usando as credenciais
  3. Seleciona coleção: Acessa a coleção especificada no banco de dados
  4. Processa documento: Substitui variáveis no documento a ser inserido
  5. Insere documento: Executa insertOne() no MongoDB
  6. Gera _id automático: Se não fornecido, MongoDB cria ObjectId único
  7. Armazena resultado: Salva insertedId e acknowledged na variável especificada
  8. Fecha conexão: Encerra a conexão com MongoDB

Código interno (mongodb.executor.ts:152-167):

private async insertDocument(
  db: Db,
  collectionName: string,
  document: any,
  context: ExecutionContext,
): Promise<any> {
  const replacedDocument = this.replaceObjectVariables(document, context.variables);

  const collection = db.collection(collectionName);
  const result = await collection.insertOne(replacedDocument);

  return {
    insertedId: result.insertedId,
    acknowledged: result.acknowledged,
  };
}

Quando você DEVE usar este Node?

Use MONGODB INSERT sempre que precisar criar um novo documento em uma coleção:

Casos de uso

  1. Cadastrar usuário: "Criar novo registro de usuário no sistema"
  2. Registrar pedido: "Salvar novo pedido de compra"
  3. Criar log: "Inserir registro de auditoria ou evento"
  4. Adicionar produto: "Cadastrar novo produto no catálogo"

Quando NÃO usar MONGODB INSERT

  • Atualizar existente: Use MONGODB UPDATE para modificar documento existente
  • Upsert (inserir ou atualizar): Use MONGODB FIND_ONE_AND_UPDATE com upsert:true
  • Inserir múltiplos: Para muitos documentos, considere insertMany (não disponível neste executor)

Parâmetros Detalhados

operation (string, obrigatório)

O que é: Define qual operação MongoDB será executada. Para inserir documento, use "insert".

Padrão: Nenhum (obrigatório)

Flow completo para testar:

{
  "name": "Teste MongoDB Insert - Operation",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "mongodb_1",
      "type": "mongodb",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Inserir Produto",
        "operation": "insert",
        "config": {
          "connectionString": "mongodb://localhost:27017",
          "database": "loja"
        },
        "collection": "produtos",
        "document": {
          "nome": "Notebook",
          "preco": 2999.90,
          "estoque": 10
        },
        "responseVariable": "resultado"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Produto inserido! ID: {{resultado.insertedId}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "mongodb_1" },
    { "source": "mongodb_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: 1. Execute o flow 2. Espere: "✅ Produto inserido! ID: 507f1f77bcf86cd799439011"

config (object, obrigatório)

O que é: Objeto contendo as credenciais e configurações de conexão com o MongoDB.

Estrutura: - connectionString (string): String de conexão completa MongoDB - OU host, port, user, password: Configuração individual - database (string, obrigatório): Nome do banco de dados

Flow completo para testar:

{
  "name": "Teste MongoDB Insert - Config",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "mongodb_1",
      "type": "mongodb",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Inserir com Auth",
        "operation": "insert",
        "config": {
          "host": "localhost",
          "port": 27017,
          "database": "crm",
          "user": "admin",
          "password": "senha123"
        },
        "collection": "clientes",
        "document": {
          "nome": "Maria Santos",
          "email": "maria@example.com"
        },
        "responseVariable": "resultado"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar Inserção",
        "parameters": {
          "message": "Cliente cadastrado! ID: {{resultado.insertedId}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "mongodb_1" },
    { "source": "mongodb_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: 1. Configure MongoDB com autenticação 2. Execute o flow 3. Espere: "Cliente cadastrado! ID: ..."

collection (string, obrigatório)

O que é: Nome da coleção MongoDB onde o documento será inserido.

Flow completo para testar:

{
  "name": "Teste MongoDB Insert - Collection",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "mongodb_1",
      "type": "mongodb",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Inserir na Coleção",
        "operation": "insert",
        "config": {
          "connectionString": "mongodb://localhost:27017",
          "database": "ecommerce"
        },
        "collection": "pedidos",
        "document": {
          "numero": "PED-2024-001",
          "total": 299.90,
          "status": "pendente"
        },
        "responseVariable": "pedido"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Mostrar Pedido",
        "parameters": {
          "message": "Pedido criado! ID: {{pedido.insertedId}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "mongodb_1" },
    { "source": "mongodb_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: 1. Execute o flow 2. Espere: "Pedido criado! ID: ..."

document (object, obrigatório)

O que é: Objeto contendo os dados do documento a ser inserido. Suporta variáveis com sintaxe {{variavel}}.

Flow completo para testar:

{
  "name": "Teste MongoDB Insert - Document",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "mongodb_1",
      "type": "mongodb",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Inserir Documento Completo",
        "operation": "insert",
        "config": {
          "connectionString": "mongodb://localhost:27017",
          "database": "loja"
        },
        "collection": "produtos",
        "document": {
          "nome": "Notebook Dell Inspiron",
          "descricao": "Core i5, 8GB RAM, 256GB SSD",
          "preco": 3499.90,
          "estoque": 5,
          "categorias": ["informatica", "notebooks"],
          "especificacoes": {
            "processador": "Intel Core i5",
            "memoria": "8GB",
            "armazenamento": "256GB SSD"
          },
          "ativo": true,
          "dataCriacao": "2024-01-15T10:30:00.000Z"
        },
        "responseVariable": "novoProduto"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Produto cadastrado com sucesso!\nID: {{novoProduto.insertedId}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "mongodb_1" },
    { "source": "mongodb_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: 1. Execute o flow 2. Espere: "✅ Produto cadastrado com sucesso! ID: ..."

responseVariable (string, opcional)

O que é: Nome da variável onde o resultado da inserção será armazenado (contém insertedId e acknowledged).

Padrão: Se não especificado, resultado não é armazenado

Flow completo para testar:

{
  "name": "Teste MongoDB Insert - Response Variable",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "mongodb_1",
      "type": "mongodb",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Inserir e Salvar Resultado",
        "operation": "insert",
        "config": {
          "connectionString": "mongodb://localhost:27017",
          "database": "logs"
        },
        "collection": "eventos",
        "document": {
          "tipo": "login",
          "usuario": "joao@example.com",
          "timestamp": "2024-01-15T10:30:00.000Z"
        },
        "responseVariable": "eventoLog"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Usar Resultado",
        "parameters": {
          "message": "Log registrado!\nID: {{eventoLog.insertedId}}\nStatus: {{eventoLog.acknowledged}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "mongodb_1" },
    { "source": "mongodb_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: 1. Execute o flow 2. Espere: "Log registrado! ID: ... Status: true"

Parâmetros

Campo Tipo Obrigatório Descrição
operation string Sim Tipo de operação MongoDB ("insert")
config object Sim Configuração de conexão MongoDB
collection string Sim Nome da coleção
document object Sim Documento a ser inserido
responseVariable string Não Variável para armazenar resultado

Exemplo 1: Cadastro de Novo Cliente

Objetivo: Coletar dados do cliente e inserir no MongoDB

JSON para Importar

{
  "name": "Cadastro de Novo Cliente",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_nome",
      "type": "input",
      "position": { "x": 250, "y": 100 },
      "data": {
        "label": "Solicitar Nome",
        "parameters": {
          "message": "Digite seu nome completo:",
          "variable": "nome"
        }
      }
    },
    {
      "id": "input_email",
      "type": "email",
      "position": { "x": 400, "y": 100 },
      "data": {
        "label": "Solicitar Email",
        "parameters": {
          "message": "Digite seu email:",
          "variable": "email"
        }
      }
    },
    {
      "id": "input_telefone",
      "type": "phone",
      "position": { "x": 550, "y": 100 },
      "data": {
        "label": "Solicitar Telefone",
        "parameters": {
          "message": "Digite seu telefone:",
          "variable": "telefone"
        }
      }
    },
    {
      "id": "mongodb_insert",
      "type": "mongodb",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Salvar Cliente",
        "operation": "insert",
        "config": {
          "connectionString": "mongodb://localhost:27017",
          "database": "crm"
        },
        "collection": "clientes",
        "document": {
          "nome": "{{nome}}",
          "email": "{{email}}",
          "telefone": "{{telefone}}",
          "status": "ativo",
          "dataCadastro": "{{now}}",
          "origem": "whatsapp"
        },
        "responseVariable": "novoCliente"
      }
    },
    {
      "id": "message_success",
      "type": "message",
      "position": { "x": 850, "y": 100 },
      "data": {
        "label": "Confirmação",
        "parameters": {
          "message": "✅ Cadastro realizado com sucesso!\n\n👤 Nome: {{nome}}\n📧 Email: {{email}}\n📱 Telefone: {{telefone}}\n\n🆔 Seu ID: {{novoCliente.insertedId}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1000, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_nome" },
    { "source": "input_nome", "target": "input_email" },
    { "source": "input_email", "target": "input_telefone" },
    { "source": "input_telefone", "target": "mongodb_insert" },
    { "source": "mongodb_insert", "target": "message_success" },
    { "source": "message_success", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Digite seu nome completo:
Usuário: João Silva
Sistema: Digite seu email:
Usuário: joao@example.com
Sistema: Digite seu telefone:
Usuário: 11987654321
Sistema: ✅ Cadastro realizado com sucesso!

👤 Nome: João Silva
📧 Email: joao@example.com
📱 Telefone: 11987654321

🆔 Seu ID: 507f1f77bcf86cd799439011

Exemplo 2: Registrar Pedido de Compra

Objetivo: Criar registro de pedido com itens e totais

JSON para Importar

{
  "name": "Registrar Pedido de Compra",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 250, "y": 100 },
      "data": {
        "label": "Dados do Pedido",
        "parameters": {
          "variables": [
            { "name": "clienteId", "value": "507f1f77bcf86cd799439011" },
            { "name": "subtotal", "value": "299.90" },
            { "name": "frete", "value": "20.00" },
            { "name": "total", "value": "319.90" }
          ]
        }
      }
    },
    {
      "id": "mongodb_insert",
      "type": "mongodb",
      "position": { "x": 400, "y": 100 },
      "data": {
        "label": "Criar Pedido",
        "operation": "insert",
        "config": {
          "connectionString": "mongodb://localhost:27017",
          "database": "ecommerce"
        },
        "collection": "pedidos",
        "document": {
          "clienteId": "{{clienteId}}",
          "numero": "PED-{{timestamp}}",
          "status": "pendente",
          "itens": [
            {
              "produtoId": "prod-001",
              "nome": "Notebook Dell",
              "quantidade": 1,
              "precoUnitario": 2999.90
            },
            {
              "produtoId": "prod-002",
              "nome": "Mouse Logitech",
              "quantidade": 2,
              "precoUnitario": 49.90
            }
          ],
          "valores": {
            "subtotal": "{{subtotal}}",
            "frete": "{{frete}}",
            "total": "{{total}}"
          },
          "endereco": {
            "rua": "Rua das Flores, 123",
            "cidade": "São Paulo",
            "estado": "SP",
            "cep": "01234-567"
          },
          "dataCriacao": "{{now}}",
          "dataAtualizacao": "{{now}}"
        },
        "responseVariable": "pedido"
      }
    },
    {
      "id": "message_success",
      "type": "message",
      "position": { "x": 550, "y": 100 },
      "data": {
        "label": "Confirmação",
        "parameters": {
          "message": "✅ Pedido criado com sucesso!\n\n🆔 ID: {{pedido.insertedId}}\n💰 Total: R$ {{total}}\n📦 Status: Pendente"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "mongodb_insert" },
    { "source": "mongodb_insert", "target": "message_success" },
    { "source": "message_success", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: ✅ Pedido criado com sucesso!

🆔 ID: 507f1f77bcf86cd799439012
💰 Total: R$ 319.90
📦 Status: Pendente

Exemplo 3: Criar Log de Auditoria

Objetivo: Registrar ações do usuário para auditoria

JSON para Importar

{
  "name": "Criar Log de Auditoria",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 250, "y": 100 },
      "data": {
        "label": "Dados da Ação",
        "parameters": {
          "variables": [
            { "name": "usuarioId", "value": "user-123" },
            { "name": "acao", "value": "alteracao_preco" },
            { "name": "recurso", "value": "produto-456" },
            { "name": "detalhes", "value": "Preço alterado de R$99.90 para R$89.90" }
          ]
        }
      }
    },
    {
      "id": "mongodb_insert",
      "type": "mongodb",
      "position": { "x": 400, "y": 100 },
      "data": {
        "label": "Registrar Log",
        "operation": "insert",
        "config": {
          "connectionString": "mongodb://localhost:27017",
          "database": "auditoria"
        },
        "collection": "logs",
        "document": {
          "usuarioId": "{{usuarioId}}",
          "acao": "{{acao}}",
          "recurso": "{{recurso}}",
          "detalhes": "{{detalhes}}",
          "ip": "192.168.1.100",
          "userAgent": "WhatsApp/2.24.1",
          "timestamp": "{{now}}",
          "nivel": "info"
        },
        "responseVariable": "log"
      }
    },
    {
      "id": "message_success",
      "type": "message",
      "position": { "x": 550, "y": 100 },
      "data": {
        "label": "Confirmação",
        "parameters": {
          "message": "📝 Log de auditoria registrado\nID: {{log.insertedId}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "mongodb_insert" },
    { "source": "mongodb_insert", "target": "message_success" },
    { "source": "message_success", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: 📝 Log de auditoria registrado
ID: 507f1f77bcf86cd799439013

Resposta do Node

{
  "insertedId": "507f1f77bcf86cd799439011",
  "acknowledged": true
}

Boas Práticas

✅ SIM:

  • Sempre armazene o insertedId para referência futura
  • Use variáveis do contexto ({{variavel}}) para dados dinâmicos
  • Inclua timestamp de criação no documento
  • Valide dados ANTES de inserir (use nodes de validação)
  • Use campos de status para controlar estados do documento
  • Armazene resultado em responseVariable para usar depois

❌ NÃO:

  • Não insira documentos vazios ou sem dados essenciais
  • Não esqueça de validar dados de entrada antes de inserir
  • Não ignore o insertedId retornado (você pode precisar dele)
  • Não tente inserir _id manualmente (deixe MongoDB gerar)
  • Não insira dados sensíveis sem criptografia

Dicas

💡 Dica 1: O _id é gerado automaticamente se não fornecido - não precisa incluir no document

💡 Dica 2: Use {{now}} para timestamps automáticos de criação

💡 Dica 3: MongoDB aceita objetos aninhados e arrays - aproveite a flexibilidade do NoSQL

💡 Dica 4: Combine com FIND_ONE antes para evitar duplicatas (validar por email, CPF, etc)

💡 Dica 5: O campo acknowledged: true confirma que a operação foi reconhecida pelo servidor

Próximos Nodes

→ MONGODB FIND_ONE - Buscar documento inserido → MONGODB UPDATE - Atualizar documento depois → MONGODB FIND_ONE_AND_UPDATE - Upsert (inserir se não existir) → MONGODB DELETE - Remover documentos