embeddedDocument

On this page

Definition

Syntax
Options
Behavior
Scoring Behavior
Sorting Behavior
Highlighting
Limitations
Examples
Index Definition
Basic Query
Facet Query
Query and Sort
Query for Matching Embedded Documents Only

Note

The Atlas Search embeddedDocuments index option, embeddedDocument operator, and embedded scoring option are in preview. When an Atlas Search index on a replica set or single MongoDB shard reaches Lucene's two billion document limit, Atlas Search doesn't index new documents or apply updates to existing documents for that index. A solution to accommodate this limitation will be in place when this feature is generally available. To troubleshoot any issues related to using this feature, contact Support.

Definition

embeddedDocument: The embeddedDocument operator is similar to $elemMatch operator. It constrains multiple query predicates to be satisfied from a single element of an array of embedded documents. embeddedDocument can be used only for queries over fields of the embeddedDocuments type.

Syntax

embeddedDocument has the following syntax:

{
  "embeddedDocument": {
    "path": "<path-to-field>",
    "operator": { <operator-specification> },
    "score": { <score-options> }
  }
}

Options

embeddedDocument uses the following options to construct a query:

Field	Type	Description	Necessity
`operator`	object	Operator to use to query each document in the array of documents that you specify in the `path`. The moreLikeThis operator is not supported.	Required
`path`	string	Indexed embeddedDocuments type field to search. The specified field must be a parent for all operators and fields specified using the `operator` option. See Path Construction for more information.	Required
`score`	object	Score to assign to matching search results. You can use the `embedded` scoring option to configure scoring options. To learn more, see Scoring Behavior.	Optional

Behavior

When you query embedded documents in arrays using the embeddedDocument operator, Atlas Search evaluates and scores the operator query predicates at different stages of query execution. Atlas Search:

Evaluates each embedded document in the array independently.
Combines the scores of matching results as configured using the embedded option, or scores by summing the scores of matching results if you don't specify an embedded score option.
Joins the matching results with the parent document if other query predicates are specified through the compound operator.
Note
For string faceting, Atlas Search counts string facets once for each document in the result set. For an example of this behavior, see Examples.

Scoring Behavior

By default, embeddedDocument operator uses the default aggregation strategy, sum, for combining scores of embedded document matches. The embeddedDocument operator score option allows you to override the default and configure the score of matching results using the embedded option.

Tip

Sorting Behavior

To sort the parent documents by an embedded document field, you must do the following:

Index the parents of the embedded document child field as the document type.
Index the child field with string values within the embedded document as the token type. For child fields with number and date values, enable dynamic mapping to index those fields automatically.

Atlas Search sorts on parent documents only. It doesn't sort the child fields within an array of documents. For an example, see Sort Example.

Highlighting

You can highlight on fields if the fields are indexed under a parent field of document type for query predicates specified inside the embeddedDocument operator. For an example, see tutorial.

Limitations

You can't highlight on queries inside the embeddedDocument operator.

Examples

The following examples use the sample_supplies.sales collection in the sample dataset.

Index Definition

These sample queries use the following index definition on the collection:

{
  "mappings": {
    "dynamic": true,
    "fields": {
      "items": [
        {
          "dynamic": true,
          "type": "embeddedDocuments"
        },
        {
          "dynamic": true,
          "fields": {
            "tags": {
              "type": "token"
            }
          },
          "type": "document"
        }
      ],
      "purchaseMethod": {
        "type": "stringFacet"
      }
    }
  }
}

Basic Query

The following query searches the collection for items tagged school with a preference for items named backpack. Atlas Search scores the results in descending order based on the average (arithmetic mean) score of all matching embedded documents. The query includes a $limit stage to limit the output to 5 documents and a $project stage to:

Exclude all fields except items.name and items.tags fields
Add a field named score

1 db.sales.aggregate({
2   "$search": {
3     "embeddedDocument": {
4       "path": "items",
5       "operator": {
6         "compound": {
7           "must": [{
8             "text": {
9               "path": "items.tags",
10               "query": "school"
11             }
12           }],
13           "should": [{
14             "text": {
15               "path": "items.name",
16               "query": "backpack"
17             }
18           }]
19         }
20       },
21       "score": {
22         "embedded": {
23           "aggregate": "mean"
24         }
25       }
26     }
27   }
28 },
29 {
30   $limit: 5
31 },
32 {
33   $project: {
34     "_id": 0,
35     "items.name": 1,
36     "items.tags": 1,
37     "score": { $meta: "searchScore" }
38   }
39 })

Facet Query

The following query searches for items tagged school with a preference for items named backpack. It requests facet information on the purchaseMethod field.

1 db.sales.aggregate({
2   "$searchMeta": {
3     "facet": {
4       "operator": {
5         "embeddedDocument": {
6           "path": "items",
7           "operator": {
8             "compound": {
9               "must": [
10                 {
11                   "text": {
12                     "path": "items.tags",
13                     "query": "school"
14                   }
15                 }
16               ],
17               "should": [
18                 {
19                   "text": {
20                     "path": "items.name",
21                     "query": "backpack"
22                   }
23                 }
24               ]
25             }
26           }
27         }
28       },
29       "facets": {
30         "purchaseMethodFacet": {
31           "type": "string",
32           "path": "purchaseMethod"
33         }
34       }
35     }
36   }
37 })

Query and Sort

The following query searches for items named laptop and it sorts the results by the items.tags field. The query includes a $limit stage to limit the output to 5 documents and a $project stage to:

Exclude all fields except items.name and items.tags
Add a field named score

1 db.sales.aggregate({
2   "$search": {
3     "embeddedDocument": {
4       "path": "items",
5       "operator": {
6         "text": {
7           "path": "items.name",
8           "query": "laptop"
9         }
10       }
11     },
12     "sort": {
13       "items.tags": 1
14     }
15   }
16 },
17 {
18   "$limit": 5
19 },
20 {
21   "$project": {
22     "_id": 0,
23     "items.name": 1,
24     "items.tags": 1,
25     "score": { "$meta": "searchScore" }
26   }
27 })

Query for Matching Embedded Documents Only

The following query returns only the nested documents that match the query. The query uses Atlas Search compound operator clauses in the $search stage to find matching documents and then the aggregation operators in the $project stage to return only matching embedded documents. Specifically, the query specifies the following pipeline stages:

`$search`	Specifies the following criteria in the compound operator `must` clause: Check if `items.price` field exists in the collection. Search for the items tagged as `office` in the `items.tags` field. Match only if value is more than 2 for the `items.quantity` field.
`$limit`	Limits the output to `5` documents.
`$project`	Perform the following actions: Exclude the `_id` field and only include the `items` and `storeLocation` fields. Use `$filter` to return only elements of the `items` input array that match the condition specified using the `$and` operator. The `and` operator uses the following operators: `$ifNull` to determine if `items.price` contains null values and replace null values, if present, with the replacement expression `false`. `$gt` to check if quantity is greater than 2. `$in` to check if `office` exists in the `tags` array.

1 db.sales.aggregate(
2   {
3     "$search": {
4       "embeddedDocument": {
5         "path": "items",
6         "operator": {
7           "compound": {
8             "must": [
9               {
10                 "range": {
11                   "path": "items.quantity",
12                   "gt": 2
13                 }
14               },
15               {
16                 "exists": {
17                   "path": "items.price"
18                 }
19               },
20               {
21                 "text": {
22                   "path": "items.tags",
23                   "query": "school"
24                 }
25               }
26             ]
27           }
28         }
29       }
30     }
31   },
32   {
33     "$limit": 2
34   },
35   {
36     "$project": {
37       "_id": 0,
38       "storeLocation": 1,
39       "items": {
40         "$filter": {
41           "input": "$items",
42           "cond": {
43             "$and": [
44               {
45                 "$ifNull": [
46                   "$$this.price", "false"
47                 ]
48               },
49               {
50                 "$gt": [
51                   "$$this.quantity", 2
52                 ]
53               },
54               {
55                 "$in": [
56                   "office", "$$this.tags"
57                 ]
58               }
59             ]
60           }
61         }
62       }
63     }
64   }
65 )

Tip

To return only matching embedded documents in the results, include an equivalent $filter to match the $search criteria on the embedded document field. To return only matching embedded documents in the $search stage results, upvote this request in the MongoDB Feedback Engine.

Back

compound

equals

1	db.sales.aggregate({
2	"$search": {
3	"embeddedDocument": {
4	"path": "items",
5	"operator": {
6	"compound": {
7	"must": [{
8	"text": {
9	"path": "items.tags",
10	"query": "school"
11	}
12	}],
13	"should": [{
14	"text": {
15	"path": "items.name",
16	"query": "backpack"
17	}
18	}]
19	}
20	},
21	"score": {
22	"embedded": {
23	"aggregate": "mean"
24	}
25	}
26	}
27	}
28	},
29	{
30	$limit: 5
31	},
32	{
33	$project: {
34	"_id": 0,
35	"items.name": 1,
36	"items.tags": 1,
37	"score": { $meta: "searchScore" }
38	}
39	})

1	db.sales.aggregate({
2	"$searchMeta": {
3	"facet": {
4	"operator": {
5	"embeddedDocument": {
6	"path": "items",
7	"operator": {
8	"compound": {
9	"must": [
10	{
11	"text": {
12	"path": "items.tags",
13	"query": "school"
14	}
15	}
16	],
17	"should": [
18	{
19	"text": {
20	"path": "items.name",
21	"query": "backpack"
22	}
23	}
24	]
25	}
26	}
27	}
28	},
29	"facets": {
30	"purchaseMethodFacet": {
31	"type": "string",
32	"path": "purchaseMethod"
33	}
34	}
35	}
36	}
37	})

1	db.sales.aggregate(
2	{
3	"$search": {
4	"embeddedDocument": {
5	"path": "items",
6	"operator": {
7	"compound": {
8	"must": [
9	{
10	"range": {
11	"path": "items.quantity",
12	"gt": 2
13	}
14	},
15	{
16	"exists": {
17	"path": "items.price"
18	}
19	},
20	{
21	"text": {
22	"path": "items.tags",
23	"query": "school"
24	}
25	}
26	]
27	}
28	}
29	}
30	}
31	},
32	{
33	"$limit": 2
34	},
35	{
36	"$project": {
37	"_id": 0,
38	"storeLocation": 1,
39	"items": {
40	"$filter": {
41	"input": "$items",
42	"cond": {
43	"$and": [
44	{
45	"$ifNull": [
46	"$$this.price", "false"
47	]
48	},
49	{
50	"$gt": [
51	"$$this.quantity", 2
52	]
53	},
54	{
55	"$in": [
56	"office", "$$this.tags"
57	]
58	}
59	]
60	}
61	}
62	}
63	}
64	}
65	)

embeddedDocument.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

Note

Definition

Syntax

Options

Behavior

Note

Scoring Behavior

Tip

See also:

Sorting Behavior

Highlighting

Limitations

Examples

Index Definition

Basic Query

Facet Query

Query and Sort

Query for Matching Embedded Documents Only

Tip

embeddedDocument