Create an Atlas Search Index
On this page
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
Prerequisites
To create an Atlas Search index, you must have an Atlas cluster with:
MongoDB version
4.2or higherCollection 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. | ✓ | ✓ | ||
Project Data Access Admin or higher role | To create and manage Atlas Search analyzers and indexes, and
assign the role to your API Key. | ✓ | ✓ | ✓ | ✓ |
Project Owner role | ✓ | ✓ | |||
Organization Owner role | 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
M0clusters.5 indexes on
M2clusters.10 indexes on
M5clusters.
There are no limits to the number of indexes you can create on M10+ clusters.
Create an Atlas Search Index Using the Atlas UI
When you create a new Atlas Search index, choose a configuration method.
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.
Prefer to Learn by Watching?
Follow along with this video tutorial walk-through that demonstrates how to create Atlas Search indexes of various complexity.
Duration: 15 Minutes
Procedure
To create an Atlas Search index from the Atlas UI:
Navigate to the Atlas Cluster Overview page.
Click Database in the top-left corner of Atlas to navigate to the Database Deployments page for your project.
Click the cluster name to view cluster details.
Click the Search tab.
Create an index.
For your first index, click Create Search Index.
For subsequent indexes, click Create Index.
Select a Configuration Method and click Next.
For a guided experience, select Visual Editor.
Note
The Visual Editor doesn't support custom analyzers.
To edit the raw index definition, select JSON Editor.
Enter the Index Name, and set the Database and Collection.
In the Index Name field, enter a name for the index.
Note
If you name your index
default, you don't need to specify anindexparameter when using the $search pipeline stage. Otherwise, you must specify the index name using theindexparameter.In the Database and Collection section, find the database or collection, and select the collection name.
If you use the Visual Editor, click Next.
Review the default Atlas Search index configuration settings in the Index Configurations section.
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.
Refine your Atlas Search index to configure additional settings.
Optional: If you use the Visual Editor, you can save or delete your index definition draft.
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.
Click Cancel.
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.
Click Create Search Index.
Close the You're All Set! Modal Window.
A modal window appears to let you know your index is building. Click the Close button.
Check the status.
The newly created index appears on the 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.
Create an Atlas Search Index Using the Atlas Search API
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.
Create an Atlas Search Index Using the Atlas CLI
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
Node Status
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.
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:
|
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.
Note
If you run sh.shardCollection() on an
unsharded collection with Atlas Search indexes, the Atlas Search indexes
might enter an invalid state after sharding. To mitigate this issue,
you can create a new index on the collection after sharding, or
contact support to restart the mongot
processes on the nodes.