range

On this page

Definition

Syntax
Options
Examples
Number Example
Date Example
ObjectId Example
String Example

Definition

range

The range operator supports querying and scoring numeric, date, and string values. You can use this operator to find results that are within a given numeric, date, objectId, or letter (from the English alphabet) range.

range supports querying the following data types:

number, including int32, int64, and double
date
string, indexed as Atlas Search token type
objectId

Syntax

range has the following syntax:

1 {
2     "$search": {
3        "index": <index name>, // optional, defaults to "default"
4        "range": {
5           "path": "<field-to-search>",
6           "gt | gte": <value-to-search>,
7           "lt | lte": <value-to-search>,
8           "score": <score-options>
9        }
10     }
11 }

Options

range uses the following terms to construct a query:

Field	Type	Description	Necessity
`gt` or `gte`	BSON date, number, or string, or objectId	Find values greater than (`>`) or greater than or equal to (`>=`) the given value. For number fields, the value can be an `int32`, `int64`, or `double` data type. For date fields, the value must be an ISODate formatted date. For string fields, the value must be indexed as Atlas Search `token` type. For `ObjectId` fields, the value must be indexed as objectId data type or dynamic mappings must be set to `true`.	no
`lt` or `lte`	BSON date, number, or string, or objectId	Find values less than (`<`) or less than or equal to (`<=`) the given value. For number fields, the value can be an `int32`, `int64`, or `double` data type. For date fields, the value must be an ISODate formatted date. For string fields, the value must be indexed as Atlas Search `token` type. For `ObjectId` fields, the value must be indexed as objectId data type or dynamic mappings must be set to `true`.	no
`path`	string or array of strings	Indexed field or fields to search. See Path Construction.	yes
`score`	object	Modify the score assigned to matching search results. You can modify the default score using the following options: `boost`: multiply the result score by the given number. `constant`: replace the result score with the given number. `function`: replace the result score with the given expression. When you query values in arrays, Atlas Search doesn't alter the score of the matching results based on the number of values inside the array that matched the query. The score would be the same as a single match regardless of the number of matches inside an array. For information on using `score` in your query, see Score the Documents in the Results.	no

Examples

The following examples use the collection in the sample data. If you loaded the sample data on your cluster, you can create the indexes using the index definitions in the examples below and run the example queries on your cluster.

Tip

If you've already loaded the sample dataset, follow the Get Started with Atlas Search tutorial to create an index definition and run Atlas Search queries.

Number Example

The following examples use indexes on numeric fields in the sample data and run range queries against the indexed fields.

For this example, you can use either static or dynamic mappings to index the runtime field in the sample_mflix.movies collection. The query uses gte and lte fields to define the numeric range to search.

Sample Index

The following index definition named default indexes all the fields in the movies collection.

1 {
2   "mappings": {
3     "dynamic": true
4   }
5 }

The following index definition named default indexes the runtime field only in the movies collection.

1 {
2   "mappings": {
3     "dynamic": false,
4     "fields": {
5       "runtime": {
6         "type": "number"
7       }
8     }
9   }
10 }

Sample Query

The following query searches for movies with a runtime greater than or equal to 2 and less than or equal to 3. It includes a $limit stage to limit the output to 5 results and a $project stage to exclude all fields except title and runtime.

1 db.movies.aggregate([
2   {
3     "$search": {
4       "range": {
5         "path": "runtime",
6         "gte": 2,
7         "lte": 3
8       }
9     }
10   },
11   {
12     "$limit": 5
13   },
14   {
15     "$project": {
16       "_id": 0,
17       "title": 1,
18       "runtime": 1
19     }
20   }
21 ])

{ "runtime" : 3, "title" : "Dots" }
{ "runtime" : 3, "title" : "Sisyphus" }
{ "runtime" : 3, "title" : "The Fly" }
{ "runtime" : 2, "title" : "Andrè and Wally B." }
{ "runtime" : 2, "title" : "Luxo Jr." }

For this example, you can use either static or dynamic mappings to index the runtime field in the sample_mflix.movies collection. The query uses the lte field to search for all values less than or equal to the given value.

Sample Index

The following index definition named default indexes the runtime field in the movies collection.

1 {
2   "mappings": {
3     "dynamic": true
4   }
5 }

1 {
2   "mappings": {
3     "dynamic": false,
4     "fields": {
5       "runtime": {
6         "type": "number"
7       }
8     }
9   }
10 }

Sample Query

The following query searches for all movies with a runtime less than or equal to 2. It includes a $limit stage to limit the output to 5 results and $project stage to:

Exclude all fields except title and runtime
Add a field named score

1 db.movies.aggregate([
2   {
3     "$search": {
4       "range": {
5         "path": "runtime",
6         "lte": 2
7       }
8     }
9   },
10   {
11     "$limit": 5
12   },
13   {
14     "$project": {
15       "_id": 0,
16       "title": 1,
17       "runtime": 1,
18       score: { $meta: "searchScore" }
19     }
20   }
21 ])

{ "runtime" : 1, "title" : "Blacksmith Scene", "score" : 1 }
{ "runtime" : 2, "title" : "Andrè and Wally B.", "score" : 1 }
{ "runtime" : 2, "title" : "Luxo Jr.", "score" : 1 }
{ "runtime" : 1, "title" : "The Kiss", "score" : 1 }
{ "runtime" : 1, "title" : "Dickson Experimental Sound Film", "score" : 1 }

The following example dynamically indexes all the dynamically indexable fields, including fields with array of numeric values, in the sample_analytics.customers collection. The sample query uses the gte and lte fields to search for all values between the given values in an array of numeric values.

Sample Index

The following index definition named default dynamically indexes all fields, including the accounts field, which is an array of numeric values.

{
  "mappings": {
    "dynamic": true
  }
}

Sample Query

The following query searches for customer accounts between 250000 and 300000. It includes a $limit stage to limit the output to 5 results and a $project stage to exclude all fields except accounts and name.

1 db.customers.aggregate([
2   {
3     "$search": {
4       "range": {
5         "path": "accounts",
6         "gt": 250000,
7         "lt": 400000
8       }
9     }
10   },
11   {
12     "$limit": 5
13   },
14   {
15     "$project": {
16       "_id": 0,
17       "accounts": 1,
18       "name": 1
19     }
20   }
21 ])

1 [
2   {
3     name: 'Elizabeth Ray',
4     accounts: [ 371138, 324287, 276528, 332179, 422649, 387979 ]
5   },
6   {
7     name: 'Katherine David',
8     accounts: [ 462501, 228290, 968786, 515844, 377292 ]
9   },
10   {
11     name: 'Brad Cardenas',
12     accounts: [ 721914, 817222, 973067, 260799, 87389 ]
13   },
14   {
15     name: 'Gary Nichols',
16     accounts: [ 385397, 337979, 325377, 440243, 586395, 86702 ]
17   },
18   { name: 'Jennifer Lawrence', accounts: [ 344885, 839927, 853542 ] }
19 ]

Date Example

The following example uses the range operator to query a date field in the sample_mflix.movies collection. For this example, you can use either static or dynamic mappings to index the date type field named released in the collection.

Sample Index

The following index definition named default indexes all the dynamically indexable fields in the movies collection, including the released field, which is of type date.

{
   "mappings": {
      "dynamic": true
   }
}

The following index definition named default indexes the released field in the movies collection:

{
   "mappings": {
      "dynamic": false,
      "fields": {
         "released": {
            "type": "date"
         }
      }
   }
}

Sample Query

The following query searches for movies released between January 1, 2010 and January 1, 2015. It includes a $limit stage to limit the output to 5 results and a $project stage to exclude all fields except title and released.

1 db.movies.aggregate([
2   {
3     "$search": {
4       "range": {
5         "path": "released",
6         "gt": ISODate("2010-01-01T00:00:00.000Z"),
7         "lt": ISODate("2015-01-01T00:00:00.000Z")
8       }
9     }
10   },
11   {
12     "$limit": 5
13   },
14   {
15     "$project": {
16       "_id": 0,
17       "title": 1,
18       "released": 1
19     }
20   }
21 ])

1 [
2   {
3     title: 'Too Much Johnson',
4     released: ISODate('2014-08-30T00:00:00.000Z')
5   },
6   {
7     title: 'Stolen Desire',
8     released: ISODate('2012-07-01T00:00:00.000Z')
9   },
10   {
11     title: 'The Monkey King',
12     released: ISODate('2012-01-12T00:00:00.000Z')
13   },
14   { title: 'The Land', released: ISODate('2012-08-04T00:00:00.000Z') },
15   {
16     title: 'My Childhood',
17     released: ISODate('2013-07-31T00:00:00.000Z')
18   }
19 ]

ObjectId Example

The following example uses the range operator to query an objectId field in the sample_mflix.movies collection. For this example, you can use either static or dynamic mappings to index the objectId type field named _id in the collection.

Sample Index

The following index definition named default indexes all the fields in the movies collection.

The following index definition named default indexes all the dynamically indexable fields in the movies collection, including the _id field, which is of type objectId.

{
   "mappings": {
      "dynamic": true
   }
}

The following index definition named default indexes the _id field in the movies collection:

{
   "mappings": {
      "dynamic": false,
      "fields": {
         "_id": {
           "type": "objectId"
         }
      }
   }
}

Sample Query

The following example uses the range operator to query _id field for a range of objectId values in the sample_mflix.movies collection.

1 db.movies.aggregate([
2   {
3     "$search": {
4       "range": {
5         "path": "_id",
6         "gte": ObjectId("573a1396f29313caabce4a9a"),
7         "lte": ObjectId('573a1396f29313caabce4ae7')
8       }
9     }
10   },
11   {
12     "$project": {
13       "_id": 1,
14       "title": 1,
15       "released": 1
16     }
17   }
18 ])

1 [
2   {
3     _id: ObjectId('573a1396f29313caabce4a9a'),
4     title: 'The Godfather',
5     released: ISODate('1972-03-24T00:00:00.000Z')
6   },
7   {
8     _id: ObjectId('573a1396f29313caabce4a9b'),
9     title: 'Get to Know Your Rabbit',
10     released: ISODate('1972-06-01T00:00:00.000Z')
11   },
12   {
13     _id: ObjectId('573a1396f29313caabce4aad'),
14     title: 'The Tall Blond Man with One Black Shoe',
15     released: ISODate('1973-08-30T00:00:00.000Z')
16   },
17   {
18     _id: ObjectId('573a1396f29313caabce4abe'),
19     title: 'The Great Northfield Minnesota Raid',
20     released: ISODate('1972-05-12T00:00:00.000Z')
21   },
22   {
23     _id: ObjectId('573a1396f29313caabce4ac4'),
24     title: 'The Heartbreak Kid',
25     released: ISODate('1973-02-01T00:00:00.000Z')
26   },
27   {
28     _id: ObjectId('573a1396f29313caabce4ac7'),
29     title: 'Gumshoe',
30     released: ISODate('1971-12-01T00:00:00.000Z')
31   },
32   {
33     _id: ObjectId('573a1396f29313caabce4ad9'),
34     title: 'Heat',
35     released: ISODate('1972-10-06T00:00:00.000Z')
36   },
37   {
38     _id: ObjectId('573a1396f29313caabce4ae7'),
39     title: 'Horror Express',
40     released: ISODate('1973-12-01T00:00:00.000Z')
41   }
42 ]

String Example

The following example uses the range operator to query a string field in the sample_mflix.movies collection. For this example, you must use static mappings to index the field named title in the collection as Atlas Search token type.

Sample Index

The following index definition named default indexes the title field in the movies collection as Atlas Search token type:

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "title": {
        "type": "token",
        "normalizer": "lowercase"
      }
    }
  }
}

Sample Query

The following query searches for movie titles that contain characters between city and country. It includes a $limit stage to limit the output to 5 results and a $project stage to exclude all fields except title.

1 db.movies.aggregate([
2   {
3     "$search": {
4       "range": {
5         "path": "title",
6         "gt": "city",
7         "lt": "country"
8       }
9     }
10   },
11   {
12     "$limit": 5
13   },
14   {
15     "$project": {
16       "_id": 0,
17       "title": 1
18     }
19   }
20 ])

[
  { title: 'Civilization' },
  { title: 'Clash of the Wolves' },
  { title: 'City Lights' },
  { title: 'Comradeship' },
  { title: 'Come and Get It' }
]

Back

queryString

regex

1	{
2	"$search": {
3	"index": <index name>, // optional, defaults to "default"
4	"range": {
5	"path": "<field-to-search>",
6	"gt \| gte": <value-to-search>,
7	"lt \| lte": <value-to-search>,
8	"score": <score-options>
9	}
10	}
11	}

1	{
2	"mappings": {
3	"dynamic": false,
4	"fields": {
5	"runtime": {
6	"type": "number"
7	}
8	}
9	}
10	}

1	db.movies.aggregate([
2	{
3	"$search": {
4	"range": {
5	"path": "runtime",
6	"gte": 2,
7	"lte": 3
8	}
9	}
10	},
11	{
12	"$limit": 5
13	},
14	{
15	"$project": {
16	"_id": 0,
17	"title": 1,
18	"runtime": 1
19	}
20	}
21	])

1	db.customers.aggregate([
2	{
3	"$search": {
4	"range": {
5	"path": "accounts",
6	"gt": 250000,
7	"lt": 400000
8	}
9	}
10	},
11	{
12	"$limit": 5
13	},
14	{
15	"$project": {
16	"_id": 0,
17	"accounts": 1,
18	"name": 1
19	}
20	}
21	])

1	[
2	{
3	name: 'Elizabeth Ray',
4	accounts: [ 371138, 324287, 276528, 332179, 422649, 387979 ]
5	},
6	{
7	name: 'Katherine David',
8	accounts: [ 462501, 228290, 968786, 515844, 377292 ]
9	},
10	{
11	name: 'Brad Cardenas',
12	accounts: [ 721914, 817222, 973067, 260799, 87389 ]
13	},
14	{
15	name: 'Gary Nichols',
16	accounts: [ 385397, 337979, 325377, 440243, 586395, 86702 ]
17	},
18	{ name: 'Jennifer Lawrence', accounts: [ 344885, 839927, 853542 ] }
19	]

1	[
2	{
3	title: 'Too Much Johnson',
4	released: ISODate('2014-08-30T00:00:00.000Z')
5	},
6	{
7	title: 'Stolen Desire',
8	released: ISODate('2012-07-01T00:00:00.000Z')
9	},
10	{
11	title: 'The Monkey King',
12	released: ISODate('2012-01-12T00:00:00.000Z')
13	},
14	{ title: 'The Land', released: ISODate('2012-08-04T00:00:00.000Z') },
15	{
16	title: 'My Childhood',
17	released: ISODate('2013-07-31T00:00:00.000Z')
18	}
19	]

1	[
2	{
3	_id: ObjectId('573a1396f29313caabce4a9a'),
4	title: 'The Godfather',
5	released: ISODate('1972-03-24T00:00:00.000Z')
6	},
7	{
8	_id: ObjectId('573a1396f29313caabce4a9b'),
9	title: 'Get to Know Your Rabbit',
10	released: ISODate('1972-06-01T00:00:00.000Z')
11	},
12	{
13	_id: ObjectId('573a1396f29313caabce4aad'),
14	title: 'The Tall Blond Man with One Black Shoe',
15	released: ISODate('1973-08-30T00:00:00.000Z')
16	},
17	{
18	_id: ObjectId('573a1396f29313caabce4abe'),
19	title: 'The Great Northfield Minnesota Raid',
20	released: ISODate('1972-05-12T00:00:00.000Z')
21	},
22	{
23	_id: ObjectId('573a1396f29313caabce4ac4'),
24	title: 'The Heartbreak Kid',
25	released: ISODate('1973-02-01T00:00:00.000Z')
26	},
27	{
28	_id: ObjectId('573a1396f29313caabce4ac7'),
29	title: 'Gumshoe',
30	released: ISODate('1971-12-01T00:00:00.000Z')
31	},
32	{
33	_id: ObjectId('573a1396f29313caabce4ad9'),
34	title: 'Heat',
35	released: ISODate('1972-10-06T00:00:00.000Z')
36	},
37	{
38	_id: ObjectId('573a1396f29313caabce4ae7'),
39	title: 'Horror Express',
40	released: ISODate('1973-12-01T00:00:00.000Z')
41	}
42	]

range.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-fmznk8{margin-top:-85px;position:absolute;padding-bottom:2px;}

Definition

Syntax

Options

Examples

Tip

Number Example

Sample Index

Sample Query

Sample Index

Sample Query

Sample Index

Sample Query

Date Example

Sample Index

Sample Query

ObjectId Example

Sample Index

Sample Query

String Example

Sample Index

Sample Query

range