The $getField operator reads a field value from an object when the field name may be dynamic. Use it in aggregation pipelines when dot notation cannot help — for example, when the key to read is stored in another field.
Read fields by name.
field + input.
Pull values from subdocs.
Shape output fields.
Metrics, configs, maps.
Fixed vs dynamic paths.
In MongoDB’s aggregation framework, the $getField operator returns the value of a specified field from an object. You provide a field name (which can be a literal string or an expression) and an input object to read from. This is especially powerful when documents store flexible key-value data — like metrics maps, user preferences, or configuration objects — and you need to read whichever key the document points to.
For a fixed path like "$product.name", dot notation is simpler. Reach for $getField when the field name comes from data — like field: "$metricKey" and input: "$metrics".
The $getField operator takes an object with field and input:
{
$getField: {
field: <string expression>,
input: <object expression>
}
}// Static field name from nested object
{ field: "name", input: "$product" }
// Dynamic field name from document field
{ field: "$metricKey", input: "$metrics" }
// Read from the full document
{ field: "$lookupKey", input: "$$ROOT" }field — the name of the field to read (string literal like "name" or expression like "$metricKey").input — the object to read from (field path like "$metrics" or "$$ROOT").null if the field does not exist or input is null.$project, $addFields, or $set.Dot notation ("$metrics.revenue") only works when you know the field name at pipeline design time. $getField lets the field name come from document data. It also handles awkward field names that contain dots or $ prefixes.
| Question | Answer |
|---|---|
| Operator type | Aggregation field-access expression operator |
| Syntax | { $getField: { field, input } } |
| Input | Field name + source object |
| Output | Field value (or null) |
| Common stages | $project, $addFields, $set |
{
$getField: {
field: "name",
input: "$product"
}
}Fixed field name
{
$getField: {
field: "$metricKey",
input: "$metrics"
}
}Name from field
{
$getField: {
field: "$key",
input: "$$ROOT"
}
}From full document
// field not in input
→ nullReturns null
Walk through sample data, an aggregation pipeline, and the output step by step.
Start with a inventory collection and read a nested field with a static name.
Suppose you have an inventory collection where each document has a nested product object:
[
{
"_id": ObjectId("609c26812e9274a86871bc6a"),
"sku": "A100",
"product": { "name": "Laptop", "brand": "TechCo", "price": 999 }
},
{
"_id": ObjectId("609c26812e9274a86871bc6b"),
"sku": "B200",
"product": { "name": "Mouse", "brand": "TechCo", "price": 29 }
}
]Extract product.name using $getField with a literal field name:
db.inventory.aggregate([
{
$project: {
sku: 1,
productName: {
$getField: {
field: "name",
input: "$product"
}
}
}
}
])input: "$product" points to the nested object.field: "name" tells MongoDB which key to read.product.name — same as dot notation here, but the pattern scales to dynamic names.Read metrics by dynamic key, pull from the full document, and handle flexible schemas.
Each document stores which metric to read in metricKey:
db.reports.aggregate([
{
$project: {
reportId: 1,
metricKey: 1,
selectedValue: {
$getField: {
field: "$metricKey",
input: "$metrics"
}
}
}
}
])
// metricKey: "revenue", metrics: { revenue: 5000, clicks: 120 }
// → selectedValue: 5000field: "$metricKey" resolves per document. One pipeline can read different keys without rewriting the path — dot notation cannot do this.
When the key to read is a top-level field name stored in lookupKey:
db.settings.aggregate([
{
$project: {
lookupKey: 1,
resolved: {
$getField: {
field: "$lookupKey",
input: "$$ROOT"
}
}
}
}
])
// lookupKey: "theme", document has theme: "dark"
// → resolved: "dark"$$ROOT refers to the current document. Combined with a dynamic field, you can resolve any top-level field whose name is stored in the document itself.
$getField can read keys that dot notation cannot express cleanly:
db.logs.aggregate([
{
$project: {
event: 1,
dotKeyValue: {
$getField: {
field: "user.name",
input: "$attributes"
}
}
}
}
])
// attributes: { "user.name": "Ana", "status": "ok" }
// → dotKeyValue: "Ana"The field name "user.name" is a single key in the object, not a nested path. Dot notation would look for attributes.user.name as nested objects. $getField treats the entire string as the key name.
$ that dot notation cannot handle.$getField WorksThe field expression becomes the key name; input becomes the source object.
MongoDB reads input[field] — like JavaScript bracket notation, not dot chaining.
If the key exists, its value is returned. If not, the result is null.
You get the right value even when the field name varies per document.
The $getField operator is essential when field names are dynamic or contain special characters. It gives aggregation pipelines the same flexibility as JavaScript bracket notation — read any key from any object at runtime.
For beginners, remember two parts: field (the key to read) and input (the object to read from). Use dot notation for fixed paths; use $getField when the path depends on document data.
$getField when the field name comes from document data$$ROOT as input for top-level dynamic lookups$getField returns null$setField when you also need to write dynamic keys$getField unnecessarilyfield is the key name, not a full pathfield: "a.b" is one key, not nested$getField as a query filter outside expressions$getFieldUse these points when accessing fields dynamically in pipelines.
Read fields by name.
Purposefield + input.
SyntaxLike obj[key].
UsageMetrics, configs.
Use caseKey name, not nested.
Edge caseContinue with $gt for greater-than comparisons, or review $function for custom JavaScript.
5 people found this page helpful