Docs Menu

Docs HomeLaunch & Manage MongoDBMongoDB Atlas

Create an Atlas Search Index

On this page

  • Prerequisites
  • Required Access
  • Create an Atlas Search Index Using the Atlas UI
  • Create an Atlas Search Index Using the Atlas Search API
  • Create an Atlas Search Index Using the Atlas CLI
  • Create an Atlas Search Index Programmatically
  • Node Status

Atlas Search index is a data structure that categorizes data in an easily searchable format. It is a mapping between terms and the documents that contain those terms. Atlas Search indexes enable faster retrieval of documents using certain identifiers. You must configure an Atlas Search index to query data in your Atlas cluster using Atlas Search.

You can create an Atlas Search index on a single field or on multiple fields. We recommend that you index the fields that you regularly use to sort or filter your data in order to quickly retrieve the documents that contain the relevant data at query-time.

You can create an Atlas Search index for all collections except time series collections on your Atlas cluster through the Atlas UI, API, Atlas CLI, and Terraform.

Important

If you use the $out aggregation stage to modify a collection with an Atlas Search index, you must delete and re-create the search index. If possible, consider using $merge instead of $out.

To create an Atlas Search index, you must have an Atlas cluster with:

  • MongoDB version 4.2 or higher

  • Collection to create the Atlas Search index for

The following table shows the modes of access each role supports.

Role
Action
Atlas UI
Atlas API
Atlas Search API
Atlas CLI
Project Data Access Read Only or higher role
To view Atlas Search analyzers and indexes.
To create and manage Atlas Search analyzers and indexes, and assign the role to your API Key.
To create access list entries for your API Key and send the request from a client that appears in the access list for your API Key.
To create, view, edit, and delete Atlas Search indexes using the Atlas UI or API.

Note

You cannot create more than:

  • 3 indexes on M0 clusters.

  • 5 indexes on M2 clusters.

  • 10 indexes on M5 clusters.

There are no limits to the number of indexes you can create on M10+ clusters.

When you create a new Atlas Search index, choose a configuration method.

Screenshot of Create an Atlas Search Index modal window
click to enlarge

You can specify the type of index that you want to create. For $search queries, if you don't explicitly specify type, the type defaults to search.

You can use either the default index definition or specify a custom definition for the index. The default index definition is dynamic mapping of fields in the documents and will work with any collection. If you wish to create a custom index definition for static mapping, you can specify which fields to index with which analyzer and as which data type.

The index name defaults to default. You can leave the default name in place or choose one of your own.

Note

If you name your index default, you don't need to specify an index parameter when using the $search pipeline stage. Otherwise, you must specify the index name using the index parameter.

Index names must be unique within their namespace.

Follow along with this video tutorial walk-through that demonstrates how to create Atlas Search indexes of various complexity.

Duration: 15 Minutes

To create an Atlas Search index from the Atlas UI:

1

Click Database in the top-left corner of Atlas to navigate to the Database Deployments page for your project.

2
3
4

Click Create Search Index.

5
  • For a guided experience, select the Atlas Search Visual Editor.

  • To edit the raw index definition, select the Atlas Search JSON Editor.

6
  1. In the Index Name field, enter a name for the index.

    Note

    If you name your index default, you don't need to specify an index parameter when using the $search pipeline stage. Otherwise, you must specify the index name using the index parameter.

  2. In the Database and Collection section, find the database or collection, and select the collection name.

  3. If you use the Visual Editor, click Next.

7

If you are satisfied with the default configuration, skip to step 10. If you wish to refine your Atlas Search index, proceed to the next step.

8
9

Note

If you use the Visual Editor and your index definition contains static mappings, you can save an index definition as a draft. You can't save the default index definition as a draft. You can save only a custom index definition as a draft.

  1. Click Cancel.

  2. Click Save Draft or Delete Draft.

Important

You can't create a new index when you have a pending index draft.

To learn more about creating an index using an index draft, see Resume or Delete an Atlas Search Index Draft.

10
11

A modal window appears to let you know your index is building. Click the Close button.

12

The newly created index appears on the Atlas Search tab. While the index is building, the Status field reads Build in Progress. When the index is finished building, the Status field reads Active.

Note

Larger collections take longer to index. You will receive an email notification when your index is finished building.

To create an Atlas Search index, send a POST request to the fts/indexes endpoint. To learn more about the syntax and parameters for this endpoint, see Create One.

Note

Atlas doesn't create the index if the collection doesn't exist, but it still returns a 200 status.

You can also use Atlas Search with local Atlas deployments that you create with the Atlas CLI. To learn more, see Create a Local Atlas Deployment.

To create a search index for a cluster using the Atlas CLI, run the following command:

atlas clusters search indexes create [indexName] [options]

To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas clusters search indexes create.

Tip

See: Related Links

To create a search index for the specified deployment using the Atlas CLI, run the following command:

atlas deployments search indexes create [indexName] [options]

To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas deployments search indexes create.

You can create an Atlas Search index programmatically by using mongosh or a supported MongoDB Driver in your preferred language.

Note

You can't use the mongosh command or driver helper methods to create Atlas Search indexes on M0, M2, or M5 Atlas clusters. To create Atlas Search indexes using mongosh or the driver, upgrade to a dedicated cluster tier.

You must have at least the readWriteAnyDatabase role or readWrite access to the database that contains the indexes. To learn more, see Built-in Roles or Specific Privileges.


Use the Select your language drop-down menu to set the language of the example in this section.


When you create the Atlas Search index, the Atlas Search Indexes tab in the right-side panel of the Atlas UI displays information about Atlas Search indexes for the selected namespace. The Status column shows the current state of the index on the primary node of the cluster. Click the View status details link below the status to view the state of the index on all the nodes of the cluster.

Screenshot of Atlas Search Index information panel
click to enlarge

When the Status column reads Active, the index is ready to use. In other states, queries against the index may return incomplete results.

Status
Description
Not Started
Atlas has not yet started building the index.
Initial Sync

Atlas is building the index or re-building the index after an edit. When the index is in this state:

  • For a new index, Atlas Search doesn't serve queries until the index build is complete.

  • For an existing index, you can continue to use the old index for existing and new queries until the index rebuild is complete.

Active
Index is ready to use.
Recovering
Replication encountered an error. This state commonly occurs when the current replication point is no longer available on the mongod oplog. You can still query the existing index until it updates and its status changes to Active. Use the error in the View status details modal window to troubleshoot the issue. To learn more, see Fix Atlas Search Issues.
Failed
Atlas could not build the index. Use the error in the View status details modal window to troubleshoot the issue. To learn more, see Fix Atlas Search Issues.
Delete in Progress
Atlas is deleting the index from the cluster nodes.

While Atlas builds the index and after the build completes, the Documents column shows the percentage and number of documents indexed. The column also shows the total number of documents in the collection.

Warning

If you shard a collection that already has an Atlas Search index, you might experience a brief period of query downtime when the collection begins to appear on a shard. Also, if you add a shard for an already sharded collection that contains an Atlas Search index, your search queries against that collection will fail until the initial sync process completes on the added shards. To learn more, see initial sync process.

←  Create and Manage Atlas Search IndexesProcess Data with Analyzers →