range

On this page

Definition

Syntax
Options
Limitation
Examples

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, and double 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.

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 (`>`) 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.	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.	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: `boost`: multiply the result score by the given number. `constant`: replace the result score with the given number. For information on using `score` in your query, see Customize the Score in Results.	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.

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 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.

Example

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.

Example

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 and runtime
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.

Example

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

← 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	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	])

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	"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	])

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

range.css-134mg1q{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.css-6vrlzm{border-radius:0!important;display:initial!important;margin:initial!important;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

Definition

Syntax

Options

Limitation

Examples

Number Example

Example 1

Example 2

Date Example

range