Create an Atlas Search Index¶
On this page
You can also manage Atlas Search indexes with the Atlas API.
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.
Unlike compound indexes, the order of fields in the Atlas Search index definition is not important. Fields can be defined in any order.
The index name defaults to default. You can leave the default name in place or choose one of your own.
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.
Prerequisites¶
To create an Atlas Search index, you must have an Atlas cluster with:
- MongoDB version
4.2or higher - At least one collection
You must have the:
Project Data Access Read Onlyor higher role to view Atlas Search analyzers and indexes using the Atlas UI or API.Project Data Access Adminor higher role to create and manage Atlas Search analyzers and indexes using the Atlas UI or API.
Procedure¶
Navigate to the Atlas Cluster Overview page.¶
Click Databases 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.
NoteThe Visual Editor doesn't support custom analyzers or synonym mapping definitions.
- 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.
The index name defaults to default. You can leave the default name in place or choose one of your own.
NoteIf 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.Index names must be unique within their namespace.
- 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.¶
If you are satisfied with the default configuration, skip to step 9. If you wish to refine your Atlas Search index, proceed to the next step.
Defining your own field mappings is recommended for advanced users only.
Customize your Atlas Search index configuration settings.¶
If you are using the Visual Editor, click Refine Your Index to make changes to any of the following settings and click Save Changes.
Field NameDescriptionNecessityIndex AnalyzerOptionalSearch AnalyzerOptionalDynamic MappingSpecify dynamic or static mapping of fields. To disable dynamic mapping, set
"dynamic":toOff. By default, dynamic mapping is enabled. If you disable dynamic mapping, you must specify the fields to index. To learn more about dynamic and static mappings, see Define Atlas Search Indexes.Corresponds to the
mappings.dynamicsetting.RequiredField MappingsRequired if dynamic mapping is disabled.
To add the fields to index, you must specify the following settings for each field:
- Field name - Name of the field to index.
- Enable Dynamic Mapping - Static or dynamic mapping to use. If you disable dynamic mapping, the data in the field isn't automatically indexed.
- Data Type Configuration - Field data type. To learn more about the supported data types and their options, see BSON Data Types and Atlas Search Field Types.
NoteUnlike compound indexes, the order of fields in the Atlas Search index definition is not important. Fields can be defined in any order.
Corresponds to the
mappings.fieldssetting.ConditionalIf you are using the JSON Editor, replace the default definition with any of the following settings and click Next. To learn more about index definition settings, see Define Atlas Search Indexes.
Field NameDescriptionNecessityanalyzerOptionalsearchAnalyzerOptionalmappings.dynamicSpecify dynamic or static mapping of fields. To disable dynamic mapping, set
"dynamic":tofalse. By default, dynamic mapping is enabled. If you disable dynamic mapping, you must specify the fields to index. To learn more about dynamic and static mappings, see Define Atlas Search Indexes.Requiredmappings.fieldsRequired if dynamic mapping is disabled.
To add the fields to index, you must specify the following settings for each field:
- Field name - Name of the field to index.
- Enable Dynamic Mapping - Static or dynamic mapping to use. If you disable dynamic mapping, the data in the field isn't automatically indexed.
- Data Type Configuration - Field data type. To learn more about the supported data types and their options, see BSON Data Types and Atlas Search Field Types.
NoteUnlike compound indexes, the order of fields in the Atlas Search index definition is not important. Fields can be defined in any order.
Conditional
Optional: If you use the Visual Editor, you can save or delete your index definition draft.¶
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.
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 one of the following buttons.¶
- Create Search Index if you are creating a default index.
- Save Changes if you are creating a custom 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.
Larger collections take longer to index. You will receive an email notification when your index is finished building.
Node Status¶
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. In this state, Atlas Search does not serve queries. |
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.