Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB

excluir

Nesta página

Definição

Comportamento
Exemplos
Saída

Definição

delete

O comando delete remove documentos de uma collection. Um único comando delete pode conter várias especificações de exclusão. Os métodos de exclusão fornecidos pelos drivers do MongoDB usam este comando internamente.

Alterado na versão 5.0.

Dica

No mongosh, este comando também pode ser executado através dos métodos de ajuda do deleteOne(), deleteMany() e findOneAndDelete() .

Os métodos auxiliares são convenientes para os usuários mongosh , mas podem não retornar o mesmo nível de informações que os comandos do banco de dados. Nos casos em que a conveniência não for necessária ou os campos de retorno adicionais forem necessários, use o comando de banco de dados.

O comando delete tem a seguinte sintaxe:

{
   delete: <collection>,
   deletes: [
      {
        q : <query>,
        limit : <integer>,
        collation: <document>,
        hint: <document|string>
      },
      ...
   ],
   comment: <any>,
   let: <document>, // Added in MongoDB 5.0
   ordered: <boolean>,
   writeConcern: { <write concern> },
   maxTimeMS: <integer>
}

O comando utiliza os seguintes campos:

Campo

Tipo

Descrição

excluir

string

O nome da coleção de destino.

exclui

variedade

Uma array de uma ou mais declarações de exclusão para executar na coleção denominada.

comment

qualquer

Opcional. Um comentário fornecido pelo usuário para anexar a este comando. Depois de definido, esse comentário aparece junto com os registros desse comando nos seguintes locais:

mensagens de log do mongod, no campo attr.command.cursor.comment.
Saída do perfil do banco de dados, no campo command.comment.
Saída de currentOp, no campo command.comment.

Um comentário pode ser qualquer tipo BSON válido (string, inteiro, objeto, array etc).

Novidades na versão 4.4.

deixei

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.

Observação

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

Para obter um exemplo completo usando let e variáveis, consulte Usar variáveis em let.

Novidades na versão 5,0.

encomendado

boleano

Opcional. Se true, quando uma instrução de exclusão falhar, retorne sem executar as instruções de exclusão restantes. Se false, quando uma instrução delete falhar, continue com as instruções delete restantes, se houver. O padrão é true.

Escreva preocupação

documento

Opcional. Um documento que expressa a write concern do comando delete . Omite o uso da detecção de gravação 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.

maxTimeMS

número inteiro não negativo

Opcional.

Especifica um limite de tempo em milissegundos. Se você não especificar um valor para maxTimeMS, as operações não atingirão o tempo limite. Um valor 0 especifica explicitamente o comportamento ilimitado padrão.

O MongoDB encerra as operações que excedem o limite de tempo alocado usando o mesmo mecanismo de db.killOp(). O MongoDB só encerra uma operação em um de seus pontos de interrupção designados.

Cada elemento do array deletes contém os seguintes campos:

Campo

Tipo

Descrição

documento

A query que corresponde aos documentos a serem excluídos.

limite

inteiro

O número de documentos correspondentes para excluir. Especifique um 0 para excluir todos os documentos correspondentes ou 1 para excluir um único documento.

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 collection 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.

Novidade na versão 3.4.

dica

Documento ou string

Opcional. Um documento ou string que especifica o índice a ser 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 ocorrerá erros.

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

Comportamento

Coleções partilhadas

Para usar operações de delete para uma coleção fragmentada que especifique a opção limit: 1 :

Se você segmentar apenas um fragmento, poderá usar uma chave de fragmento parcial na especificação da consulta ou,
Você pode fornecer a chave de estilhaço ou o campo _id na especificação de consulta.

Limites

O tamanho total de todas as queries (ou seja, os valores de campo q) na array deletes deve ser menor ou igual ao tamanho máximo do documento JSON.

O número total de documentos excluídos na array deletes deve ser menor ou igual ao tamanho máximo do volume.

Transações

excluir 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.

Exemplos

Limite o número de documentos excluídos

O exemplo a seguir exclui da coleção orders um documento que tenha o status igual a D especificando o limit de 1:

db.runCommand(
   {
      delete: "orders",
      deletes: [ { q: { status: "D" }, limit: 1 } ]
   }
)

O documento retornado mostra que o comando excluiu 1 documentos. Consulte Saída para detalhes.

{ "ok" : 1, "n" : 1 }

Observação

Para usar operações de delete para uma coleção fragmentada que especifique a opção limit: 1 :

Se você segmentar apenas um fragmento, poderá usar uma chave de fragmento parcial na especificação da consulta ou,
Você pode fornecer a chave de estilhaço ou o campo _id na especificação de consulta.

Excluir todos os documentos que correspondem a uma condição

O exemplo a seguir exclui da coleção orders todos os documentos que possuem o status igual a D especificando o limit de 0:

db.runCommand(
   {
      delete: "orders",
      deletes: [ { q: { status: "D" }, limit: 0 } ],
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

O documento devolvido mostra que o comando encontrou e excluiu 13 documentos. Consulte Saída para detalhes.

{ "ok" : 1, "n" : 13 }

Excluir todos os documentos de uma coleção

Exclua todos os documentos na coleção orders especificando uma condição de query vazia e um limit de 0:

db.runCommand(
   {
      delete: "orders",
      deletes: [ { q: { }, limit: 0 } ],
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

O documento devolvido mostra que o comando encontrou e excluiu 35 documentos no total. Consulte Saída para detalhes.

{ "ok" : 1, "n" : 35 }

Exclusão em massa

O seguinte exemplo executa múltiplas operações de exclusão na coleção orders:

db.runCommand(
   {
      delete: "orders",
      deletes: [
         { q: { status: "D" }, limit: 0 },
         { q: { cust_num: 99999, item: "abc123", status: "A" }, limit: 1 }
      ],
      ordered: false,
      writeConcern: { w: 1 }
   }
)

O documento devolvido mostra que o comando encontrou e excluiu 21 documentos no total para as duas declarações de exclusão. Consulte Saída para detalhes.

{ "ok" : 1, "n" : 21 }

Especifique o agrupamento

Novidade na versão 3.4.

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.

Uma coleção myColl possui os seguintes documentos:

{ _id: 1, category: "café", status: "A" }
{ _id: 2, category: "cafe", status: "a" }
{ _id: 3, category: "cafE", status: "a" }

A seguinte operação inclui a opção coleção:

db.runCommand({
   delete: "myColl",
   deletes: [
     { q: { category: "cafe", status: "a" }, limit: 0, collation: { locale: "fr", strength: 1 } }
   ]
})

Especificar `hint` para operações de exclusão

No mongosh, crie uma coleção do members com os seguintes documentos:

db.members.insertMany([
   { "_id" : 1, "member" : "abc123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60,  "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" },
   { "_id" : 3, "member" : "lmn123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 4, "member" : "pqr123", "status" : "D", "points" : 20,  "misc1" : "Deactivated", "misc2" : null },
   { "_id" : 5, "member" : "ijk123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 6, "member" : "cde123", "status" : "A", "points" : 86,  "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }
])

Crie os seguintes índices na coleção:

db.members.createIndex( { status: 1 } )
db.members.createIndex( { points: 1 } )

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

db.runCommand({
   delete: "members",
   deletes: [
     { q: { "points": { $lte: 20 }, "status": "P" }, limit: 0, hint: { status: 1 } }
   ]
})

Observação

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

Para visualizar o índice utilizado, execute o explain na operação:

db.runCommand(
   {
     explain: {
       delete: "members",
       deletes: [
         { q: { "points": { $lte: 20 }, "status": "P" }, limit: 0, hint: { status: 1 } }
       ]
     },
     verbosity: "queryPlanner"
   }
)

Usar variáveis em `let`

Novidades na versão 5,0.

Para definir variáveis que você pode acessar em outro lugar no comando, use a opção let .

Observação

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

Criar uma coleção cakeFlavors:

db.cakeFlavors.insertMany( [
   { _id: 1, flavor: "chocolate" },
   { _id: 2, flavor: "strawberry" },
   { _id: 3, flavor: "cherry" }
] )

O exemplo a seguir define uma variável targetFlavor em let e usa a variável para excluir o sabor do bolo de morango:

db.runCommand( {
   delete: db.cakeFlavors.getName(),
   deletes: [ {
      q: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
      limit: 1
   } ],
   let : { targetFlavor: "strawberry" }
} )

Saída

O documento devolvido contém um subconjunto dos seguintes campos:

delete.ok: O status do comando.

delete.n: O número de documentos excluídos.

delete.writeErrors

Uma array de documentos que contém informações sobre qualquer erro encontrado durante a operação de exclusão. A array writeErrors contém um documento de erro para cada instrução delete que apresenta erros.

Cada documento de erro contém as seguintes informações:

delete.writeErrors.index: Um inteiro que identifica a declaração de exclusão na array deletes , que usa um índice baseado em zero.

delete.writeErrors.code: Um valor inteiro identificando o erro.

delete.writeErrors.errmsg: Uma descrição do erro.

delete.writeConcernError

Documento que descreve o erro relacionado ao write concern e contém os campos:

delete.writeConcernError.code: Um valor inteiro que identifica a causa do erro de write concern.

delete.writeConcernError.errmsg: Uma descrição da causa do erro de write concern.

delete.writeConcernError.errInfo.writeConcern

O objeto de write concern usado para a operação correspondente. Para obter informações sobre os campos de objeto de write concern, consulte Especificação de write concern.

O objeto de write concern também pode conter o seguinte campo, indicando a origem da write concern:

delete.writeConcernError.errInfo.writeConcern.provenance

Um valor de string que indica a origem do write concern (conhecido como write concern provenance). A tabela a seguir mostra os valores possíveis para este campo e sua significância:

Proveniência	Descrição
`clientSupplied`	A preocupação de escrita foi especificada no aplicativo.
`customDefault`	A write concern originou-se de um valor padrão personalizado definido. Consulte `setDefaultRWConcern`.
`getLastErrorDefaults`	A write concern originada do campo `settings.getLastErrorDefaults` do conjunto de réplicas.
`implicitDefault`	A preocupação de gravação originou-se do servidor na ausência de todas as outras especificações de preocupação de gravação.

O seguinte é um documento de exemplo retornado para um comando delete bem-sucedido:

{ ok: 1, n: 1 }

A seguir está um documento de exemplo retornado para um comando delete que encontrou um erro porque especificou um índice inexistente no campo hint :

{
  n: 0,
  writeErrors: [
    {
      index: 0,
      code: 2,
      errmsg: 'error processing query: ns=test.products: hat $eq "bowler"\n' +
        'Sort: {}\n' +
        'Proj: {}\n' +
        ' planner returned error :: caused by :: hint provided does not correspond to an existing index'
    }
  ],
  ok: 1
}

← Comandos de operação de query e gravação

find →

excluir.css-134mg1q{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.css-6vrlzm{border-radius:0!important;display:initial!important;margin:initial!important;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

Definição

Dica

Observação

Comportamento

Coleções partilhadas

Limites

Transações

Importante

Exemplos

Limite o número de documentos excluídos

Observação

Excluir todos os documentos que correspondem a uma condição

Excluir todos os documentos de uma coleção

Exclusão em massa

Especifique o agrupamento

Especificar hint para operações de exclusão

Observação

Usar variáveis em let

Observação

Saída

excluir

Especificar `hint` para operações de exclusão

Usar variáveis em `let`