Nomes de campo com pontos (.) e cifrões ($)

Visão geral

O MongoDB 5.0 adiciona suporte aprimorado para nomes de campo que são prefixados em dólar ($) ou que contêm períodos (.). As regras de validação para armazenar dados foram atualizadas para facilitar o trabalho com fontes de dados que usam esses caracteres.

Na maioria dos casos, os dados que foram armazenados utilizando nomes de campo como estes não são diretamente acessíveis. Você precisa utilizar métodos de assistente como $getField, $setField e $literal em consultas que acessam estes campos.

As regras de validação de nome de campo não são as mesmas para todos os tipos de operações de armazenamento. Esta página resume como diferentes operações de inserção e atualização lidam com nomes de campos prefixados em dólares ($).

Inserir operações

Campos prefixados em dólar ($) são permitidos como nomes de campo de nível superior e aninhados para inserções.

db.sales.insertOne( {
   "$price": 50.00,
   "quantity": 30
} )

Campos prefixados em dólar ($) são permitidos em inserções usando palavras que, de outra forma, estariam reservadas. Nomes de operadores como $inc podem ser usados como nomes de campos, assim como palavras como id, db e ref.

db.books.insertOne( {
   "$id": "h1961-01",
   "location": {
      "$db": "novels",
      "$ref": "2007042768",
      "$inc": true
} } )

Uma atualização que cria um novo documento durante um upsert é tratada como insert em vez de update para a validação do nome do campo. Upserts podem aceitar campos prefixados em dólar ($). No entanto, os upserts são um caso especial e operações de atualização semelhantes podem causar um erro se a parte match da atualização selecionar um documento existente.

Esse exemplo de código tem upsert: true, então ele inserirá um novo documento se a collection ainda não contiver um documento que corresponda ao termo de query { "date": "2021-07-07" }. Se esse código de amostra corresponder a um documento existente, a atualização falhará porque $hotel é prefixado em dólar ($).

db.expenses.updateOne(
   { "date": "2021-07-07" },
   { $set: {
      "phone": 25.17,
      "$hotel": 320.10
   } },
   { upsert: true }
)

Atualizações que substituem documentos

Os operadores de atualização substituem os campos existentes por novos documentos ou modificam esses campos. Nos casos em que a atualização executar uma substituição, campos prefixados em dólar ($) não são permitidos como nomes de campo de nível superior.

Considere um documento como

{
   "_id": "E123",
   "address": {
      "$number": 123,
      "$street": "Elm Road"
   },
   "$rooms": {
      "br": 2,
      "bath": 1
   }
}

Você poderia usar um operador de atualização que substitui um documento existente para modificar o campo address.$street, mas não poderia atualizar o campo $rooms dessa forma.

db.housing.updateOne(
   { "_id": "E123" },
   { $set: { "address.$street": "Elm Ave" } }
)

Use $setField como parte de um pipeline de agregação para atualizar campos prefixados de dólar de nível superior ($) como $rooms.

Atualizações que modificam documentos

Quando uma atualização modifica, em vez de substituir, os campos de documento existentes, os campos prefixados em dólar ($) podem ser nomes de campo de nível superior. Os subcampos podem ser acessados diretamente, mas você precisa de um método auxiliar para acessar os campos de nível superior.

Considere uma coleção com documentos como este registro de inventário:

{
   _id: ObjectId("610023ad7d58ecda39b8d161"),
   "part": "AB305",
   "$bin": 200,
   "quantity": 100,
   "pricing": { sale: true, "$discount": 60 }
}

O subcampo pricing.$discount pode ser consultado diretamente.

db.inventory.findAndModify( {
    query: { "part": { $eq: "AB305" } },
    update: { $inc: { "pricing.$discount": 10 } }
} )

Utilize $getField e $literal para acessar o valor do campo de nível superior $bin.

db.inventory.findAndModify( {
   query: { $expr: {
      $eq: [ { $getField: { $literal: "$bin" } }, 200 ]
   } },
   update: { $inc: { "quantity": 10 } }
} )

Atualizações que usam aggregation pipelines

Use $setField, $getFielde $literal no estágio $replaceWith para modificar campos prefixados em dólar ($) em um pipeline de agregação.

Considere uma collection de registros escolares como:

{
   "_id": 100001,
   "$term": "fall",
   "registered": true,
   "grade": 4
}

Crie uma nova collection para o semestre da primavera usando um pipeline para atualizar o campo $term prefixado em dólar ($).

db.school.aggregate( [
   { $match: { "registered": true } },
   { $replaceWith: {
      $setField: {
         field: { $literal: "$term" },
         input: "$$ROOT",
         value: "spring"
   } } },
   { $out: "spring2022" }
] )

Restrições gerais

Além das regras de validação de armazenamento acima, há algumas restrições gerais sobre o uso de nomes de campos prefixados em dólar ($). Esses campos não podem:

• Ser indexado

• Ser usado como parte de uma chave de fragmento

• Ser validados usando $jsonSchema

• Ser modificados com uma sequência de escape

• Ser usado com criptografia de nível de campo

• Ser usado como subcampo em um documento _id