Dominando Operações CRUD no MongoDB: Um Guia Prático de Comandos

O MongoDB, um popular banco de dados NoSQL de documentos, forma a espinha dorsal de inúmeras aplicações modernas devido à sua flexibilidade, escalabilidade e desempenho. No centro da interação com qualquer banco de dados estão as operações fundamentais de Criar, Ler, Atualizar e Deletar (CRUD). Dominar esses comandos é essencial para qualquer pessoa que trabalhe com MongoDB, desde desenvolvedores criando novos recursos até administradores gerenciando dados.

Este guia usa uma pequena coleção users e mostra os comandos CRUD do MongoDB que você utiliza durante o trabalho real: adicionar um registro de um formulário de inscrição, encontrar o documento por trás de um ticket de suporte, alterar um campo sem sobrescrever o resto do documento e deletar dados sem apagar acidentalmente a coleção. Os exemplos usam mongosh, mas os mesmos filtros e operadores de atualização são válidos para drivers de aplicação.

Pré-requisitos

Antes de mergulhar nos comandos, certifique-se de ter:

• MongoDB instalado e em execução: Você pode baixá-lo do site oficial do MongoDB ou usar um serviço em nuvem como MongoDB Atlas.
• mongosh (MongoDB Shell) instalado: Esta é a interface JavaScript interativa para MongoDB.

Conectando ao MongoDB e Selecionando um Banco de Dados

Para começar, abra seu terminal ou prompt de comando e conecte-se à sua instância MongoDB usando mongosh:

mongosh

Uma vez conectado, você estará no banco de dados test padrão. Para alternar ou criar um novo banco de dados, use o comando use:

use myDatabase;

Se myDatabase não existir, o MongoDB o criará implicitamente quando você inserir seu primeiro documento em uma coleção dentro dele.

Operações de Criação (Inserir)

As operações de criação envolvem adicionar novos documentos a uma coleção. O MongoDB fornece métodos para inserir documentos únicos ou múltiplos.

1. db.collection.insertOne()

Este método insere um único documento em uma coleção. Se a coleção não existir, o MongoDB a cria.

// Selecione uma coleção chamada 'users'
db.users.insertOne({
  name: "Alice Smith",
  age: 30,
  city: "New York",
  email: "[email protected]",
  interests: ["reading", "hiking"]
});

A saída mostrará o status acknowledged e o insertedId do novo documento.

2. db.collection.insertMany()

Use este método para inserir vários documentos em uma coleção em uma única operação. Ele recebe um array de documentos.

db.users.insertMany([
  {
    name: "Bob Johnson",
    age: 24,
    city: "Los Angeles",
    email: "[email protected]",
    interests: ["coding", "gaming"]
  },
  {
    name: "Charlie Brown",
    age: 35,
    city: "New York",
    email: "[email protected]",
    interests: ["cooking", "photography"]
  },
  {
    name: "Diana Prince",
    age: 29,
    city: "London",
    email: "[email protected]",
    interests: ["fitness", "travel"]
  }
]);

Isso retornará um array de insertedIds para todos os documentos adicionados.

Dica: O MongoDB adiciona automaticamente um campo _id (um ObjectId único) a cada documento se você não fornecer um.

Operações de Leitura (Encontrar)

As operações de leitura envolvem consultar documentos de uma coleção. O método find() é sua principal ferramenta para isso.

1. db.collection.find()

a. Encontrar Todos os Documentos

Para recuperar todos os documentos em uma coleção, chame find() sem argumentos:

db.users.find();

b. Encontrar Documentos com um Filtro de Consulta

Passe um documento de consulta para find() para especificar critérios de seleção de documentos. Isso atua como uma cláusula WHERE no SQL.

// Encontrar usuários de New York
db.users.find({ city: "New York" });

// Encontrar usuários com mais de 25 anos
db.users.find({ age: { $gt: 25 } });

// Encontrar usuários com idade entre 25 e 35 (exclusive 35)
db.users.find({ age: { $gt: 25, $lt: 35 } });

// Encontrar usuários cujos interesses incluem 'coding'
db.users.find({ interests: "coding" });

// Encontrar usuários cujos interesses incluem AMBOS 'reading' e 'hiking'
db.users.find({ interests: { $all: ["reading", "hiking"] } });

// Encontrar usuários chamados Alice Smith OU de Londres
db.users.find({
  $or: [
    { name: "Alice Smith" },
    { city: "London" }
  ]
});

Operadores de consulta comuns:

• $eq: Igual a (padrão se nenhum operador for especificado)
• $ne: Diferente de
• $gt: Maior que
• $gte: Maior ou igual a
• $lt: Menor que
• $lte: Menor ou igual a
• $in: Corresponde a qualquer um dos valores especificados em um array
• $nin: Não corresponde a nenhum dos valores especificados em um array
• $and, $or, $not, $nor: Operadores lógicos

c. Projeção: Selecionando Campos Específicos

Para retornar apenas um subconjunto de campos, passe um documento de projeção como segundo argumento para find(). Um valor de 1 inclui o campo, 0 o exclui. O campo _id é incluído por padrão, a menos que seja explicitamente excluído.

// Retornar apenas nome e email, excluir _id
db.users.find({ city: "New York" }, { name: 1, email: 1, _id: 0 });

d. Ordenação, Limitação e Pulo

Encadear métodos permite consultas mais complexas:

// Ordenar por idade em ordem decrescente (1 para crescente, -1 para decrescente)
db.users.find().sort({ age: -1 });

// Limitar resultados a 2 documentos
db.users.find().limit(2);

// Pular os primeiros 2 documentos e retornar o restante
db.users.find().skip(2);

// Combinar operações: Encontrar usuários de New York, ordenar por idade, pular 1, limitar 1
db.users.find({ city: "New York" }).sort({ age: 1 }).skip(1).limit(1);

2. db.collection.findOne()

Este método retorna um único documento que corresponde aos critérios da consulta. Se vários documentos corresponderem, ele retorna o primeiro encontrado.

db.users.findOne({ name: "Alice Smith" });

Operações de Atualização

As operações de atualização modificam documentos existentes em uma coleção. Você pode atualizar um único documento, vários documentos ou até mesmo substituir um documento inteiro.

1. db.collection.updateOne()

Atualiza um único documento que corresponde aos critérios do filtro.

// Atualizar a cidade de Alice para 'San Francisco'
db.users.updateOne(
  { name: "Alice Smith" },
  { $set: { city: "San Francisco", lastUpdated: new Date() } }
);

2. db.collection.updateMany()

Atualiza todos os documentos que correspondem aos critérios do filtro.

// Incrementar a idade de todos os usuários em New York em 1
db.users.updateMany(
  { city: "New York" },
  { $inc: { age: 1 } }
);

// Adicionar um novo interesse 'reading' para usuários que ainda não o têm
db.users.updateMany(
  {}, // Aplicar a todos os documentos
  { $addToSet: { interests: "reading" } }
);

// Remover 'gaming' dos interesses de Bob Johnson
db.users.updateOne(
  { name: "Bob Johnson" },
  { $pull: { interests: "gaming" } }
);

Operadores de Atualização Comuns:

• $set: Define o valor de um campo em um documento. Cria o campo se ele não existir.
• $inc: Incrementa o valor de um campo em uma quantia especificada.
• $unset: Remove um campo de um documento.
• $push: Adiciona um valor a um campo de array.
• $pull: Remove todas as instâncias de um valor ou valores que correspondem a uma consulta especificada de um array.
• $addToSet: Adiciona um valor a um array apenas se o valor ainda não estiver presente.

3. db.collection.replaceOne()

Substitui um único documento que corresponde aos critérios do filtro por um novo documento. O campo _id do documento sendo substituído não pode ser alterado.

// Substituir o documento de Bob Johnson completamente
db.users.replaceOne(
  { name: "Bob Johnson" },
  {
    name: "Robert Johnson",
    occupation: "Software Engineer",
    status: "active",
    email: "[email protected]"
  }
);

Opção Upsert

Tanto updateOne() quanto updateMany() suportam uma opção upsert. Se definida como true, e nenhum documento corresponder ao filtro, o MongoDB inserirá um novo documento baseado na consulta e nas operações de atualização.

db.users.updateOne(
  { name: "David Lee" },
  { $set: { age: 28, city: "Seattle" } },
  { upsert: true } // Se David Lee não existir, crie-o
);

Operações de Exclusão

As operações de exclusão removem documentos de uma coleção. Seja extremamente cuidadoso com operações de exclusão, pois elas são irreversíveis.

1. db.collection.deleteOne()

Exclui no máximo um documento que corresponde ao filtro especificado.

// Excluir o usuário chamado 'Robert Johnson' (anteriormente 'Bob Johnson')
db.users.deleteOne({ name: "Robert Johnson" });

2. db.collection.deleteMany()

Exclui todos os documentos que correspondem ao filtro especificado.

// Excluir todos os usuários de Londres
db.users.deleteMany({ city: "London" });

Aviso: Para excluir todos os documentos em uma coleção, use um filtro vazio {}. Seja extremamente cauteloso, pois esta operação não pode ser desfeita:

db.users.deleteMany({}); // Exclui todos os documentos na coleção 'users'

3. db.collection.drop()

Este método remove permanentemente uma coleção inteira do banco de dados, incluindo todos os seus documentos e índices.

db.users.drop(); // Exclui toda a coleção 'users'

Aviso: Descartar uma coleção é uma operação altamente destrutiva. Certifique-se de ter backups adequados ou esteja absolutamente certo antes de executar este comando.

Melhores Práticas para CRUD no MongoDB

• Indexação: Para campos consultados com frequência, crie índices para acelerar significativamente as operações de leitura. db.collection.createIndex({ fieldName: 1 }).
• Projeções: Recupere apenas os dados necessários. Usar projeções ({ field: 1 }) reduz o uso de largura de banda e memória.
• Operações em Lote: Ao inserir, atualizar ou excluir muitos documentos, use insertMany(), updateMany() e deleteMany() em vez de operações individuais para reduzir a sobrecarga.
• Entenda os Operadores: Familiarize-se com o rico conjunto de operadores de consulta e atualização do MongoDB. Eles oferecem maneiras poderosas de manipular seus dados.
• Tratamento de Erros: Em uma aplicação de produção, sempre implemente um tratamento de erros robusto para suas operações de banco de dados.
• Design de Esquema: Embora o MongoDB não tenha esquema, um design de esquema cuidadoso é crucial para consultas eficientes e consistência de dados.

Uma Maneira Mais Segura de Praticar CRUD em um Banco de Dados Real

A parte perigosa do CRUD no MongoDB não é a sintaxe. É executar um filtro amplo no banco de dados errado, especialmente com updateMany() ou deleteMany(). Gosto de usar um hábito de três etapas para qualquer escrita que toque em dados existentes.

Primeiro, execute o filtro como uma leitura:

db.users.find(
  { city: "New York", status: "inactive" },
  { name: 1, email: 1, city: 1, status: 1 }
).limit(20);

Se a pré-visualização retornar documentos que você não esperava, pare aí. Corrija o filtro antes de pensar na atualização. Se não retornar nada, certifique-se de que está no banco de dados correto com db.getName() e que os nomes dos campos correspondem aos documentos reais.

Segundo, conte os documentos correspondentes:

db.users.countDocuments({ city: "New York", status: "inactive" });

Isso dá uma noção aproximada do impacto. Se você esperava 12 usuários e a contagem diz 12.000, o comando está dizendo que algo está errado. Uma contagem não substitui um backup, mas é uma proteção barata.

Terceiro, execute a escrita com o comando mais restrito que se adequa ao trabalho. Use updateOne() quando um email único, ID de conta ou _id deve corresponder a um documento. Use updateMany() apenas quando alterar um segmento inteiro for intencional.

db.users.updateMany(
  { city: "New York", status: "inactive" },
  {
    $set: {
      marketingEmailEnabled: false,
      updatedBy: "ops-maintenance-2025-11-04"
    }
  }
);

Adicionar um updatedBy, updatedAt ou nota de manutenção não é exigido pelo MongoDB, mas ajuda mais tarde quando alguém perguntar por que um campo mudou.

Erros Comuns que Causam Bugs Reais

O primeiro erro é substituir um documento quando você pretendia atualizar um campo. Este comando parece inofensivo, mas substitui todo o documento correspondente apenas pelos campos mostrados:

db.users.updateOne(
  { email: "[email protected]" },
  { city: "Boston" }
);

O MongoDB moderno espera operadores de atualização para documentos de atualização, a menos que você esteja usando métodos de substituição, então este padrão pode falhar dependendo do comando e da versão. O modelo mental mais seguro é simples: se você está alterando campos no lugar, use $set, $unset, $inc, $push, $pull ou outro operador de atualização.

db.users.updateOne(
  { email: "[email protected]" },
  { $set: { city: "Boston" } }
);

O segundo erro é consultar arrays como se a ordem sempre importasse. { interests: ["reading", "hiking"] } corresponde exatamente a um array. { interests: "reading" } corresponde a documentos onde o array contém esse valor. { interests: { $all: ["reading", "hiking"] } } corresponde a arrays que contêm ambos os valores, independentemente da ordem. Essas são três perguntas diferentes.

O terceiro erro é assumir que findOne() retorna "o correto" quando o filtro não é único. Se você executar:

db.users.findOne({ city: "New York" });

O MongoDB retorna um documento correspondente, mas sem uma ordenação você não deve tratar esse documento como o mais novo, mais antigo, mais importante ou mais representativo. Se a ordem importa, diga:

db.users.find({ city: "New York" }).sort({ createdAt: -1 }).limit(1);

O quarto erro é pular índices até que a aplicação já esteja lenta. Uma coleção com alguns milhares de documentos pode esconder uma consulta ineficiente. A mesma consulta pode se tornar dolorosa quando a coleção cresce. Se a aplicação frequentemente encontra usuários por email, crie um índice único quando o modelo de dados permitir:

db.users.createIndex({ email: 1 }, { unique: true });

Isso protege tanto o desempenho quanto a qualidade dos dados. Se emails duplicados já existirem, o comando falhará, que é exatamente o tipo de problema que você quer descobrir antes de confiar no email como identificador.

Verificando o que uma Escrita Realmente Fez

Os resultados de escrita do MongoDB valem a pena ser lidos. Após uma atualização, observe matchedCount e modifiedCount. matchedCount informa quantos documentos corresponderam ao filtro. modifiedCount informa quantos foram realmente alterados.

Se matchedCount for 1 e modifiedCount for 0, o comando ainda pode estar correto. Talvez o campo já tivesse o valor solicitado. Se matchedCount for 0, seu filtro não correspondeu a nada. Isso é comum quando um _id é passado como string em vez de um ObjectId.

db.users.findOne({ _id: ObjectId("6650f1e59d0a41a37c2d8011") });

Para exclusões, verifique deletedCount. Se você esperava um documento excluído e o resultado diz deletedCount: 0, não execute imediatamente uma exclusão mais ampla. Reconfira o banco de dados, a coleção e o filtro.

Quando CRUD Não é Suficiente

Comandos CRUD básicos cobrem a maioria do trabalho diário com dados, mas algumas tarefas precisam de ferramentas mais fortes. Se você está atualizando várias coleções que devem permanecer consistentes juntas, veja transações em conjuntos de réplicas ou clusters fragmentados. Se você está remodelando dados em muitos documentos, um pipeline de agregação pode ser mais claro do que uma longa série de loops do lado do cliente. Se você está migrando dados de produção, use um script com registro, modo de simulação, backups e um plano de reversão.

Para operações pontuais em mongosh, mantenha os comandos legíveis. Uma linha engenhosa é mais difícil de revisar e mais difícil de se recuperar. Em produção, comandos simples são geralmente melhores.

Os comandos CRUD do MongoDB são diretos depois que você se acostuma com documentos, filtros e operadores de atualização. A habilidade que importa no trabalho real é ser deliberado: pré-visualizar o filtro, contar o impacto, escolher o comando de escrita mais restrito, ler o resultado e deixar contexto suficiente para que a próxima pessoa possa entender o que mudou.