Docs Menu

Docs HomeLaunch & Manage MongoDBMongoDB Atlas

range

On this page

  • Definition
  • Syntax
  • Options
  • Examples
  • Number Example
  • Date Example
  • String Example
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, and double 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.

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}

range uses the following terms to construct a query:

Field
Type
Description
Necessity
gt or gte
BSON date or number

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.

no
lt or lte
BSON date or number

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.

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.

For information on using score in your query, see Score the Documents in the Results.

Note

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.

no

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.

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

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.

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.

1db.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") }

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.

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"
}
}
}
}

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.

1db.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' }
]
←  queryStringregex →