For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.
Make the MongoDB docs better! We value your opinion. Share your feedback for a chance to win $100.
MongoDB Branding Shape
Click here >
Docs Menu
Docs Home
/ /
Search Options
Docs Home
/ /
Query Reference
/
Search Options
Docs Home
/
Development
/
Search
/
Queries & Indexes
/
Query Reference
/
Search Options

Query, Filter, and Retrieve Arrays of Objects

You can use the returnScope option to set the context of the query and return arrays of objects as individual documents.

Requirements

To retrieve nested objects as individual documents using returnScope, you must:

  • Index the arrays of objects as the embeddedDocuments type.

  • Define storedSource for the nested fields that you want to retrieve. MongoDB Search only returns fields defined in the storedSource.

  • Set the returnStoredSource option to true in the query.

Syntax

returnScope has the following syntax in your queries:

{
  $search: {
   "<operator>": {
      <operator-specification>,
   },
   "returnScope": {
      "path": "<embedded-documents-field-to-retrieve>"
   },
   "returnStoredSource": true
  }
}
{
  $searchMeta: {
   "returnScope": {
      "path": "<embedded-documents-field-to-retrieve>"
   },
   "returnStoredSource": true
  },
  "facet": {
    "<operator>": {
      <operator-specification>,
   },
    "facets": {
      <facet-definition>
    }
  }
}

To learn more about query syntax, see $search.

Behavior

The returnScope option sets the retrieval context for the query. If you specify returnScope in your query, MongoDB Search scores, sorts, and counts each embedded document as if it were an individual document.

Considerations

When you use the returnScope option, MongoDB Search only returns the fields that you configured as storedSource within the embeddedDocument. Fields outside of the embeddedDocument path (such as fields at the root level) and fields that are not configured as storedSource are not returned.

In your operator specification, you must specify the full path to the field that you want to query. When you use the returnScope option, you must make sure all operator specifications paths are nested under the returnScope.path. To query on a field outside the returnScope.path, you must use either the hasAncestor or hasRoot operator. To learn more, see:

Retrieve the Root Document ID

When you use returnScope in a query, MongoDB Search populates a searchRootDocumentId metadata field. You can use the searchRootDocumentId metadata field on clusters running MongoDB 8.3 or later. This field contains the identifier of the root document that contains each returned embedded document. To project this value, use the $meta expression with the searchRootDocumentId keyword.

MongoDB Search populates searchRootDocumentId only when your query sets both returnStoredSource: true and returnScope.path. If you reference searchRootDocumentId in a query that does not specify returnScope, the query fails with the following error:

query requires $search root document id metadata, but it is not
available

Use searchRootDocumentId if you want to:

  • Fetch fields from the parent document after filtering on the child documents.

  • Group child documents by their parent.

Don't use searchRootDocumentId if:

  • You need only fields from the matched child documents.

  • You want to return the parent document for every child document in the result set, since this can be expensive.

Examples

The following examples demonstrate how to use the returnScope option in queries. The examples use the sample_training.companies sample dataset. If you load the data on your cluster and create the sample index on the fields in the collection, you can try the following queries against the sample data.

Sample Index

1{
2  "mappings": { 
3    "dynamic": false,
4    "fields": { 
5      "funding_rounds": { 
6        "type": "embeddedDocuments",
7        "dynamic": true,
8        "fields": {
9          "investments": {
10            "type": "embeddedDocuments",
11            "dynamic": true
12          }
13        },
14        "storedSource": {
15          "include": [
16            "round_code", 
17            "raised_currency_code",
18            "raised_amount",
19            "investments.person",
20            "investments.financial_org"
21          ] 
22        }
23      } 
24    }
25  }
26}

The preceding index definition configures MongoDB Search to:

  • Index the funding_rounds and funding_rounds.investments fields as the embeddedDocuments type.

  • Index all the dynamically indexable fields nested in the funding_rounds and funding_rounds.investments array of objects.

  • Store the following fields on mongot:

    • funding_rounds.round_code

    • funding_rounds.raised_currency_code

    • funding_rounds.raised_amount

    • funding_rounds.investments.person

    • funding_rounds.investments.financial_org

You can use the embeddedDocument Operator to perform element-wise querying on both the funding_rounds and funding_rounds.investments fields. The following sections demonstrate some sample queries that use the returnScope option to retrieve the embeddedDocuments fields as individual documents.

Sample Document Structure from sample_training.companies Collection
{
  ...,
  "funding_rounds": [
    {
      "id": <integer>,
      "round_code": "<string>",
      "source_url": "<string>",
      "source_description": "<string>",
      "raised_amount": <integer>,
      "raised_currency_code": "<string>",
      "funded_year": <integer>,
      "funded_month": "<string>",
      "funded_day": "<string>",
      "investments": [
         {
           "company": "<string>",
           "financial_org": {
             "name": "<string>",
             "permalink": "<string>"
           },
           "person": {
             "first_name": "<string>",
             "last_name": "<string>",
             "permalink": "<string>"
           }
         },
         ...
      ]
    },
    ...
  ],
  ...
}

Sample Queries

The following sections demonstrate sample queries that use the returnScope option to retrieve fields in embeddedDocuments type fields that were stored on mongot.

Simple Query

Query and retrieve embedded document fields.

The following query uses the range (MongoDB Search Operator) to query the funding_rounds.raised_amount field for amount greater than and equal to 5000000 and less than and equal to 10000000. It sets the query scope as funding_rounds field using the returnScope option. It returns all the stored fields inside the funding_rounds array of objects, including fields in the funding_rounds.investments array of objects that were stored using the returnStoredSource option. It limits the number of results to only 5 funding_rounds documents.

1db.companies.aggregate(
2  {
3    "$search": {
4      "range": {
5        "path": "funding_rounds.raised_amount",
6        "gte": 5000000,
7        "lte": 10000000
8      },
9      "returnStoredSource": true,
10      "returnScope": {
11        "path": "funding_rounds"
12      }
13    }
14  },
15  {
16    "$limit": 5
17  }
18)
[
  {
    round_code: 'a',
    raised_amount: 5250000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: {
          name: 'Frazier Technology Ventures',
          permalink: 'frazier-technology-ventures'
        },
        person: null
      },
      {
        financial_org: { name: 'Trinity Ventures', permalink: 'trinity-ventures' },
        person: null
      }
    ]
  },
  {
    round_code: 'b',
    raised_amount: 9500000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: { name: 'Accel Partners', permalink: 'accel-partners' },
        person: null
      },
      {
        financial_org: {
          name: 'Frazier Technology Ventures',
          permalink: 'frazier-technology-ventures'
        },
        person: null
      },
      {
        financial_org: { name: 'Trinity Ventures', permalink: 'trinity-ventures' },
        person: null
      }
    ]
  },
  {
    round_code: 'a',
    raised_amount: 5000000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: {
          name: 'Charles River Ventures',
          permalink: 'charles-river-ventures'
        },
        person: null
      },
      {
        financial_org: {
          name: 'Union Square Ventures',
          permalink: 'union-square-ventures'
        },
        person: null
      },
      {
        financial_org: null,
        person: {
          first_name: 'Marc',
          last_name: 'Andreessen',
          permalink: 'marc-andreessen'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Dick',
          last_name: 'Costolo',
          permalink: 'dick-costolo'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Naval',
          last_name: 'Ravikant',
          permalink: 'naval-ravikant'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Ron',
          last_name: 'Conway',
          permalink: 'ron-conway'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Chris',
          last_name: 'Sacca',
          permalink: 'chris-sacca'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Greg',
          last_name: 'Yaitanes',
          permalink: 'greg-yaitanes'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Brian',
          last_name: 'Pokorny',
          permalink: 'brian-pokorny'
        }
      },
      {
        financial_org: { name: 'SV Angel', permalink: 'sv-angel' },
        person: null
      }
    ]
  },
  {
    round_code: 'e',
    raised_amount: 5166511,
    raised_currency_code: 'USD',
    investments: []
  },
  {
    round_code: 'b',
    raised_amount: 9000000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: {
          name: 'Charles River Ventures',
          permalink: 'charles-river-ventures'
        },
        person: null
      },
      {
        financial_org: { name: 'Redpoint Ventures', permalink: 'redpoint-ventures' },
        person: null
      },
      {
        financial_org: {
          name: 'The Kinsey Hills Group',
          permalink: 'kinsey-hills-group'
        },
        person: null
      }
    ]
  }
]

Compound Query

Query and retrieve multiple embedded document fields.

The following query uses the compound Operator to search multiple levels of nested embeddedDocuments fields in the same query:

  • Must match``funding_rounds.raised_currency_code`` with USD

  • Should match funding_rounds.investments.financial_org.name with Trinity Ventures

It returns all the stored fields inside the funding_rounds array of objects, including fields in the funding_rounds.investments. It limits the number of results to only 5 funding_rounds documents.

1db.companies.aggregate(
2  {
3    "$search": {
4      "compound": {
5        "must": [{
6          "text": {
7            "path": "funding_rounds.raised_currency_code",
8            "query": "usd"
9          }
10        }],
11        "should": [{
12          "phrase": {
13            "path": "funding_rounds.investments.financial_org",
14            "query": "Trinity Ventures",
15          }
16        }]
17      },
18      "returnStoredSource": true,
19      "returnScope": {
20        "path": "funding_rounds"
21      }
22    }
23  },
24  {
25    "$limit": 5
26  }
27)
[
  {
    round_code: 'a',
    raised_amount: 5250000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: {
          name: 'Frazier Technology Ventures',
          permalink: 'frazier-technology-ventures'
        },
        person: null
      },
      {
        financial_org: { name: 'Trinity Ventures', permalink: 'trinity-ventures' },
        person: null
      }
    ]
  },
  {
    round_code: 'b',
    raised_amount: 9500000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: { name: 'Accel Partners', permalink: 'accel-partners' },
        person: null
      },
      {
        financial_org: {
          name: 'Frazier Technology Ventures',
          permalink: 'frazier-technology-ventures'
        },
        person: null
      },
      {
        financial_org: { name: 'Trinity Ventures', permalink: 'trinity-ventures' },
        person: null
      }
    ]
  },
  {
    round_code: 'c',
    raised_amount: 25000000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: { name: 'DAG Ventures', permalink: 'dag-ventures' },
        person: null
      },
      {
        financial_org: { name: 'Accel Partners', permalink: 'accel-partners' },
        person: null
      },
      {
        financial_org: { name: 'Trinity Ventures', permalink: 'trinity-ventures' },
        person: null
      },
      {
        financial_org: {
          name: 'Frazier Technology Ventures',
          permalink: 'frazier-technology-ventures'
        },
        person: null
      }
    ]
  },
  {
    round_code: 'angel',
    raised_amount: 500000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: null,
        person: {
          first_name: 'Peter',
          last_name: 'Thiel',
          permalink: 'peter-thiel'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Reid',
          last_name: 'Hoffman',
          permalink: 'reid-hoffman'
        }
      }
    ]
  },
  {
    round_code: 'a',
    raised_amount: 12700000,
    raised_currency_code: 'USD',
    investments: [
      {
        financial_org: { name: 'Accel Partners', permalink: 'accel-partners' },
        person: null
      },
      {
        financial_org: null,
        person: {
          first_name: 'Mark',
          last_name: 'Pincus',
          permalink: 'mark-pincus'
        }
      },
      {
        financial_org: null,
        person: {
          first_name: 'Reid',
          last_name: 'Hoffman',
          permalink: 'reid-hoffman'
        }
      }
    ]
  }
]

Group Children by Parent

Group children by parent using the searchRootDocumentId meta field.

The following query uses the range (MongoDB Search Operator) to query the funding_rounds.raised_amount field for amount greater than and equal to 5000000 and less than and equal to 10000000. It sets the query scope as funding_rounds field using the returnScope option. It groups the matching funding_rounds under each parent company by using the searchRootDocumentId meta field as the group key and computes the average raised_amount per company in the avgRaisedAmount field. It sorts the results by avgRaisedAmount in descending order and limits the number of results to 10 companies.

1db.companies.aggregate([
2  {
3    "$search": {
4      "returnStoredSource": true,
5      "returnScope": {
6        "path": "funding_rounds"
7      },
8      "range": {
9        "path": "funding_rounds.raised_amount",
10        "gte": 5000000,
11        "lte": 10000000
12      }
13    }
14  },
15  {
16    "$group": {
17      "_id": { "$meta": "searchRootDocumentId" },
18      "funding_rounds": {
19        "$push": {
20          "round_code": "$round_code",
21          "raised_amount": "$raised_amount",
22          "raised_currency_code": "$raised_currency_code"
23        }
24      },
25      "avgRaisedAmount": { "$avg": "$raised_amount" }
26    }
27  },
28  { "$sort": { "avgRaisedAmount": -1 } },
29  { "$limit": 10 }
30])
[
  {
    _id: ObjectId('52cdef7d4bab8bd675298f82'),
    funding_rounds: [
      {
        round_code: 'a',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7e4bab8bd67529af80'),
    funding_rounds: [
      {
        round_code: 'b',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7f4bab8bd67529be3d'),
    funding_rounds: [
      {
        round_code: 'a',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7f4bab8bd67529c52d'),
    funding_rounds: [
      {
        round_code: 'unattributed',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7e4bab8bd67529ab31'),
    funding_rounds: [
      {
        round_code: 'c',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      },
      {
        round_code: 'a',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7e4bab8bd67529aa94'),
    funding_rounds: [
      {
        round_code: 'b',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7f4bab8bd67529be6f'),
    funding_rounds: [
      {
        round_code: 'a',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7c4bab8bd6752985cb'),
    funding_rounds: [
      {
        round_code: 'd',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7d4bab8bd675299fd1'),
    funding_rounds: [
      {
        round_code: 'c',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  },
  {
    _id: ObjectId('52cdef7f4bab8bd67529c2c8'),
    funding_rounds: [
      {
        round_code: 'debt_round',
        raised_amount: 10000000,
        raised_currency_code: 'USD'
      }
    ],
    avgRaisedAmount: 10000000
  }
]

Fetch Parent Fields After Filtering

Retrieve the fields from the parent document after filtering on the embedded document fields.

The following query uses the range (MongoDB Search Operator) to query the funding_rounds.raised_amount field for amount greater than and equal to 5000000 and less than and equal to 10000000. It sets the query scope as funding_rounds field using the returnScope option. It sorts the matching funding_rounds by raised_amount in descending order and limits the results to the top 10 funding rounds. It then uses the searchRootDocumentId meta field to join each funding round back to its parent company in the companies collection and returns the company's name alongside the funding round's round_code, raised_amount, and raised_currency_code fields.

1db.companies.aggregate([
2  {
3    "$search": {
4      "returnStoredSource": true,
5      "returnScope": {
6        "path": "funding_rounds"
7      },
8      "range": {
9        "path": "funding_rounds.raised_amount",
10        "gte": 5000000,
11        "lte": 10000000
12      }
13    }
14  },
15  { "$sort": { "raised_amount": -1 } },
16  { "$limit": 10 },
17  { "$addFields": { "root_id": { "$meta": "searchRootDocumentId" } } },
18  {
19    "$lookup": {
20      "from": "companies",
21      "localField": "root_id",
22      "foreignField": "_id",
23      "as": "company"
24    }
25  },
26  { "$unwind": "$company" },
27  {
28    "$project": {
29      "_id": 0,
30      "round_code": 1,
31      "raised_amount": 1,
32      "raised_currency_code": 1,
33      "company.name": 1
34    }
35  }
36])
[
  {
    round_code: 'partial',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'WeFi' }
  },
  {
    round_code: 'b',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'LinkedIn' }
  },
  {
    round_code: 'a',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'Lotame' }
  },
  {
    round_code: 'c',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'OpenX' }
  },
  {
    round_code: 'b',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'AddThis' }
  },
  {
    round_code: 'a',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'Terabitz' }
  },
  {
    round_code: 'b',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'Six Apart' }
  },
  {
    round_code: 'a',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'Snocap' }
  },
  {
    round_code: 'b',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'Wikia' }
  },
  {
    round_code: 'unattributed',
    raised_amount: 10000000,
    raised_currency_code: 'USD',
    company: { name: 'Mashery' }
  }
]

Back

searchSequenceToken

Next

Performance Options

On this page