Make the MongoDB docs better! We value your opinion. Share your feedback for a chance to win $100.
Click here >
Menu Docs
Página inicial do Docs
/
Desenvolvimento
/
Métodos de mongosh
Página inicial do Docs
/
Desenvolvimento
/
Métodos de mongosh
Página inicial do Docs
/
Desenvolvimento
/
Métodos de mongosh

db.coleção.deleteOne() (método mongosh)

MongoDB com drivers

Esta página documenta um método mongosh. Para ver o método equivalente em um driver MongoDB, consulte a página correspondente da sua linguagem de programação:

C#Java SyncNode.jsPyMongoC++GoJava RSKotlin CoroutineKotlin SyncPHPMongoidRustScala

Definição

db.collection.deleteOne()

Remove um único documento de uma coleção.

Retorna:Um documento contendo:

  • Um booleano acknowledged como true se a operação foi executada com preocupação de gravação ou se a preocupação de gravação false foi desativada

  • deletedCount contendo o número de documentos excluídos

Compatibilidade

Esse método está disponível em implantações hospedadas nos seguintes ambientes:

  • MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem

Observação

Este comando é aceito em todos os clusters do MongoDB Atlas. Para obter informações sobre o suporte do Atlas a todos os comandos, consulte Comandos não suportados.

  • MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB

  • MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Sintaxe

O método deleteOne() tem o seguinte formato:

db.collection.deleteOne(
    <filter>,
    {
      writeConcern: <document>,
      collation: <document>,
      hint: <document|string>,
      maxTimeMS: <int>,
      let: <document>
    }
)

O método deleteOne() utiliza os seguintes parâmetros:

Parâmetro
Tipo
Descrição

filtro, filtro

documento

Define os critérios de exclusão utilizando um predicado de query.

Especifique um documento vazio { } para excluir o primeiro documento retornado na coleção.

writeConcern

documento

Opcional. Um documento que expressa o write concern. Omitir para usar o write concern padrão.

Não defina explicitamente a preocupação de gravação para a operação se for executada em uma transação. Para usar write concern com transações, consulte Transações e write concern.

agrupamento

documento

Opcional.

Especifica o agrupamento a ser usado para a operação.

A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para letras maiúsculas e marcas de acento.

A opção de agrupamento tem a seguinte sintaxe:

collation: {
    locale: <string>,
    caseLevel: <boolean>,
    caseFirst: <string>,
    strength: <int>,
    numericOrdering: <boolean>,
    alternate: <string>,
    maxVariable: <string>,
    backwards: <boolean>
 }

Ao especificar agrupamento, o campo locale é obrigatório; todos os outros campos de agrupamento são opcionais. Para obter descrições dos campos, consulte Documento de agrupamento.

Se o agrupamento não for especificado, mas a coleção tiver um agrupamento padrão (consulte db.createCollection()), a operação usará o agrupamento especificado para a coleção.

Se nenhum agrupamento for especificado para a coleção ou para as operações, o MongoDB usa a comparação binária simples usada nas versões anteriores para comparações de strings.

Você não pode especificar vários agrupamentos para uma operação. Por exemplo, você não pode especificar agrupamentos diferentes por campo ou, se estiver realizando uma busca com uma classificação, não poderá usar um agrupamento para a busca e outro para a classificação.

dica

documento

Opcional. Um documento ou string que especifica o índice aser usado para dar suporte ao predicado de query.

A opção pode usar um documento de especificação de índice ou a string do nome do índice.

Se você especificar um índice que não existe, a operação emitirá erros.

Para um exemplo, consulte Especificar hint para Excluir Operações.

maxTimeMS

inteiro

Opcional. Especifica o limite de tempo, em milésimos de segundo, para que a operação de excluir seja executada antes de atingir o tempo limite.

let

Documento

Opcional.

Especifica um documento com uma lista de variáveis. Isso permite que você melhore a legibilidade do comando separando as variáveis do texto da query.

A sintaxe do documento é:

{
  <variable_name_1>: <expression_1>,
  ...,
  <variable_name_n>: <expression_n>
}

A variável é definida para o valor retornado pela expressão e não pode ser alterada posteriormente.

Para acessar o valor de uma variável no comando, use o prefixo de dois cifrões ($$) junto com o nome da variável no formato $$<variable_name>. Por exemplo: $$targetTotal.

Para usar uma variável para filtrar os resultados, você deve acessar a variável dentro do operador $expr.

Para ver um exemplo completo com let e variáveis, consulte Atualizar com variáveis let.

Comportamento

Ordem de exclusão

db.collection.deleteOne() exclui o primeiro documento que corresponde ao filtro. Use um campo que faça parte de um índice único, como _id, para exclusões precisas.

Coleções fragmentadas

Para usar db.collection.deleteOne() em uma coleção fragmentada:

  • Se você segmentar apenas um fragmento, poderá usar uma chave de fragmento parcial na especificação da consulta.

  • Você não precisa fornecer a chave de estilhaço ou o campo _id na especificação de consulta, porque deleteOne() usa inerentemente um limite de 1.

Transações

db.collection.deleteOne() pode ser usado dentro de transações distribuídas.

Não defina explicitamente a preocupação de gravação para a operação se for executada em uma transação. Para usar write concern com transações, consulte Transações e write concern.

Importante

Na maioria dos casos, uma transação distribuída incorre em um custo de desempenho maior do que as gravações de um único documento, e a disponibilidade de transações distribuídas não deve substituir o design eficaz do esquema. Em muitos cenários, o modelo de dados desnormalizado (documentos e arrays incorporados) continuará a ser ideal para seus dados e casos de uso. Ou seja, para muitos cenários, modelar seus dados adequadamente minimizará a necessidade de transações distribuídas.

Para considerações adicionais sobre o uso de transações (como limite de tempo de execução e limite de tamanho do oplog), consulte também Considerações de produção.

Entradas de oplog

Se uma operação db.collection.deleteOne() excluir um documento com êxito, a operação adicionará uma entrada no oplog (registro de operações). Se a operação falhar ou não localizar um documento a ser excluído, a operação não adicionará uma entrada no oplog.

Exemplos

Os exemplos nesta página usam dados do conjunto de dados de amostra sample_mflix. Para obter detalhes sobre como carregar esse conjunto de dados em sua implantação autogerenciada do MongoDB , consulte Carregar o conjunto de dados de amostra. Se você fez modificações nos bancos de dados de amostra, talvez seja necessário descartar e recriar os bancos de dados para executar os exemplos nesta página.

Excluir um único documento

A operação a seguir exclui o primeiro document em que year é anterior a 1910:

db.movies.deleteOne( { year: { $lt: 1910 } } )
{ acknowledged: true, deletedCount: 1 }

deleteOne() com um tempo limite e variáveis de consulta

A operação a seguir exclui o primeiro document em que year é anterior à variável cutoffYear e define um limite de tempo de 3 segundos:

db.movies.deleteOne(
   { $expr: { $lt: ["$year", "$$cutoffYear"] } },
   {
      let: { cutoffYear: 1910 },
      maxTimeMS: 3000
   }
)
{ acknowledged: true, deletedCount: 1 }

deleteOne() com Write concern

Dado um conjunto de réplicas de três membros, a operação a seguir especifica um w de majority e wtimeout de 100

db.movies.deleteOne(
   { title: "A Corner in Wheat" },
   { writeConcern: { w: "majority", wtimeout: 100 } }
)
{ acknowledged: true, deletedCount: 1 }

Especifique o agrupamento

A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para letras maiúsculas e marcas de acento.

A operação a seguir usa a opção de agrupamento com locale em inglês e strength: 2, que faz comparações sem distinção entre maiúsculas e minúsculas. O filtro title: "the dark knight" corresponde ao document com o título "The Dark Knight" na coleção:

db.movies.deleteOne(
   { title: "the dark knight" },
   { collation: { locale: "en", strength: 2 } }
)
{ acknowledged: true, deletedCount: 1 }

Especificar hint para operações de exclusão

Crie índices nos campos rated e metacritic:

db.movies.createIndex( { rated: 1 } )
db.movies.createIndex( { metacritic: 1 } )

A seguinte operação de exclusão sugere explicitamente o uso do índice { rated: 1 }:

db.movies.deleteOne(
   { metacritic: { $lte: 15 }, rated: "PG" },
   { hint: { rated: 1 } }
)
{ acknowledged: true, deletedCount: 1 }

Observação

Se você especificar um índice que não existe, a operação emitirá erros.

Para visualizar os índices usados, é possível usar o pipeline $indexStats :

db.movies.aggregate( [ { $indexStats: { } }, { $sort: { name: 1 } } ] )

O campo accesses.ops na saída $indexStats indica o número de operações que utilizaram o índice.

Dica

Para excluir vários documentos, consulte db.collection.deleteMany()

Voltar

db.collection.deleteMany

Próximo

db.collection.distinct

Nesta página