Create an Atlas Search Index using the Atlas Search API¶
On this page
This part of the tutorial guides you through creating an Atlas Search index using the Atlas Search API.
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.
- 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.
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 namekeywordAnalyzer
. 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 aboutmulti
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.