Docs Menu

Create an Atlas Search Index

On this page

  • Prerequisites
  • 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
  • Node Status

You can create an Atlas Search index through the Atlas UI, API, and Atlas CLI.

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
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.

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

Screenshot of Create an Atlas Search Index modal window

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.

To create an Atlas Search index from the Atlas UI:

1

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

2
3
4
  • For your first index, click Create Search Index.
  • For subsequent indexes, click Create Index.
5
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 9. If you wish to refine your Atlas Search index, proceed to the next step.

Note

Defining your own field mappings is recommended for advanced users only.

8
  • 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 Name
    Description
    Necessity
    Index Analyzer

    Specify the analyzer to use for indexing the collection data. By default, Atlas Search uses the standard analyzer ("lucene.standard").

    Corresponds to the analyzer setting.

    Optional
    Search Analyzer

    Specify the analyzer to use when parsing data for the Atlas Search queries. By default, Atlas Search uses the standard analyzer ("lucene.standard").

    Corresponds to the searchAnalyzer setting.

    Optional
    Dynamic Mapping

    Specify dynamic or static mapping of fields. To disable dynamic mapping, set "dynamic": to Off. 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 Review Atlas Search Index Syntax.

    Corresponds to the mappings.dynamic setting.

    Required
    Store Full Document

    Specify whether to store entire documents on Atlas Search for query-time lookups. If this is enabled, Atlas Search stores all the fields in the documents by default. You can exclude specific fields from storage on Atlas Search in the Field Mappings definition for the fields. To learn more about storing fields, see Define Stored Source Fields in Your Atlas Search Index.

    Required
    Field Mappings

    Required 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.
    • Store Original Value - Flag to store field on Atlas Search for query-time lookups. This is enabled by default if Store Full Document is enabled. However, you can toggle the setting to Off to exclude the field from storage. To learn more about storing fields, see Define Stored Source Fields in Your Atlas Search Index.
    • 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.
    Note

    Unlike 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.fields setting.

    Conditional
  • If 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 Review Atlas Search Index Syntax.

    Field Name
    Description
    Necessity
    analyzer

    Specify the analyzer to use for indexing the collection data. By default, Atlas Search uses the standard analyzer ("lucene.standard").

    Optional
    searchAnalyzer

    Specify the analyzer to use when parsing data for the Atlas Search queries. By default, Atlas Search uses the standard analyzer ("lucene.standard").

    Optional
    mappings.dynamic

    Specify dynamic or static mapping of fields. To disable dynamic mapping, set "dynamic": to false. 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 Review Atlas Search Index Syntax.

    Required
    mappings.fields

    Required if dynamic mapping is disabled.

    Specify the fields that you would like to index. To learn more, see Define Field Mappings.

    Note

    Unlike compound indexes, the order of fields in the Atlas Search index definition is not important. Fields can be defined in any order.

    Conditional
    storedSource
    Note

    storedSource is only available on Atlas clusters running one of the following versions:

    • MongoDB 4.4.12+
    • MongoDB 5.0.6+
    • MongoDB 6.0+ (including release candidates)

    Specify fields in the documents to store for query-time look-ups using the returnedStoredSource option. Value can be one of the following:

    • true, to store all fields
    • false, to not store any fields
    • Object that specifies the fields to include or exclude from storage

    If omitted, defaults to false. To learn more about the syntax and fields, see Define Stored Source Fields in Your Atlas Search Index.

    Note

    You can store fields of all BSON Data Types on Atlas Search.

    Optional
    synonyms
    Specify synonym mappings to use in your index. To learn more, see Define Synonym Mappings in Your Atlas Search Index.
    Optional
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
  • Create Search Index if you are creating a default index.
  • Save Changes if you are creating a custom index.
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 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 an Atlas Search Index.

Note

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

To create an Atlas Search index:

1
3

Run the atlas clusters search indexes create command. To learn more about the syntax and options for the command, see atlas clusters search indexes create.

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

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.

←  Create and Manage Atlas Search IndexesProcess Data with Analyzers →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.