OPTIONS

Multikey Indexes

To index a field that holds an array value, MongoDB adds index items for each item in the array. These multikey indexes allow MongoDB to return documents from queries using the value of an array. MongoDB automatically determines whether to create a multikey index if the indexed field contains an array value; you do not need to explicitly specify the multikey type.

Consider the following illustration of a multikey index:

Diagram of a multikey index on the ``addr.zip`` field. The ``addr`` field contains an array of address documents. The address documents contain the ``zip`` field.

Diagram of a multikey index on the addr.zip field. The addr field contains an array of address documents. The address documents contain the zip field.

Multikey indexes support all operations supported by other MongoDB indexes; however, applications may use multikey indexes to select documents based on ranges of values for the value of an array. Multikey indexes support arrays that hold both values (e.g. strings, numbers) and nested documents.

Limitations

Interactions between Compound and Multikey Indexes

While you can create multikey compound indexes, at most one field in a compound index may hold an array. For example, given an index on { a: 1, b: 1 }, the following documents are permissible:

{a: [1, 2], b: 1}

{a: 1, b: [1, 2]}

However, the following document is impermissible, and MongoDB cannot insert such a document into a collection with the {a: 1, b: 1 } index:

{a: [1, 2], b: [1, 2]}

If you attempt to insert such a document, MongoDB will reject the insertion, and produce an error that says cannot index parallel arrays. MongoDB does not index parallel arrays because they require the index to include each value in the Cartesian product of the compound keys, which could quickly result in incredibly large and difficult to maintain indexes.

Shard Keys

Important

The index of a shard key cannot be a multi-key index.

Hashed Indexes

hashed indexes are not compatible with multi-key indexes.

To compute the hash for a hashed index, MongoDB collapses sub-documents and computes the hash for the entire value. For fields that hold arrays or sub-documents, you cannot use the index to support queries that introspect the sub-document.

Examples

Index Basic Arrays

Given the following document:

{
  "_id" : ObjectId("..."),
  "name" : "Warm Weather",
  "author" : "Steve",
  "tags" : [ "weather", "hot", "record", "april" ]
}

Then an index on the tags field, { tags: 1 }, would be a multikey index and would include these four separate entries for that document:

  • "weather",
  • "hot",
  • "record", and
  • "april".

Queries could use the multikey index to return queries for any of the above values.

Index Arrays with Embedded Documents

You can create multikey indexes on fields in objects embedded in arrays, as in the following example:

Consider a feedback collection with documents in the following form:

{
 "_id": ObjectId(...),
 "title": "Grocery Quality",
 "comments": [
    { author_id: ObjectId(...),
      date: Date(...),
      text: "Please expand the cheddar selection." },
    { author_id: ObjectId(...),
      date: Date(...),
      text: "Please expand the mustard selection." },
    { author_id: ObjectId(...),
      date: Date(...),
      text: "Please expand the olive selection." }
 ]
}

An index on the comments.text field would be a multikey index and would add items to the index for all embedded documents in the array.

With the index { "comments.text": 1 } on the feedback collection, consider the following query:

db.feedback.find( { "comments.text": "Please expand the olive selection." } )

The query would select the documents in the collection that contain the following embedded document in the comments array:

{ author_id: ObjectId(...),
  date: Date(...),
  text: "Please expand the olive selection." }