range
Definition
range
The
range
operator supports querying and scoring numeric, date, and string 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.String fields of BSON
string
data type indexed as Atlas Search token type.
You can use the
range
operator to find results that are within a given numeric, date, or letter (from the English alphabet) range.
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. You can modify the default score using the following options:
For information on using NoteWhen 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. | 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 the
runtime
field only 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 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
andruntime
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 ])
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") }
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' } ]