$inc

Definição

$inc

O operador $inc incrementa um campo por um valor especificado.

Compatibilidade

Você pode utilizar o $inc para implantações hospedadas nos seguintes ambientes:

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

• 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 operador $inc tem o seguinte formato:

{ $inc: { <field1>: <amount1>, <field2>: <amount2>, ... } }

Para especificar um <field> em um documento incorporado ou em uma array, use a notação de ponto.

Comportamento

A partir do MongoDB 5.0, os operadores de atualização processam campos de documento com nomes baseados em cadeia de caracteres em ordem lexicográfica. Os campos com nomes numéricos são processados em ordem numérica. Consulte Atualizar Comportamento de Operadores para detalhes.

O operador $inc aceita valores positivos e negativos.

Se o campo não existir, $inc criará o campo e definirá o campo para o valor especificado.

O uso do operador $inc em um campo com um valor nulo gerará um erro.

$inc é uma operação atômica dentro de um único documento.

A partir do MongoDB 5.0, mongod não gera mais um erro ao usar um operador de atualização como $inc com uma expressão de operando vazia ( { } ). Uma atualização vazia não resulta em alteração e nenhuma entrada no oplog é criada (o que significa que é sem operação).

Exemplo

Crie a coleção products:

db.products.insertOne(
   {
     _id: 1,
     sku: "abc123",
     quantity: 10,
     metrics: { orders: 2, ratings: 3.5 }
   }
)

A seguinte operação updateOne() utiliza o operador $inc para:

• aumentar o campo "metrics.orders" em 1

• aumentar o campo quantity em -2 (que diminui quantity)

db.products.updateOne(
   { sku: "abc123" },
   { $inc: { quantity: -2, "metrics.orders": 1 } }
)

O documento atualizado se parece com:

{
  _id: 1,
  sku: 'abc123',
  quantity: 8,
  metrics: { orders: 3, ratings: 3.5 }
}