Docs Menu
Docs Home
MongoDB Atlas
/ / / /

How to Index Fields in Arrays of Objects and Documents

On this page

  • Review embeddedDocuments Type Limitations
  • Define the Index for the embeddedDocument Type
  • Configure embeddedDocument Field Properties
  • Try an Example for the embeddedDocument Type


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.

You can use the Atlas Search embeddedDocuments type to index fields in documents and objects that are elements of an array. Atlas Search indexes embedded documents independent of their parent document. Each indexed document contains only fields that are part of the embedded document array element. You can use only the embeddedDocument operator to query fields indexed as embeddedDocuments type.

Atlas Search doesn't dynamically index fields of type embeddedDocument. You must use static mappings to index embeddedDocument fields. You can use the Visual Editor or the JSON Editor in the Atlas UI to index fields of type embeddedDocument.


Atlas Search doesn't support indexing more than two billion index objects, where each indexed embedded document counts as a single object. Using the embeddedDocuments field type can result in indexing objects over this limit, which causes an index to transition to a failed state. If your collection has large arrays that might generate two billion objects, you must shard any clusters that contain indexes with the embeddedDocuments type.

The following limitations apply:

  • You can use embeddedDocuments only on fields with up to 5 levels of nesting. An embeddedDocuments field can't have more than 4 parent embeddedDocuments fields.

  • You can't use embeddedDocuments for date or numeric faceting.

  • You can't define a field inside the embeddedDocuments type as the knnVector type.

  • You can't index children of fields indexed as the embeddedDocuments type as the token type.

  • For highlighting fields within embedded documents, you must also index the parent of the field that you want to highlight as the document type.

  • You can do the following only if you index the parents of the embedded document child field as the document type:

    • Faceted search on string fields within embedded documents. You must also index the field that you want to facet on as the stringFacet type.


      When you facet on a string field inside embedded documents, Atlas Search returns facet count for only the number of matching parent documents.

      You can't facet on numeric and date fields in embedded documents.

    • Highlight fields within embedded documents. For an example, see the How to Run Atlas Search Queries Against Objects in Arrays tutorial.

    • Sort by the parent of the embedded document field. You must also index the embedded document field with string values as the token type. For child fields with number and date values, enable dynamic mapping to index those fields automatically. For an example, see Sort Example.

To define the index for the embeddedDocument type, choose your preferred configuration method in the Atlas UI and then select the database and collection.

The Atlas Search embeddedDocuments type takes the following parameters:

Human-readable label that identifies the field type. Value must be embeddedDocuments.

Flag that specifies whether to index every dynamically indexable field in the document. Value can be one of the following:

  • true - index all indexable fields.

  • false - don't index all the indexable fields.


Fields to index.

If dynamic is true, Atlas Search indexes all indexable fields.

If dynamic is false, you can specify the fields to index in the field definition for fields.


Atlas Search doesn't support indexing facet fields as part of an embeddedDocuments field.


The following index definition example uses the sample_supplies.sales collection. If you have the sample data already loaded on your cluster, you can use the Visual Editor or JSON Editor in the Atlas UI to configure the index. After you select your preferred configuration method, select the database and collection, and refine your index to add field mappings.


See also: Additional Index Definition Examples

← document
geo →