Fix This Page
Navigation

Query on Embedded/Nested Documents

This page provides examples of query operations on embedded/nested documents using the db.collection.find() method in the mongo shell. The examples on this page use the inventory collection. To populate the inventory collection, run the following:

This page provides examples of query operations on embedded/nested documents using the pymongo.collection.Collection.find() method in the PyMongo Python driver. The examples on this page use the inventory collection. To populate the inventory collection, run the following:

This page provides examples of query operations on embedded/nested documents using the MongoDB\Collection::find() method in the MongoDB PHP Library. The examples on this page use the inventory collection. To populate the inventory collection, run the following:

This page provides examples of query operations on embedded/nested documents using the MongoDB::Collection::find() method in the MongoDB Perl Driver. The examples on this page use the inventory collection. To populate the inventory collection, run the following:

db.inventory.insertMany( [
   { item: "journal", qty: 25, size: { h: 14, w: 21, uom: "cm" }, status: "A" },
   { item: "notebook", qty: 50, size: { h: 8.5, w: 11, uom: "in" }, status: "A" },
   { item: "paper", qty: 100, size: { h: 8.5, w: 11, uom: "in" }, status: "D" },
   { item: "planner", qty: 75, size: { h: 22.85, w: 30, uom: "cm" }, status: "D" },
   { item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" }
]);

You can run the operation in the web shell below:

# Subdocument key order matters in a few of these examples so we have
# to use bson.son.SON instead of a Python dict.
from bson.son import SON
db.inventory.insert_many([
    {"item": "journal",
     "qty": 25,
     "size": SON([("h", 14), ("w", 21), ("uom", "cm")]),
     "status": "A"},
    {"item": "notebook",
     "qty": 50,
     "size": SON([("h", 8.5), ("w", 11), ("uom", "in")]),
     "status": "A"},
    {"item": "paper",
     "qty": 100,
     "size": SON([("h", 8.5), ("w", 11), ("uom", "in")]),
     "status": "D"},
    {"item": "planner",
     "qty": 75,
     "size": SON([("h", 22.85), ("w", 30), ("uom", "cm")]),
     "status": "D"},
    {"item": "postcard",
     "qty": 45,
     "size": SON([("h", 10), ("w", 15.25), ("uom", "cm")]),
     "status": "A"}])
$insertManyResult = $db->inventory->insertMany([
    [
        'item' => 'journal', 
        'qty' => 25,
        'size' => ['h' => 14, 'w' => 21, 'uom' => 'cm'],
        'status' => 'A',
    ],
    [
        'item' => 'notebook', 
        'qty' => 50,
        'size' => ['h' => 8.5, 'w' => 11, 'uom' => 'in'],
        'status' => 'A',
    ],
    [
        'item' => 'paper', 
        'qty' => 100,
        'size' => ['h' => 8.5, 'w' => 11, 'uom' => 'in'],
        'status' => 'D',
    ],
    [
        'item' => 'planner', 
        'qty' => 75,
        'size' => ['h' => 22.85, 'w' => 30, 'uom' => 'cm'],
        'status' => 'D',
    ],
    [
        'item' => 'postcard', 
        'qty' => 45,
        'size' => ['h' => 10, 'w' => 15.25, 'uom' => 'cm'],
        'status' => 'A',
    ],
]);
# Subdocument key order matters in this example so we have
# to use Tie::IxHash instead of a regular, unordered Perl hash.
$db->coll("inventory")->insert_many(
    [
        {
            item   => "journal",
            qty    => 25,
            size   => Tie::IxHash->new( h => 14, w => 21, uom => "cm" ),
            status => "A"
        },
        {
            item   => "notebook",
            qty    => 50,
            size   => Tie::IxHash->new( h => 8.5, w => 11, uom => "in" ),
            status => "A"
        },
        {
            item   => "paper",
            qty    => 100,
            size   => Tie::IxHash->new( h => 8.5, w => 11, uom => "in" ),
            status => "D"
        },
        {
            item   => "planner",
            qty    => 75,
            size   => Tie::IxHash->new( h => 22.85, w => 30, uom => "cm" ),
            status => "D"
        },
        {
            item   => "postcard",
            qty    => 45,
            size   => Tie::IxHash->new( h => 10, w => 15.25, uom => "cm" ),
            status => "A"
        }
    ]
);

Match an Embedded/Nested Document

To specify an equality condition on a field that is an embedded/nested document, use the query filter document { <field>: <value> } where <value> is the document to match.

To specify an equality condition on a field that is an embedded/nested document, use the query filter document { <field>: <value> } where <value> is the document to match.

To specify an equality condition on a field that is an embedded/nested document, use the query filter document [ <field> => <value> ] where <value> is the document to match.

To specify an equality condition on a field that is an embedded/nested document, use the query filter document { <field> => <value> } where <value> is the document to match.

For example, the following query selects all documents where the field size equals the document { h: 14, w: 21, uom: "cm" }:

db.inventory.find( { size: { h: 14, w: 21, uom: "cm" } } )
cursor = db.inventory.find(
    {"size": SON([("h", 14), ("w", 21), ("uom", "cm")])})
$cursor = $db->inventory->find(['size' => ['h' => 14, 'w' => 21, 'uom' => 'cm']]);
# Subdocument key order matters in this example so we have
# to use Tie::IxHash instead of a regular, unordered Perl hash.
$cursor = $db->coll("inventory")->find(
    { size => Tie::IxHash->new( h => 14, w => 21, uom => "cm" ) }
);

Equality matches on the whole embedded document require an exact match of the specified <value> document, including the field order. For example, the following query does not match any documents in the inventory collection:

db.inventory.find(  { size: { w: 21, h: 14, uom: "cm" } }  )
cursor = db.inventory.find(
    {"size": SON([("w", 21), ("h", 14), ("uom", "cm")])})
$cursor = $db->inventory->find(['size' => ['w' => 21, 'h' => 14, 'uom' => 'cm']]);
# Subdocument key order matters in this example so we have
# to use Tie::IxHash instead of a regular, unordered Perl hash.
$cursor = $db->coll("inventory")->find(
    { size => Tie::IxHash->new( w => 21, h => 14, uom => "cm" ) }
);

Query on Nested Field

To specify a query condition on fields in an embedded/nested document, use the dot notation ("field.nestedField").

Specify Equality Match on a Nested Field

The following example selects all documents where the field uom nested in the size field equals "in":

db.inventory.find( { "size.uom": "in" } )
cursor = db.inventory.find({"size.uom": "in"})
$cursor = $db->inventory->find(['size.uom' => 'in']);
$cursor = $db->coll("inventory")->find( { "size.uom" => "in" } );

Specify Match using Query Operator

A query filter document can use the query operators to specify conditions in the following form:

{ <field1>: { <operator1>: <value1> }, ... }

A query filter document can use the query operators to specify conditions in the following form:

{ <field1>: { <operator1>: <value1> }, ... }

A query filter document can use the query operators to specify conditions in the following form:

[ <field1> => [ <operator1> => <value1> ], ... ]

A query filter document can use the query operators to specify conditions in the following form:

{ <field1> => { <operator1> => <value1> }, ... }

The following query uses the less than operator ($lt) on the field h embedded in the size field:

db.inventory.find( { "size.h": { $lt: 15 } } )
cursor = db.inventory.find({"size.h": {"$lt": 15}})
$cursor = $db->inventory->find(['size.h' => ['$lt' => 15]]);
$cursor = $db->coll("inventory")->find( { "size.h" => { '$lt' => 15 } } );

Specify AND Condition

The following query selects all documents where the nested field h is less than 15, the nested field uom equals "in", and the status field equals "D":

db.inventory.find( { "size.h": { $lt: 15 }, "size.uom": "in", status: "D" } )
cursor = db.inventory.find(
    {"size.h": {"$lt": 15}, "size.uom": "in", "status": "D"})
$cursor = $db->inventory->find([
    'size.h' => ['$lt' => 15],
    'size.uom' => 'in',
    'status' => 'D',
]);
$cursor = $db->coll("inventory")->find(
    { "size.h" => { '$lt' => 15 }, "size.uom" => "in", status => "D" }
);

Additional Query Tutorials

For additional query examples, see: