Pular para conteúdo

MONGODB FIND_ONE - Buscar Único Documento no MongoDB

O que é este Node?

O MONGODB FIND_ONE é o node responsável por buscar um único documento em uma coleção MongoDB, retornando o primeiro documento que atende aos critérios especificados.

Por que este Node existe?

Quando você precisa buscar apenas um documento específico (por ID, email único, etc), buscar múltiplos documentos é ineficiente. O MONGODB FIND_ONE existe para:

  1. Buscar por ID: Recuperar um documento específico usando seu _id único
  2. Performance otimizada: Para quando você precisa de apenas 1 registro
  3. Buscar registros únicos: Email, CPF, username ou qualquer campo único
  4. Validar existência: Verificar se um documento existe antes de operações

Como funciona internamente?

Quando o MONGODB FIND_ONE é 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 query: Substitui variáveis e converte _id strings para ObjectId
  5. Busca primeiro documento: Executa findOne que retorna apenas o primeiro match
  6. Retorna documento: Se encontrado, retorna o documento completo; se não, retorna null
  7. Armazena resultado: Salva documento na variável especificada
  8. Fecha conexão: Encerra a conexão com MongoDB

Código interno (mongodb.executor.ts:142-150):

private async findOne(db: Db, collectionName: string, query: any, context: ExecutionContext): Promise<any> {
  const replacedQuery = this.replaceObjectVariables(query || {}, context.variables);
  const parsedQuery = this.parseMongoQuery(replacedQuery);

  const collection = db.collection(collectionName);
  const document = await collection.findOne(parsedQuery);

  return document;
}

Quando você DEVE usar este Node?

Use MONGODB FIND_ONE sempre que precisar buscar apenas um documento específico:

Casos de uso

  1. Buscar por ID: "Recuperar produto com _id específico"
  2. Validar login: "Verificar se usuário com email X existe"
  3. Buscar registro único: "Buscar cliente pelo CPF"
  4. Checar duplicatas: "Verificar se email já está cadastrado"

Quando NÃO usar MONGODB FIND_ONE

  • Buscar múltiplos: Use MONGODB FIND para vários documentos
  • Atualizar ao buscar: Use MONGODB FIND_ONE_AND_UPDATE para buscar e modificar
  • Substituir documento: Use MONGODB FIND_ONE_AND_REPLACE para trocar completamente

Parâmetros Detalhados

operation (string, obrigatório)

O que é: Define qual operação MongoDB será executada. Para buscar um único documento, use "findOne".

Padrão: Nenhum (obrigatório)

Flow completo para testar:

{
  "name": "Teste MongoDB FindOne - 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": "Buscar Um Produto",
        "operation": "findOne",
        "config": {
          "connectionString": "mongodb://localhost:27017",
          "database": "loja"
        },
        "collection": "produtos",
        "query": { "_id": "507f1f77bcf86cd799439011" },
        "responseVariable": "produto"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Mostrar Produto",
        "parameters": {
          "message": "Produto: {{produto.nome}}"
        }
      }
    },
    {
      "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 com um _id válido 2. Espere: "Produto: Nome do Produto"

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 FindOne - 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": "Buscar com Autenticação",
        "operation": "findOne",
        "config": {
          "host": "localhost",
          "port": 27017,
          "database": "loja",
          "user": "admin",
          "password": "senha123"
        },
        "collection": "usuarios",
        "query": { "email": "joao@example.com" },
        "responseVariable": "usuario"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar Usuário",
        "parameters": {
          "message": "Usuário: {{usuario.nome}}"
        }
      }
    },
    {
      "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 seu MongoDB com autenticação 2. Execute o flow 3. Espere: "Usuário: Nome do Usuário"

collection (string, obrigatório)

O que é: Nome da coleção MongoDB onde a busca será realizada.

Flow completo para testar:

{
  "name": "Teste MongoDB FindOne - 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": "Buscar na Coleção",
        "operation": "findOne",
        "config": {
          "connectionString": "mongodb://localhost:27017",
          "database": "ecommerce"
        },
        "collection": "pedidos",
        "query": { "numero": "PED-2024-001" },
        "responseVariable": "pedido"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Mostrar Pedido",
        "parameters": {
          "message": "Pedido {{pedido.numero}}: R$ {{pedido.total}}"
        }
      }
    },
    {
      "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. Certifique-se que a coleção "pedidos" existe 2. Execute o flow 3. Espere: "Pedido PED-2024-001: R$ 150.00"

query (object, obrigatório)

O que é: Objeto de query MongoDB para encontrar o documento. Suporta todos os operadores MongoDB.

Flow completo para testar:

{
  "name": "Teste MongoDB FindOne - Query",
  "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": "Buscar por Email",
        "operation": "findOne",
        "config": {
          "connectionString": "mongodb://localhost:27017",
          "database": "crm"
        },
        "collection": "clientes",
        "query": {
          "email": "maria@example.com",
          "ativo": true
        },
        "responseVariable": "cliente"
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Encontrou?",
        "conditions": [
          {
            "variable": "cliente",
            "operator": "not_equals",
            "value": "null",
            "targetNode": "message_found"
          }
        ],
        "defaultTarget": "message_not_found"
      }
    },
    {
      "id": "message_found",
      "type": "message",
      "position": { "x": 700, "y": 50 },
      "data": {
        "label": "Encontrado",
        "parameters": {
          "message": "✅ Cliente: {{cliente.nome}}"
        }
      }
    },
    {
      "id": "message_not_found",
      "type": "message",
      "position": { "x": 700, "y": 150 },
      "data": {
        "label": "Não Encontrado",
        "parameters": {
          "message": "❌ Cliente não encontrado"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "mongodb_1" },
    { "source": "mongodb_1", "target": "condition_1" },
    { "source": "message_found", "target": "end_1" },
    { "source": "message_not_found", "target": "end_1" }
  ]
}

Teste: 1. Execute o flow com email existente 2. Espere: "✅ Cliente: Maria Silva"

responseVariable (string, opcional)

O que é: Nome da variável onde o documento encontrado será armazenado.

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

Flow completo para testar:

{
  "name": "Teste MongoDB FindOne - 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": "Buscar e Salvar",
        "operation": "findOne",
        "config": {
          "connectionString": "mongodb://localhost:27017",
          "database": "loja"
        },
        "collection": "configuracoes",
        "query": { "chave": "smtp_config" },
        "responseVariable": "config"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Usar Config",
        "parameters": {
          "message": "SMTP Host: {{config.host}} Port: {{config.port}}"
        }
      }
    },
    {
      "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: "SMTP Host: smtp.gmail.com Port: 587"

Parâmetros

Campo Tipo Obrigatório Descrição
operation string Sim Tipo de operação MongoDB ("findOne")
config object Sim Configuração de conexão MongoDB
collection string Sim Nome da coleção
query object Sim Filtro de busca para encontrar documento
responseVariable string Não Variável para armazenar documento

Exemplo 1: Validar Login de Usuário

Objetivo: Buscar usuário por email para validar login

JSON para Importar

{
  "name": "Validar Login de Usuário",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 250, "y": 100 },
      "data": {
        "label": "Solicitar Email",
        "parameters": {
          "message": "Digite seu email:",
          "variable": "email"
        }
      }
    },
    {
      "id": "mongodb_1",
      "type": "mongodb",
      "position": { "x": 400, "y": 100 },
      "data": {
        "label": "Buscar Usuário",
        "operation": "findOne",
        "config": {
          "connectionString": "mongodb://localhost:27017",
          "database": "auth"
        },
        "collection": "usuarios",
        "query": {
          "email": "{{email}}",
          "ativo": true
        },
        "responseVariable": "usuario"
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 550, "y": 100 },
      "data": {
        "label": "Usuário Existe?",
        "conditions": [
          {
            "variable": "usuario",
            "operator": "not_equals",
            "value": "null",
            "targetNode": "message_success"
          }
        ],
        "defaultTarget": "message_error"
      }
    },
    {
      "id": "message_success",
      "type": "message",
      "position": { "x": 700, "y": 50 },
      "data": {
        "label": "Login OK",
        "parameters": {
          "message": "✅ Bem-vindo, {{usuario.nome}}!"
        }
      }
    },
    {
      "id": "message_error",
      "type": "message",
      "position": { "x": 700, "y": 150 },
      "data": {
        "label": "Login Falhou",
        "parameters": {
          "message": "❌ Email não encontrado ou usuário inativo"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "mongodb_1" },
    { "source": "mongodb_1", "target": "condition_1" },
    { "source": "message_success", "target": "end_1" },
    { "source": "message_error", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Digite seu email:
Usuário: joao@example.com
Sistema: ✅ Bem-vindo, João Silva!

Exemplo 2: Buscar Produto por ID

Objetivo: Recuperar detalhes completos de um produto usando seu ObjectId

JSON para Importar

{
  "name": "Buscar Produto por ID",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 250, "y": 100 },
      "data": {
        "label": "Solicitar ID",
        "parameters": {
          "message": "Digite o ID do produto:",
          "variable": "produtoId"
        }
      }
    },
    {
      "id": "mongodb_1",
      "type": "mongodb",
      "position": { "x": 400, "y": 100 },
      "data": {
        "label": "Buscar Produto",
        "operation": "findOne",
        "config": {
          "connectionString": "mongodb://localhost:27017",
          "database": "ecommerce"
        },
        "collection": "produtos",
        "query": {
          "_id": "{{produtoId}}"
        },
        "responseVariable": "produto"
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 550, "y": 100 },
      "data": {
        "label": "Produto Existe?",
        "conditions": [
          {
            "variable": "produto",
            "operator": "not_equals",
            "value": "null",
            "targetNode": "message_details"
          }
        ],
        "defaultTarget": "message_not_found"
      }
    },
    {
      "id": "message_details",
      "type": "message",
      "position": { "x": 700, "y": 50 },
      "data": {
        "label": "Detalhes",
        "parameters": {
          "message": "📦 {{produto.nome}}\n💰 R$ {{produto.preco}}\n📊 Estoque: {{produto.estoque}}"
        }
      }
    },
    {
      "id": "message_not_found",
      "type": "message",
      "position": { "x": 700, "y": 150 },
      "data": {
        "label": "Não Encontrado",
        "parameters": {
          "message": "❌ Produto não encontrado"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "mongodb_1" },
    { "source": "mongodb_1", "target": "condition_1" },
    { "source": "message_details", "target": "end_1" },
    { "source": "message_not_found", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Digite o ID do produto:
Usuário: 507f1f77bcf86cd799439011
Sistema: 📦 Notebook Dell
💰 R$ 3499.00
📊 Estoque: 15

Exemplo 3: Verificar Duplicata Antes de Cadastrar

Objetivo: Verificar se email já existe antes de criar novo usuário

JSON para Importar

{
  "name": "Verificar Email Duplicado",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 250, "y": 100 },
      "data": {
        "label": "Solicitar Email",
        "parameters": {
          "message": "Digite seu email para cadastro:",
          "variable": "novoEmail"
        }
      }
    },
    {
      "id": "mongodb_check",
      "type": "mongodb",
      "position": { "x": 400, "y": 100 },
      "data": {
        "label": "Verificar Duplicata",
        "operation": "findOne",
        "config": {
          "connectionString": "mongodb://localhost:27017",
          "database": "usuarios"
        },
        "collection": "cadastros",
        "query": {
          "email": "{{novoEmail}}"
        },
        "responseVariable": "emailExistente"
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 550, "y": 100 },
      "data": {
        "label": "Email Já Existe?",
        "conditions": [
          {
            "variable": "emailExistente",
            "operator": "equals",
            "value": "null",
            "targetNode": "message_disponivel"
          }
        ],
        "defaultTarget": "message_duplicado"
      }
    },
    {
      "id": "message_disponivel",
      "type": "message",
      "position": { "x": 700, "y": 50 },
      "data": {
        "label": "Email Disponível",
        "parameters": {
          "message": "✅ Email {{novoEmail}} disponível! Pode prosseguir com cadastro."
        }
      }
    },
    {
      "id": "message_duplicado",
      "type": "message",
      "position": { "x": 700, "y": 150 },
      "data": {
        "label": "Email em Uso",
        "parameters": {
          "message": "❌ Email {{novoEmail}} já está em uso. Tente outro."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "mongodb_check" },
    { "source": "mongodb_check", "target": "condition_1" },
    { "source": "message_disponivel", "target": "end_1" },
    { "source": "message_duplicado", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Digite seu email para cadastro:
Usuário: novo@example.com
Sistema: ✅ Email novo@example.com disponível! Pode prosseguir com cadastro.

Resposta do Node

Quando documento é encontrado:

{
  "_id": "507f1f77bcf86cd799439011",
  "nome": "João Silva",
  "email": "joao@example.com",
  "ativo": true,
  "dataCriacao": "2024-01-15T10:30:00.000Z"
}

Quando documento NÃO é encontrado:

null

Boas Práticas

✅ SIM:

  • Use FIND_ONE quando precisa de apenas 1 documento (melhor performance que FIND)
  • Sempre verifique se o resultado não é null antes de acessar campos
  • Use _id para buscas quando possível (mais rápido devido ao índice)
  • Combine múltiplos critérios na query para buscas mais precisas
  • Armazene resultado em responseVariable para usar depois

❌ NÃO:

  • Não use FIND_ONE quando precisa de múltiplos documentos (use FIND)
  • Não assuma que sempre retornará um documento (pode ser null)
  • Não esqueça de tratar caso de documento não encontrado
  • Não use FIND_ONE em loops para buscar vários docs (use FIND com array de IDs)

Dicas

💡 Dica 1: O resultado pode ser null se nenhum documento atender aos critérios - sempre valide

💡 Dica 2: Strings de ObjectId são automaticamente convertidas ao buscar por _id

💡 Dica 3: Use FIND_ONE para validações de duplicata antes de INSERT

💡 Dica 4: Combine com CONDITION node para criar fluxos baseados em existência do documento

💡 Dica 5: Para campos únicos (email, CPF), crie índices únicos no MongoDB para garantir integridade

Próximos Nodes

→ MONGODB FIND - Buscar múltiplos documentos → MONGODB INSERT - Inserir novo documento → MONGODB FIND_ONE_AND_UPDATE - Buscar e atualizar em uma operação → MONGODB UPDATE - Atualizar documentos existentes