How to Index Fields in Arrays of Objects and Documents

embeddedDocuments Type Limitations

The following limitations apply when indexing with the embeddedDocument type:

• 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 define a field inside the embeddedDocuments type as the deprecated knnVector 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 Fields in Embedded Documents 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.

{
  "_id": 0,
  "name": "Springfield High",
  "mascot": "Pumas",
  "teachers": [
    {
      "first": "Jane",
      "last": "Smith",
      "classes": [
        {
          "subject": "art of science",
          "grade": "12th"
        },
        ... // 2 more embedded documents
      ]
    },
    ... // 1 more embedded document
  ],
  "clubs": {
    "stem": [
      {
        "club_name": "chess",
        "description": "provides students opportunity to play the board game of chess informally and competitively in tournaments."
      },
      ... // 1 more embedded document
    ],
    ... // 1 more embedded document
  }
}

Define the Index for the embeddedDocument Type

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

1
{
2
  "mappings": {
3
    "dynamic": true|false,
4
    "fields": {
5
      "<field-name>": {
6
        "type": "embeddedDocuments",
7
        "dynamic": true|false,
8
        "fields": {
9
          "<field-name>": {
10
            <field-mapping-definition>
11
          }
12
        }
13
      }
14
    }
15
  }
16
}

Configure embeddedDocument Field Properties

The Atlas Search embeddedDocuments type takes the following parameters:

Try an Example for the embeddedDocument Type

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.

1
{
2
  "mappings": {
3
    "fields": {
4
      "items": {
5
        "type": "embeddedDocuments",
6
        "dynamic": true
7
      }
8
    }
9
  }
10
}

1
{
2
  "mappings": {
3
    "dynamic": true,
4
    "fields": {
5
      "items": {
6
        "dynamic": true,
7
        "type": "embeddedDocuments"
8
      },
9
      "purchaseMethod": {
10
        "type": "stringFacet"
11
      }
12
    }
13
  }
14
}

1
{
2
  "mappings": {
3
    "fields": {
4
      "items": {
5
        "type": "embeddedDocuments",
6
        "dynamic": false,
7
        "fields": {
8
          "name": {
9
            "type": "string"
10
          },
11
          "tags": {
12
            "type": "string"
13
          }
14
        }
15
      }
16
    }
17
  }
18
}

Learn More

To learn more about the embeddedDocument operator and see example queries, see embeddedDocument.

To learn how to query an embedded document, see the How to Run Atlas Search Queries Against Fields in Embedded Documents tutorial.