Indexes

Query Coverage and Performance

When you execute a query against MongoDB, your command can include various elements:

• Query criteria that specify fields and values you are looking for

• Options that affect the query's execution, such as read concern

• Projection criteria to specify the fields MongoDB returns (optional)

• Sort criteria to specify the order of documents returned from MongoDB (optional)

When all the fields specified in the query, projection, and sort are in the same index, MongoDB returns results directly from the index, also called a covered query.

name_1_age_-1

For more information about how to ensure your index covers your query criteria and projection, see the MongoDB manual articles on query coverage.

Operational Considerations

To improve query performance, build indexes on fields that appear often in your application's queries and operations that return sorted results. Each index that you add consumes disk space and memory when active, so we recommend that you track index memory and disk usage for capacity planning. In addition, when a write operation updates an indexed field, MongoDB updates the related index.

Since MongoDB supports dynamic schemas, applications can query against fields whose names cannot be known in advance or are arbitrary. MongoDB 4.2 introduced wildcard indexes to help support these queries. Wildcard indexes are not designed to replace workload-based index planning.

For more information about designing your data model and choosing indexes appropriate for your application, see the MongoDB Server Data Modeling and Indexes.

Single Field and Compound Indexes

String resultCreateIndex = collection.createIndex(Indexes.ascending("title"));
System.out.println(String.format("Index created: %s", resultCreateIndex));

Bson filter = eq("title", "Batman");
Bson sort = Sorts.ascending("title");
Bson projection = fields(include("title"), excludeId());
FindIterable<Document> cursor = collection.find(filter).sort(sort).projection(projection);

String resultCreateIndex = collection.createIndex(Indexes.ascending("type", "rated"));
System.out.println(String.format("Index created: %s", resultCreateIndex));

Bson filter = and(eq("type", "movie"), eq("rated", "G"));
Bson sort = Sorts.ascending("type", "rated");
Bson projection = fields(include("type", "rated"), excludeId());
FindIterable<Document> cursor = collection.find(filter).sort(sort).projection(projection);

Multikey Indexes (Indexes on Array Fields)

Multikey indexes are indexes that improve performance for queries that specify a field with an index that contains an array value. You can define a multikey index using the same syntax as a single field or compound index.

The following example creates a compound, multikey index on the rated, genres (an array of Strings), and title fields:

String resultCreateIndex = collection.createIndex(Indexes.ascending("rated", "genres", "title"));
System.out.println(String.format("Index created: %s", resultCreateIndex));

The following is an example of a query that is covered by the index created in the preceding code snippet:

Bson filter = and(eq("genres", "Animation"), eq("rated", "G"));
Bson sort = Sorts.ascending("title");
Bson projection = fields(include("title", "rated"), excludeId());
FindIterable<Document> cursor = collection.find(filter).sort(sort).projection(projection);

Multikey indexes behave differently from other indexes in terms of query coverage, index bound computation, and sort behavior. To learn more about multikey indexes, including a discussion of their behavior and limitations, see the Multikey Indexes page in the MongoDB manual.

Atlas Search and Vector Search Indexes

You can programmatically manage your Atlas Search and Atlas Vector Search indexes by using the Java driver.

The Atlas Search feature enables you to perform full-text searches on collections hosted on MongoDB Atlas. To learn more about MongoDB Atlas Search, see the Atlas Search Indexes documentation.

Atlas Vector Search enables you to perform semantic searches on vector embeddings stored in MongoDB Atlas. To learn more about Atlas Vector Search, see the Atlas Vector Search section in the Aggregates Builder guide.

You can call the following methods on a collection to manage your Atlas Search and Vector Search indexes:

• createSearchIndex() (valid for Atlas Search indexes only)

• createSearchIndexes()

• listSearchIndexes()

• updateSearchIndex()

• dropSearchIndex()

The following sections provide code examples that demonstrate how to use each of the preceding methods.

Document searchIdx = new Document("mappings",
        new Document("dynamic", true));
collection.createSearchIndex("myIndex", searchIdx);

SearchIndexModel searchIdxMdl = new SearchIndexModel(
    "searchIdx",
    new Document("analyzer", "lucene.standard").append(
        "mappings", new Document("dynamic", true)),
    SearchIndexType.search()
);
SearchIndexModel vectorSearchIdxMdl = new SearchIndexModel(
    "vsIdx",
    new Document(
        "fields",
        Arrays.asList(
            new Document("type", "vector")
                .append("path", "embeddings")
                .append("numDimensions", 1536)
                .append("similarity", "dotProduct")
        )
    ),
    SearchIndexType.vectorSearch()
);
collection.createSearchIndexes(
    Arrays.asList(searchIdxMdl, vectorSearchIdxMdl)
);

try (MongoCursor<Document> resultsCursor = collection.listSearchIndexes().iterator()) {
    while (resultsCursor.hasNext()) {
        System.out.println(resultsCursor.next());
    }
}

collection.updateSearchIndex("myIndex",
        new Document("analyzer", "lucene.simple").append(
                "mappings",
                new Document("dynamic", false)
                        .append("fields",
                                new Document("title",
                                        new Document("type", "string")))
        )
);

collection.dropSearchIndex("myIndex");

Text Indexes

Text indexes support text search queries on string content. These indexes can include any field whose value is a string or an array of string elements. MongoDB supports text search for various languages. You can specify the default language as an option when creating the index.

try {
    String resultCreateIndex = collection.createIndex(Indexes.text("plot"));
    System.out.println(String.format("Index created: %s", resultCreateIndex));
// Prints a message if a text index already exists with a different configuration 
} catch (MongoCommandException e) {
    if (e.getErrorCodeName().equals("IndexOptionsConflict"))
        System.out.println("there's an existing text index with different options");
}

Bson filter = text("java coffee shop");
Bson projection = fields(include("fullplot"), excludeId());
FindIterable<Document> cursor = collection.find(filter).projection(projection);

collection.createIndex(Indexes.compoundIndex(Indexes.text("title"), Indexes.text("genre")));

Geospatial Indexes

MongoDB supports queries of geospatial coordinate data using 2dsphere indexes. With a 2dsphere index, you can query the geospatial data for inclusion, intersection, and proximity. For more information about querying geospatial data, see Geospatial Queries.

To create a 2dsphere index, you must specify a field that contains only GeoJSON objects. For more details on this type, see the MongoDB Server manual page on GeoJSON objects.

The location.geo field in the following sample document from the theaters collection in the sample_mflix database is a GeoJSON Point object that describes the coordinates of the theater:

{
   "_id" : ObjectId("59a47286cfa9a3a73e51e75c"),
   "theaterId" : 104,
   "location" : {
      "address" : {
         "street1" : "5000 W 147th St",
         "city" : "Hawthorne",
         "state" : "CA",
         "zipcode" : "90250"
      },
      "geo" : {
         "type" : "Point",
         "coordinates" : [
            -118.36559,
            33.897167
         ]
      }
   }
}

The following example creates a 2dsphere index on the location.geo field:

try {
    String resultCreateIndex = collection.createIndex(Indexes.geo2dsphere("location.geo"));
    System.out.println(String.format("Index created: %s", resultCreateIndex));
// Prints a message if a geospatial index already exists with a different configuration 
} catch (MongoCommandException e) {
    if (e.getErrorCodeName().equals("IndexOptionsConflict"))
        System.out.println("there's an existing geospatial index with different options");
}

The following is an example of a geospatial query using the "location.geo" index.

// Stores the coordinates of the NY MongoDB headquarters
Point refPoint = new Point(new Position(-73.98456, 40.7612));
// Retrieves documents that represent locations up to 1000 meters from the specified point directly from the geospatial index
// Creates a filter to match a document 
Bson filter = near("location.geo", refPoint, 1000.0, 0.0);
FindIterable<Document> cursor = collection.find(filter);

MongoDB also supports 2d indexes for calculating distances on a Euclidean plane and for working with the "legacy coordinate pairs" syntax used in MongoDB 2.2 and earlier. For more information, see the Geospatial Queries page in the MongoDB Server manual.

Unique Indexes

Unique indexes ensure that the indexed fields do not store duplicate values. By default, MongoDB creates a unique index on the _id field during the creation of a collection. To create a unique index, specify the field or combination of fields that you want to prevent duplication on and set the unique option to true.

The following example creates a unique, descending index on the theaterId field:

try {
    IndexOptions indexOptions = new IndexOptions().unique(true);
    String resultCreateIndex = collection.createIndex(Indexes.descending("theaterId"), indexOptions);
    System.out.println(String.format("Index created: %s", resultCreateIndex));
// Prints a message if the "theaterID" field contains duplicate values
} catch (DuplicateKeyException e) {
    System.out.printf("duplicate field values encountered, couldn't create index: \t%s\n", e);
}

E11000 duplicate key error index

For more information, see the Unique Indexes page in the MongoDB Server manual.

Wildcard Indexes

Wildcard indexes enable queries against unknown or arbitrary fields. These indexes can be beneficial if you are using a dynamic schema.

The following example creates an ascending wildcard index on all values of the location field, including values nested in subdocuments and arrays:

String resultCreateIndex = collection.createIndex(Indexes.ascending("location.$**")); 
System.out.println(String.format("Index created: %s", resultCreateIndex));

For more information, see the Wildcard Indexes page in the MongoDB Server manual.

Clustered Indexes

Clustered indexes instruct a collection to store documents ordered by a key value. To create a clustered index, specify the clustered index option with the _id field as the key and the unique field as true when you create your collection.

The following example creates a clustered index on the _id field in the vendors collection:

MongoDatabase database = mongoClient.getDatabase("tea");
ClusteredIndexOptions clusteredIndexOptions = new ClusteredIndexOptions(new Document("_id", 1), true);
CreateCollectionOptions createCollectionOptions = new CreateCollectionOptions().clusteredIndexOptions(clusteredIndexOptions);
database.createCollection("vendors", createCollectionOptions);

See the MongoDB Server manual sections for more information:

• Clustered Index

• Clustered Collections

Remove an Index Using an Index Specification Document

Pass an index specification document to the dropIndex() method to remove an index from a collection. An index specification document is a Bson instance that specifies the type of index on a specified field.

The following snippet removes an ascending index on the title field in a collection:

collection.dropIndex(Indexes.ascending("title"));

Remove an Index Using a Name Field

Pass the name field of the index to the dropIndex() method to remove an index from a collection.

To find the name of your index, use the listIndexes() method to see the value of the name fields in your indexes.

The following snippet retrieves and prints all the indexes in a collection:

collection.listIndexes().forEach(doc -> System.out.println(doc.toJson()));

If you call listIndex() on a collection that contains a text index, the output might resemble the following:

{ "v": 2, "key": {"_id": 1}, "name": "_id_" }
{ "v": 2, "key": {"_fts": "text", "_ftsx": 1}, "name": "title_text", "weights": {"title": 1},
"default_language": "english", "language_override": "language", "textIndexVersion": 3 }

This output tells us the names of the existing indexes are "_id" and "title_text".

The following snippet removes the "title_text" index from the collection:

collection.dropIndex("title_text");

Remove an Index Using a Wildcard Character

Starting with MongoDB 4.2, you can drop all indexes by calling the dropIndexes() method on your collection:

collection.dropIndexes();

For prior versions of MongoDB, pass "*" as a parameter to your call to dropIndex() on your collection:

collection.dropIndex("*");

For more information about the methods in this section, see the following API Documentation:

• dropIndex()

• dropIndexes()