Docs Menu

$getField (aggregation)

On this page

  • Definition
  • Syntax
  • Behavior
  • Examples
$getField

New in version 5.0.

Returns the value of a specified field from a document. If you don't specify an object, $getField returns the value of the field from $$CURRENT.

You can use $getField to retrieve the value of fields with names that contain periods (.) or start with dollar signs ($).

Tip

Use $setField to add or update fields with names that contain dollar signs ($) or periods (.).

$getField has the following syntax:

{
$getField: {
field: <String>,
input: <Object>
}
}
Field
Type
Description
field
String

Field in the input object for which you want to return a value. field can be any valid expression that resolves to a string constant.

If field begins with a dollar sign ($), place the field name inside of a $literal expression to return its value.

input
Object

Default: $$CURRENT

A valid expression that contains the field for which you want to return a value. input must resolve to an object, missing, null, or undefined. If omitted, defaults to the document currently being processed in the pipeline ($$CURRENT).

$getField has the following shorthand syntax for retrieving field values from $$CURRENT:

{
$getField: <String>
}

For this syntax, the argument is equivalent to the value of field described above.

  • If field resolves to anything other than a string constant, $getField returns an error.
  • If the field that you specify is not present in the input object, or in $$CURRENT if you don't specify an input object, $getField returns missing.
  • If input evaluates to missing, undefined, or null, $getField returns null.
  • If input evaluates to anything other than an object, missing, undefined, or null, $getField returns an error.
  • $getField doesn't implicitly traverse objects or arrays. For example, $getField evaluates a field value of a.b.c as a top-level field a.b.c instead of a nested field { a: { b: { c: } } }.
Tip
See also:

Consider an inventory collection with the following documents:

{ "_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 }

The following operation uses the $getField and $gt operators to find which products have a price.usd greater than 200:

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

The operation returns the following results:

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

Consider an inventory collection with the following documents:

{ "_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 }

The following operation uses the $getField, $gt, and $literal operators to find which products have a $price greater than 200:

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

The operation returns the following results:

[
{ _id: 2, item: 'winter coat', qty: 200, '$price': 499.99 },
{ _id: 4, item: 'leather boots', qty: 300, '$price': 249.99 }
]
Give Feedback
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.