Database Manual / Reference / mongosh Methods / MongoDB Search Index

db.collection.createSearchIndex() (mongosh method)

Definition

db.collection.createSearchIndex()

New in version 7.0: (Also available starting in 6.0.7)

Creates an MongoDB Search index or Vector Search index on a specified collection or view.

Important

mongosh Method

This page documents a mongosh method. This is not the documentation for database commands or language-specific drivers, such as Node.js.

For the database command, see the createSearchIndexes command.

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

Compatibility

This method is available in deployments hosted in the following environments:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Important

This command is not supported in serverless instances. For more information, see Unsupported Commands.

Syntax

Command syntax:

db.<collection>.createSearchIndex(
   <name>,
   <type>,
   {
      <definition>
   }
)

Command Fields

createSearchIndex() takes these fields:

Field Type Necessity Description

Field	Type	Necessity	Description
`name`	string	Optional	Name of the search index to create. You cannot create multiple indexes with the same name on a single collection. If you do not specify a `name`, the index is named `default`.
`type`	string	Optional	Type of search index to create. You can specify either: `search` `vectorSearch` If you omit the `type` field, the index type is `search`.
`definition`	document	Required	Document describing the index to create. The `definition` syntax depends on whether you create a standard search index or a Vector Search index. For the `definition` syntax, see: Search Index Definition Syntax Vector Search Index Definition Syntax

name

string

Optional

Name of the search index to create.

You cannot create multiple indexes with the same name on a single collection.

If you do not specify a name, the index is named default.

type

string

Optional

Type of search index to create. You can specify either:

search
vectorSearch

If you omit the type field, the index type is search.

definition

document

Required

Document describing the index to create. The definition syntax depends on whether you create a standard search index or a Vector Search index. For the definition syntax, see:

Search Index Definition Syntax

The search index definition takes the following fields:

{
   analyzer: "<analyzer-for-index>",
   searchAnalyzer: "<analyzer-for-query>",
   mappings: {
      dynamic: <boolean>,
      fields: { <field-definition> }
   },
   analyzers: [ <custom-analyzer> ],
   storedSource: <boolean> | {
      <stored-source-definition>
   },
   synonyms: [ {
      name: "<synonym-mapping-name>",
      source: {
         collection: "<source-collection-name>"
      },
      analyzer: "<synonym-mapping-analyzer>"
   } ]
}

Field	Type	Necessity	Description
`analyzer`	string	Optional	Specifies the analyzer to apply to string fields when indexing. If you omit this field, the index uses the standard analyzer.
`searchAnalyzer`	string	Optional	Specifies the analyzer to apply to query text before the text is searched. If you omit this field, the index uses the same analyzer specified in the `analyzer` field. If you omit both the `searchAnalyzer` and the `analyzer` fields, the index uses the standard analyzer.
`mappings`	object	Required	Specifies how to index fields on different paths for this index.
`mappings.dynamic`	boolean	Optional	Enables or disables dynamic field mapping for this index. If set to `true`, the index contains all fields containing supported data types. If set to `false`, you must specify individual fields to index using `mappings.fields`. If omitted, defaults to `false`.
`mappings.fields`	document	Conditional	Required only if dynamic mapping is disabled. Specifies the fields to index. To learn more, see Define Field Mappings.
`analyzers`	array	Optional	Specifies the Custom Analyzers to use in this index.
`storedSource`	boolean or Stored Source Definition	Optional	Specifies document fields to store for queries performed using the returnedStoredSource option. You can store fields of all MongoDB Search Field Types on MongoDB Search. The `storedSource` value can be one of these: `true`, to store all fields `false`, to not store any fields An object that specifies the fields to `include` or `exclude` from storage If omitted, defaults to `false`. To learn more, see Define Stored Source Fields in Your MongoDB Search Index.
`synonyms`	array of Synonym Mapping Definitions	Optional	Specifies synonym mappings to use in your index. Configuring synonyms allows you to index and search for words that have the same or a similar meaning. To learn more, see Define Synonym Mappings in Your MongoDB Search Index.

Vector Search Index Definition Syntax

The vector search index definition takes the following fields:

{
  "fields": [
    {
      "type": "vector" | "filter",
      "path": "<field-to-index>",
      "numDimensions": <number-of-dimensions>,
      "similarity": "euclidean" | "cosine" | "dotProduct"
    }
  ]
}

For explanations of vector search index definition fields, see How to Index Fields for Vector Search.

Behavior

createSearchIndex() triggers an index build. There may be a delay between when you receive a response from the command and when the index is ready.

To see the status of your search indexes, use the $listSearchIndexes aggregation stage.

Access Control

If your deployment enforces access control, the user running createSearchIndex() must have the createSearchIndexes privilege action on the database or collection:

{
   resource: {
      db : <database>,
      collection: <collection>
   },
   actions: [ "createSearchIndexes" ]
}

The built-in readWrite role provides the createSearchIndexes privilege. The following example grants accountUser01 the readWrite role on the products database:

db.grantRolesToUser(
   "accountUser01",
   [ { role: "readWrite", db: "products" } ]
)

Examples

Create a Search Index on All Fields

The following example creates a search index named searchIndex01 on the movies collection:

db.movies.createSearchIndex(
   "searchIndex01",
   { mappings: { dynamic: true } }
)

The index definition specifies mappings: { dynamic: true }, which means that the index contains all fields in the collection that have supported data types.

Create a Search Index with a Language Analyzer

A language analyzer introduces stop-words, which are words that are not significant enough to be indexed.

The following example creates a search index named frenchIndex01 on the cars collection, and specifies the lucene.french analyzer on the fr field:

db.cars.createSearchIndex(
   "frenchIndex01",
   {
      mappings: {
         fields: {
            subject: {
               fields: {
                  fr: {
                     analyzer: "lucene.french",
                     type: "string"
                  }
               },
               type: "document"
            }
         }
      }
   }
)

To learn more about language analyzers, see Language Analyzers.

Create a Search Index with the Default Name

The following createSearchIndex() method only specifies the index definition and omits the index name. The command creates a search index with the name default on the food collection:

db.food.createSearchIndex(
   {
      mappings: {
         fields: {
            title: {
               type: "string"
            }
         }
      }
   }
)

Create a Vector Search Index

The following example creates a vector search index named vectorSearchIndex01 on the movies collection:

db.movies.createSearchIndex(
   "vectorSearchIndex01",
   "vectorSearch",
   {
      fields: [
         {
            type: "vector",
            numDimensions: 1,
            path: "genre",
            similarity: "cosine"
         }
      ]
   }
)

The vector search index contains one dimension and indexes the genre field.

Learn More

Back

MongoDB Search Index

db.collection.dropSearchIndex