Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/
Operações de agregação
/
Referência de agregação
/
Operadores de agregação

$getField (agregação)

Nesta página

  • Definição
  • Sintaxe
  • Comportamento
  • Exemplos

Definição

$getField

Novidades na versão 5.0.

Retorna o valor de um campo especificado de um documento. Se você não especificar um objeto, $getField retornará o valor do campo de $$CURRENT.

Você pode usar $getField para recuperar o valor de campos com nomes que contenham pontos (.) ou comecem com cifrões ($).

Dica

Use $setField para adicionar ou atualizar campos com nomes que contenham cifrões ($) ou pontos (.).

Sintaxe

$getField tem a seguinte sintaxe:

{
  $getField: {
    field: <String>,
    input: <Object>
  }
}
Campo
Tipo
Descrição
field
String

Campo no objeto input para o qual você deseja retornar um valor. O field pode ser qualquer expressão válida que resolva para uma constante de string.

Se o field começar com um sinal de dólar ($), coloque o nome do campo dentro de uma expressão $literal para retornar seu valor.

input
Objeto

Padrão: $$CURRENT

Uma expressão válida que contém o field para o qual você deseja retornar um valor. input deve resolver para um objeto, missing, null ou undefined. Se omitido, o padrão é o documento atualmente sendo processado no pipeline ($$CURRENT).

$getField tem a seguinte sintaxe reduzida para recuperar valores de campo de $$CURRENT:

{
  $getField: <String>
}

Para esta sintaxe, o argumento é equivalente ao valor de field descrito acima.

Comportamento

  • Se field resolver para algo diferente de uma constante de string, $getField retornará um erro.

  • Se o field que você especificar não estiver presente no objeto input ou em $$CURRENT se você não especificar um objeto input, $getField retornará missing.

  • Se input avaliar como missing, undefined ou null, $getField retornará null.

  • Se input for avaliado como algo diferente de um objeto, missing, undefined ou null, $getField retornará um erro.

  • $getField não atravessa implicitamente objetos ou arrays. Por exemplo, $getField avalia um valor field de a.b.c como um campo de nível superior a.b.c em vez de um campo aninhado { a: { b: { c: } } }.

Dica

Veja também:

Considerações para nomes de campo

Exemplos

Campos de query que contêm pontos (.)

Considere uma coleção inventory com os seguintes documentos:

{ "_id" : 1, "item" : "sweatshirt", "price.usd": 45.99, qty: 300 }
{ "_id" : 2, "item" : "winter coat", "price.usd": 499.99, qty: 200 }
{ "_id" : 3, "item" : "sun dress", "price.usd": 199.99, qty: 250 }
{ "_id" : 4, "item" : "leather boots", "price.usd": 249.99, qty: 300 }
{ "_id" : 5, "item" : "bow tie", "price.usd": 9.99, qty: 180 }

A operação a seguir utiliza os operadores $getField e $gt para descobrir quais produtos têm price.usd maior que 200:

db.inventory.aggregate( [
  {
    $match:
      { $expr:
        { $gt: [ { $getField: "price.usd" }, 200 ] }
      }
   }
] )

A operação retorna os seguintes resultados:

[
  { _id: 2, item: 'winter coat', qty: 200, 'price.usd': 499.99 },
  { _id: 4, item: 'leather boots', qty: 300, 'price.usd': 249.99 }
]

Campos de consulta que começam com um cifrão ($)

Considere uma coleção inventory com os seguintes documentos:

{ "_id" : 1, "item" : "sweatshirt", "$price": 45.99, qty: 300 }
{ "_id" : 2, "item" : "winter coat", "$price": 499.99, qty: 200 }
{ "_id" : 3, "item" : "sun dress", "$price": 199.99, qty: 250 }
{ "_id" : 4, "item" : "leather boots", "$price": 249.99, qty: 300 }
{ "_id" : 5, "item" : "bow tie", "$price": 9.99, qty: 180 }

A operação a seguir usa os operadores $getField, $gt e $literal para descobrir quais produtos têm $price maior que 200:

db.inventory.aggregate( [
  {
    $match:
      { $expr:
        { $gt: [ { $getField: {$literal: "$price" } }, 200 ] }
      }
   }
] )

A operação retorna os seguintes resultados:

[
  { _id: 2, item: 'winter coat', qty: 200, '$price': 499.99 },
  { _id: 4, item: 'leather boots', qty: 300, '$price': 249.99 }
]

Consultar um campo em um subdocumento

Cria uma collection inventory com os seguintes documentos:

db.inventory.insertMany( [
   { "_id" : 1, "item" : "sweatshirt",  "price.usd": 45.99,
     "quantity": { "$large": 50, "$medium": 50, "$small": 25 }
   },
   { "_id" : 2, "item" : "winter coat", "price.usd": 499.99,
     "quantity": { "$large": 35, "$medium": 35, "$small": 35 }
   },
   { "_id" : 3, "item" : "sun dress", "price.usd": 199.99,
     "quantity": { "$large": 45, "$medium": 40, "$small": 5 }
   },
   { "_id" : 4, "item" : "leather boots", "price.usd": 249.99,
     "quantity": { "$large": 20, "$medium": 30, "$small": 40 }
   },
   { "_id" : 5, "item" : "bow tie", "price.usd": 9.99,
     "quantity": { "$large": 0, "$medium": 10, "$small": 75 }
   }
] )

A operação seguinte retorna documentos onde o número de $small itens é menor ou igual a 20.

db.inventory.aggregate( [
   { $match:
      { $expr:
         { $lte:
            [
               { $getField:
                  { field: { $literal: "$small" },
                    input: "$quantity"
                  }
               },
               20
            ]
         }
      }
   }
] )

Use estes operadores para consultar a coleção:

  • O operador $lte localiza valores menores ou iguais a 20.

  • $getField requer parâmetros field e input explícitos porque o campo $small faz parte de um subdocumento.

  • $getField utiliza $literal para avaliar "$small", pois o nome do campo tem um sinal de dólar ($).

Saída de exemplo:

[
  {
    _id: 3,
    item: 'sun dress',
    'price.usd': 199.99,
    quantity: { '$large': 45, '$medium': 40, '$small': 5 }
  }
]
← $function (agregação)
$gt (agregação) →

Nesta página