range¶
On this page
Definition¶
range
¶The
range
operator supports querying and scoring numeric and date values. This operator can be used to perform a search over:- Number fields of BSON
int32
,int64
, anddouble
data types. - Date fields of BSON
date
data type in ISODate format.
You can use the
range
operator to find results that are within a given numeric or date range.- Number fields of BSON
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 or number | Find values greater than (
| no |
lt or lte | BSON date or number | Find values less than (
| 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. Options are:
For information on using | no |
Limitation¶
You cannot use the range
operator to query values stored in an
array. Atlas Search cannot index numeric or date values if they are part of an
array.
Examples¶
The following examples use the movies
collection in the
sample_mflix
database. If you loaded the sample dataset on your cluster, you can create the static
indexes using the index definitions in the examples below and run the
example queries on your cluster.
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 uses the range
operator to query a number
field.
Example 1¶
The following example uses gte
and lte
fields to define the
numeric range to search.
The following index definition named runtimes
indexes the
runtime
field in the movies
collection.
{ "mappings": { "dynamic": false, "fields": { "runtime": { "type": "number" } } } }
The following query searches for movies with a runtime greater than
or equal to 2 and less than 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 "index": "runtimes", 5 "range": { 6 "path": "runtime", 7 "gte": 2, 8 "lte": 3 9 } 10 } 11 }, 12 { 13 $limit: 5 14 }, 15 { 16 $project: { 17 "_id": 0, 18 "title": 1, 19 "runtime": 1 20 } 21 } 22 ])
The above query returns the following search results:
{ "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." }
Example 2¶
The following example uses the lte
field to search for all values
less than or equal to the given value.
The following index definition named runtimes
indexes the
runtime
field in the movies
collection.
1 { 2 "mappings": { 3 "dynamic": false, 4 "fields": { 5 "runtime": { 6 "type": "number" 7 } 8 } 9 } 10 }
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 a $project
stage to:
- Exclude all fields except
title
andruntime
- Add a field named
score
1 db.movies.aggregate([ 2 { 3 $search: { 4 "index": "runtimes", 5 "range": { 6 "path": "runtime", 7 "lte": 2 8 } 9 } 10 }, 11 { 12 $limit: 5 13 }, 14 { 15 $project: { 16 "_id": 0, 17 "title": 1, 18 "runtime": 1, 19 score: { $meta: "searchScore" } 20 } 21 } 22 ])
The above query returns the following search results:
{ "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 }
Date Example¶
The following example uses the range
operator to query a date
field.
The following index definition named releaseddate
indexes the
released
field in the movies
collection:
{ "mappings": { "dynamic": false, "fields": { "released": { "type": "date" } } } }
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 "index": "releaseddate", 5 "range": { 6 "path": "released", 7 "gt": ISODate("2010-01-01T00:00:00.000Z"), 8 "lt": ISODate("2015-01-01T00:00:00.000Z") 9 } 10 } 11 }, 12 { 13 $limit: 5 14 }, 15 { 16 $project: { 17 "_id": 0, 18 "title": 1, 19 "released": 1 20 } 21 } 22 ])
The above query returns the following search results:
1 { "title" : "The Fall of the House of Usher", "released" : ISODate("2011-09-20T00:00:00Z") } 2 { "title" : "The Blood of a Poet", "released" : ISODate("2010-05-20T00:00:00Z") } 3 { "title" : "Too Much Johnson", "released" : ISODate("2014-08-30T00:00:00Z") } 4 { "title" : "Stolen Desire", "released" : ISODate("2012-07-01T00:00:00Z") } 5 { "title" : "The Monkey King", "released" : ISODate("2012-01-12T00:00:00Z") }