Create an Atlas Search Index using the Atlas Search API¶

On this page

Procedure

Next Steps

This part of the tutorial guides you through creating an Atlas Search index using the Atlas Search API.

Tip

You can also create Atlas Search indexes using the Atlas UI.

This tutorial uses the sample_mflix database and the movies collection from the Sample Mflix Dataset.

Procedure¶

Choose dynamic or static index mapping.¶

When you choose dynamic mapping, Atlas dynamically indexes the fields of the supported types for the documents in a collection. Dynamic mapping is useful if the schema of your documents changes regularly or is unknown.

Note

Dynamically mapped indexes occupy more disk space than statically mapped indexes and might be less performant.
You can't use multiple analyzers with a dynamically mapped index.

When you choose static mapping, Atlas indexes only the fields that you specify for the documents in a collection.

Note

Queries that use a statically mapped index won't return matches in document fields that are not mapped in the index.

Copy one of the sample cURL requests.¶

Copy the sample cURL request for your preferred index mapping:

Dynamic Mapping¶

The following index definition dynamically indexes the fields of supported types in the movies collection.

1 PUBLIC_KEY=MY_PUBLIC_KEY # replace replace with your public key
2 PRIVATE_KEY=MY_PRIVATE_KEY # replace with your private key
3 GROUP_ID=YOUR_GROUP_ID # replace with your project ID
4 CLUSTER_NAME=YOUR_CLUSTER_NAME # replace with your cluster's name
5 
6 curl --user "$PUBLIC_KEY:$PRIVATE_KEY" --digest \
7      --header "Content-Type: application/json" \
8      --include \
9      --request POST "https://cloud.mongodb.com/api/atlas/v1.0/groups/$GROUP_ID/clusters/$CLUSTER_NAME/fts/indexes?pretty=true" \
10      --data '{
11          "collectionName": "movies",
12          "database": "sample_mflix",
13          "mappings": {
14              "dynamic": true
15          },
16          "name": "default"
17        }'

Static Mapping¶

The movies collection is large, so in order to save space we will only index the title, genres, and plot fields.

The following index definition specifies:

The standard analyzer as the default analyzer for all three indexed fields.
The keyword analyzer as an alternate analyzer for the title field, with the name keywordAnalyzer. The keyword analyzer indexes the entire field as a single term, so it only returns results if the search term and the specified field match exactly. For more information about multi analyzer designations, see Path Construction.
The standard analyzer as the analyzer by default for queries on the genres field, which is an array of strings. For indexing arrays, Atlas Search only requires the data type of the array elements. You don't have to specify that the data is contained in an array in the index definition.

1 PUBLIC_KEY=MY_PUBLIC_KEY # replace replace with your public key
2 PRIVATE_KEY=MY_PRIVATE_KEY # replace with your private key
3 GROUP_ID=YOUR_GROUP_ID # replace with your project ID
4 CLUSTER_NAME=YOUR_CLUSTER_NAME # replace with your cluster's name
5 
6 curl --user "$PUBLIC_KEY:$PRIVATE_KEY" --digest \
7      --header "Content-Type: application/json" \
8      --include \
9      --request POST "https://cloud.mongodb.com/api/atlas/v1.0/groups/$GROUP_ID/clusters/$CLUSTER_NAME/fts/indexes?pretty=true" \
10      --data '{
11          "collectionName": "movies",
12          "database": "sample_mflix",
13          "mappings": {
14            "dynamic": false,
15            "fields": {
16              "title": {
17                "type": "string",
18                "analyzer": "lucene.standard",
19                "multi": {
20                  "keywordAnalyzer": {
21                    "type": "string",
22                    "analyzer": "lucene.keyword"
23                  }
24                }
25              },
26              "genres": {
27                "type": "string",
28                "analyzer": "lucene.standard"
29              },
30              "plot": {
31                "type": "string",
32                "analyzer": "lucene.standard"
33              }
34            }
35          },
36          "name": "default"
37        }'

Open your preferred text editor and paste the sample cURL request into a new text file.¶

Replace the variables in your sample cURL request.¶

The sample cURL requests use these variables. Replace these variables with your desired values before running the cURL command to create an Atlas Search index.

Name	Type	Description
PUBLIC_KEY	string	Your public API Key for your API credentials.
PRIVATE_KEY	string	Your private API Key for your API credentials.
GROUP_ID	string	Unique 24-hexadecimal character string that identifies the project that contains the cluster that contains the collection for which you want to create an Atlas Search index.
CLUSTER_NAME	string	Human-readable label that identifies the cluster that contains the collection for which you want to create an Atlas Search index. Use the Get All Clusters endpoint to get the CLUSTER_NAME. For each cluster, Atlas returns the CLUSTER_NAME in the name field.

Run the modified cURL request to create the Atlas Search index.¶

The response you receive differs based on the index mapping you chose:

Dynamic Mapping¶

1 {
2   "collectionName" : "movies",
3   "database" : "sample_mflix",
4   "indexID" : "60bfd25f59fc81594354eed3",
5   "mappings" : {
6     "dynamic" : true
7   },
8   "name" : "default",
9   "status" : "IN_PROGRESS"
10 }

Static Mapping¶

1 {
2   "collectionName" : "movies",
3   "database" : "sample_mflix",
4   "indexID" : "60bfd3b7f6884f18eaf0846d",
5   "mappings" : {
6     "dynamic" : false,
7     "fields" : {
8       "genres" : {
9         "analyzer" : "lucene.standard",
10         "type" : "string"
11       },
12       "plot" : {
13         "analyzer" : "lucene.standard",
14         "type" : "string"
15       },
16       "title" : {
17         "analyzer" : "lucene.standard",
18         "multi" : {
19           "keywordAnalyzer" : {
20             "analyzer" : "lucene.keyword",
21             "type" : "string"
22           }
23         },
24         "type" : "string"
25       }
26     }
27   },
28   "name" : "default",
29   "status" : "IN_PROGRESS"
30 }

Next Steps¶

Now that you have created the index, proceed to Run Atlas Search Queries.

1	PUBLIC_KEY=MY_PUBLIC_KEY # replace replace with your public key
2	PRIVATE_KEY=MY_PRIVATE_KEY # replace with your private key
3	GROUP_ID=YOUR_GROUP_ID # replace with your project ID
4	CLUSTER_NAME=YOUR_CLUSTER_NAME # replace with your cluster's name
5
6	curl --user "$PUBLIC_KEY:$PRIVATE_KEY" --digest \
7	--header "Content-Type: application/json" \
8	--include \
9	--request POST "https://cloud.mongodb.com/api/atlas/v1.0/groups/$GROUP_ID/clusters/$CLUSTER_NAME/fts/indexes?pretty=true" \
10	--data '{
11	"collectionName": "movies",
12	"database": "sample_mflix",
13	"mappings": {
14	"dynamic": true
15	},
16	"name": "default"
17	}'

1	{
2	"collectionName" : "movies",
3	"database" : "sample_mflix",
4	"indexID" : "60bfd25f59fc81594354eed3",
5	"mappings" : {
6	"dynamic" : true
7	},
8	"name" : "default",
9	"status" : "IN_PROGRESS"
10	}

1	{
2	"collectionName" : "movies",
3	"database" : "sample_mflix",
4	"indexID" : "60bfd3b7f6884f18eaf0846d",
5	"mappings" : {
6	"dynamic" : false,
7	"fields" : {
8	"genres" : {
9	"analyzer" : "lucene.standard",
10	"type" : "string"
11	},
12	"plot" : {
13	"analyzer" : "lucene.standard",
14	"type" : "string"
15	},
16	"title" : {
17	"analyzer" : "lucene.standard",
18	"multi" : {
19	"keywordAnalyzer" : {
20	"analyzer" : "lucene.keyword",
21	"type" : "string"
22	}
23	},
24	"type" : "string"
25	}
26	}
27	},
28	"name" : "default",
29	"status" : "IN_PROGRESS"
30	}