/ /

Operators & Collectors

Docs Home

/ /

Query Reference

Operators & Collectors

Operators & Collectors

`near` (MongoDB Search Operator)

`near` Operator Limitations

You can't use the near operator to query numeric or date values stored in an array, even if you have a MongoDB Search index. You can use the range only to query indexed numeric or date values inside arrays.

Definition

near

The near operator supports querying and scoring numeric, date, and GeoJSON point 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 type in ISODate format.
Geographic location fields defined using latitude and longitude coordinates.

You can use the near operator to find results that are near a number or a date. The near operator scores the MongoDB Search results by proximity to the number or date.

Syntax

near has the following syntax:

{
   $search: {
      "index": <index name>, // optional, defaults to "default"
      "near": {
         "path": "<field-to-search>",
         "origin": <date-or-number>,
         "pivot": <pivot-distance>,
         "score": <score-options>
      }
   }
}

Options

near uses the following terms to construct a query:

Field

Type

Description

Necessity

origin

date, number, or geo

Number, date, or geographic point to search near. This is the origin from which the proximity of the results is measured.

For number fields, the value must be of BSON int32, int64, or double data types.
For date fields, the value must be an ISODate formatted date.
For geo fields. the value must be a GeoJSON point.

yes

path

string or array of strings

Indexed field or fields to search.

yes

pivot

number

Value to use to calculate scores of MongoDB Search result documents. Score is calculated using the following formula:

              pivot
score = ------------------
         pivot + distance

where distance is the difference between origin and the indexed field value.

Results have a score equal to 1/2 (or 0.5) when their indexed field value is pivot units away from origin. The value of pivot must be greater than (i.e. >) 0.

If origin is a:

Number, pivot can be specified as an integer or floating point number.
Date, pivot must be specified in milliseconds and can be specified as a 32 or 64 bit integer. For example:
- 1 minute is equal to 60,000 ms
- 1 hour is equal to 3,600,000 ms
- 1 day is equal to 86,400,000 ms
- 1 month (or 30 days) is equal to 2,592,000,000 ms
GeoJSON point, pivot is measured in meters and must be specified as an integer or floating point number.

yes

score

object

Score to assign 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.

To learn more, see Scoring Behavior.

Scoring Behavior

MongoDB Search score is a measure of the proximity of the MongoDB Search results to origin. The score is scaled between 0 and 1 with 1 being an exact match and 0 being a distant match. Score is equal to 0.5 when the distance of the MongoDB Search result from origin is equal to the distance away from origin as calculated using pivot.

Score is calculated using the following formula:

               pivot
score = ------------------
         pivot + distance

where, distance is the difference between origin and the indexed field value.

You can modify the default score using score option in your query. To learn more about the options, Modify the Score.

Examples

The number and date examples use the movies collection in the sample_mflix database. The GeoJSON point example uses the listingsAndReviews collection in the sample_airbnb database.

If you load the sample data on your cluster, you can create the static indexes using the index definitions in the examples below or the dynamic index and run the example queries on your cluster.

Tip

If you've already loaded the sample dataset, refer to the MongoDB Search Quick Start tutorial to create an index definition and run MongoDB Search queries.

Number Example

The following example uses the near operator to query a number field. The following queries use an index named runtimes that dynamically indexes all the fields in the movies collection. The query searches for documents in the movies collection with a runtime field value that is near 279.

Basic Example

The following query returns all documents that match the search criteria. It includes a $limit stage to limit the output to 7 results and a $project stage to:

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

The score is calculated using pivot.

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

[
  { runtime: 279, title: 'The Kingdom', score: 1 },
  { runtime: 279, title: 'The Kingdom', score: 1 },
  { runtime: 279, title: 'The Jinx: The Life and Deaths of Robert Durst', score: 1  },
  { runtime: 281, title: 'Les Misèrables', score: 0.5 },
  { runtime: 277, title: 'Tokyo Trial', score: 0.5 },
  { runtime: 283, title: 'Scenes from a Marriage', score: 0.3333333432674408 },
  { runtime: 274, title: 'The Crimson Petal and the White', score: 0.2857142984867096 }
]

In the MongoDB Search results, the movies The Kingdom and The Jinx: The Life and Deaths of Robert Durst receive a score of 1.0 because their runtime field value of 279 is an exact match. The movies Les Misèrables and Tokyo Trial receive a score of 0.5 because their runtime field value is 2 units away from 279.

Metadata Example

The following query returns the metadata results for the search criteria. That is, it uses the $searchMeta stage to get the number of movies in the following buckets (years) that match the search criteria:

2000, inclusive lower bound for this bucket
2005, exclusive upper bound for the 2000 bucket and inclusive lower bound for this bucket
2010, exclusive upper bound for the 2005 bucket and inclusive lower bound for this bucket
2010, exclusive upper bound for the 2010 bucket

1 db.movies.aggregate([
2   {
3     "$searchMeta": {
4       "facet": {
5         "operator": {
6           "near": {
7             "path": "runtime",
8             "origin": 279,
9             "pivot": 2
10           }
11         },
12         "facets": {
13           "yearFacet": {
14             "type": "number",
15             "path": "year",
16             "boundaries": [2000, 2005, 2010, 2015 ]
17           }
18         }
19       }
20     }
21   }
22 ])

[
  {
    count: { lowerBound: Long('20910') },
    facet: {
      yearFacet: {
        buckets: [
          { _id: 2000, count: Long('3058') },
          { _id: 2005, count: Long('4012') },
          { _id: 2010, count: Long('4669') }
        ]
      }
    }
  }
]

Date Example

The following example uses the near operator to query a date field.

Example

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

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

The following query searches for movies released near September 13, 1. It includes a $limit stage to limit the output to 3 results and a $project stage to:

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

The score of results is calculated using pivot.

Note

pivot is measured here in milliseconds, and 7,776,000,000 ms is equal to approximately three months.

1 db.movies.aggregate([
2    {
3       $search: {
4          "index": "releaseddate",
5          "near": {
6             "path": "released",
7             "origin": ISODate("1915-09-13T00:00:00.000+00:00"),
8             "pivot": 7776000000
9          }
10       }
11    },
12    {
13       $limit: 3
14    },
15    {
16       $project: {
17          "_id": 0,
18          "title": 1,
19          "released": 1,
20          score: { $meta: "searchScore" }
21       }
22    }
23 ])

The above query returns the following search results:

{ "title" : "Regeneration", "released" : ISODate("1915-09-13T00:00:00Z"), "score" : 1 }
{ "title" : "The Cheat", "released" : ISODate("1915-12-13T00:00:00Z"), "score" : 0.49723756313323975 }
{ "title" : "Hell's Hinges", "released" : ISODate("1916-03-05T00:00:00Z"), "score" : 0.34090909361839294 }

In the above MongoDB Search results, the movie Regeneration receives a score of 1 because the released field value of 1915-09-13 is an exact match. The movie The Cheat, which was released on 1915-12-13, receives a score of approximately 0.5 because the released field value distance from origin is approximately 7,776,000,000 milliseconds from 1915-09-13.

GeoJSON Point Examples

The following examples use the near operator to query a GeoJSON point object in the sample_airbnb.listingsAndReviews collection. The following index definition indexes the address.location and property_type fields in the listingsAndReviews collection.

Example

1 {
2   "mappings": {
3     "fields": {
4       "address": {
5         "fields": {
6           "location": {
7             "type": "geo"
8           }
9         },
10         "type": "document"
11       },
12       "property_type": {
13         "type": "string"
14       }
15     }
16   }
17 }

Basic Example

The following examples use the near operator to query the address.location field in the sample_airbnb.listingsAndReviews collection.

Example

The following query searches for properties in Portugal. It includes a $limit stage to limit the output to 3 results and a $project stage to:

Exclude all fields except name and address
Add a field named score

The score of results is calculated using pivot. Note that pivot is measured here in meters and 1000 meters is equal to 1 kilometer.

1 db.listingsAndReviews.aggregate([
2   {
3     "$search": {
4       "near": {
5         "origin": {
6           "type": "Point",
7           "coordinates": [-8.61308, 41.1413]
8         },
9         "pivot": 1000,
10         "path": "address.location"
11       }
12     }
13   },
14   {
15     $limit: 3
16   },
17   {
18     $project: {
19       "_id": 0,
20       "name": 1,
21       "address": 1,
22       score: { $meta: "searchScore" }
23     }
24   }
25 ])

The above query returns the following search results:

1 {
2   "name" : "Ribeira Charming Duplex",
3   "address" : {
4     "street" : "Porto, Porto, Portugal",
5     "suburb" : "",
6     "government_area" : "Cedofeita, Ildefonso, Sé, Miragaia, Nicolau, Vitória",
7     "market" : "Porto",
8     "country" : "Portugal",
9     "country_code" : "PT",
10     "location" : {
11       "type" : "Point",
12       "coordinates" : [ -8.61308, 41.1413 ],
13       "is_location_exact" : false
14     }
15   },
16   "score" : 1
17 }
18 {
19   "name" : "DB RIBEIRA - Grey Apartment",
20   "address" : {
21     "street" : "Porto, Porto, Portugal",
22     "suburb" : "",
23     "government_area" : "Cedofeita, Ildefonso, Sé, Miragaia, Nicolau, Vitória",
24     "market" : "Porto",
25     "country" : "Portugal",
26     "country_code" : "PT",
27     "location" : {
28       "type" : "Point",
29       "coordinates" : [ -8.61294, 41.14126 ],
30       "is_location_exact" : true
31     }
32   },
33   "score" : 0.9876177310943604
34 }
35 {
36   "name" : "Ribeira 24 (4)",
37   "address" : {
38     "street" : "Porto, Porto, Portugal",
39     "suburb" : "",
40     "government_area" : "Cedofeita, Ildefonso, Sé, Miragaia, Nicolau, Vitória",
41     "market" : "Porto",
42     "country" : "Portugal",
43     "country_code" : "PT",
44     "location" : {
45       "type" : "Point",
46       "coordinates" : [ -8.61318, 41.14107 ],
47       "is_location_exact" : false
48     }
49   },
50   "score" : 0.973789632320404
51 }

The results show that properties that are farther away from the specified coordinates have a lower score.

Compound Example

The following example uses the compound operator to query the property_type and address.location fields in the sample_airbnb.listingsAndReviews collection.

Example

The following query searches for apartments in Hong Kong near a specified GeoJSON point. The query uses must to specify the search condition, which must be met, and should to specify preference for location. It includes a $limit stage to limit the output to 3 results and a $project stage to:

Exclude all fields except property_type and address
Add a field named score

The score is calculated using the pivot field. Note that pivot is measured here in meters and 1000 meters is equal to 1 kilometer.

1 db.listingsAndReviews.aggregate([
2   {
3     $search: {
4       "compound": {
5         "must": {
6           "text": {
7             "query": "Apartment",
8             "path": "property_type"
9           }
10         },
11         "should": {
12           "near": {
13             "origin": {
14               "type": "Point",
15               "coordinates": [114.15027, 22.28158]
16             },
17             "pivot": 1000,
18             "path": "address.location"
19           }
20         }
21       }
22     }
23   },
24   {
25     $limit: 3
26   },
27   {
28     $project: {
29       "_id": 0,
30       "property_type": 1,
31       "address": 1,
32       score: { $meta: "searchScore" }
33     }
34   }
35 ])

The above query returns the following search results:

1 {
2   "property_type" : "Apartment",
3   "address" : {
4     "street" : "Hong Kong, Hong Kong Island, Hong Kong",
5     "suburb" : "Central & Western District",
6     "government_area" : "Central & Western",
7     "market" : "Hong Kong",
8     "country" : "Hong Kong",
9     "country_code" : "HK",
10     "location" : {
11       "type" : "Point",
12       "coordinates" : [ 114.15027, 22.28158 ],
13       "is_location_exact" : true
14     }
15   },
16   "score" : 1.177286982536316
17 }
18 {
19   "property_type" : "Apartment",
20   "address" : {
21     "street" : "Hong Kong, Hong Kong Island, Hong Kong",
22     "suburb" : "Central & Western District",
23     "government_area" : "Central & Western",
24     "market" : "Hong Kong",
25     "country" : "Hong Kong",
26     "country_code" : "HK",
27     "location" : {
28       "type" : "Point",
29       "coordinates" : [ 114.15082, 22.28161 ],
30       "is_location_exact" : true
31     }
32   },
33   "score" : 1.1236450672149658
34 }
35 {
36   "property_type" : "Apartment",
37   "address" : {
38     "street" : "Hong Kong,
39     Hong Kong Island, Hong Kong",
40     "suburb" : "Mid-Levels",
41     "government_area" : "Central & Western",
42     "market" : "Hong Kong",
43     "country" : "Hong Kong",
44     "country_code" : "HK",
45     "location" : {
46       "type" : "Point",
47       "coordinates" : [ 114.15007, 22.28215 ],
48       "is_location_exact" : true
49     }
50   },
51   "score" : 1.114811897277832
52 }

Back

morelikethis

phrase

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

1	db.movies.aggregate([
2	{
3	"$searchMeta": {
4	"facet": {
5	"operator": {
6	"near": {
7	"path": "runtime",
8	"origin": 279,
9	"pivot": 2
10	}
11	},
12	"facets": {
13	"yearFacet": {
14	"type": "number",
15	"path": "year",
16	"boundaries": [2000, 2005, 2010, 2015 ]
17	}
18	}
19	}
20	}
21	}
22	])

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

1	db.movies.aggregate([
2	{
3	$search: {
4	"index": "releaseddate",
5	"near": {
6	"path": "released",
7	"origin": ISODate("1915-09-13T00:00:00.000+00:00"),
8	"pivot": 7776000000
9	}
10	}
11	},
12	{
13	$limit: 3
14	},
15	{
16	$project: {
17	"_id": 0,
18	"title": 1,
19	"released": 1,
20	score: { $meta: "searchScore" }
21	}
22	}
23	])

1	{
2	"mappings": {
3	"fields": {
4	"address": {
5	"fields": {
6	"location": {
7	"type": "geo"
8	}
9	},
10	"type": "document"
11	},
12	"property_type": {
13	"type": "string"
14	}
15	}
16	}
17	}

1	db.listingsAndReviews.aggregate([
2	{
3	"$search": {
4	"near": {
5	"origin": {
6	"type": "Point",
7	"coordinates": [-8.61308, 41.1413]
8	},
9	"pivot": 1000,
10	"path": "address.location"
11	}
12	}
13	},
14	{
15	$limit: 3
16	},
17	{
18	$project: {
19	"_id": 0,
20	"name": 1,
21	"address": 1,
22	score: { $meta: "searchScore" }
23	}
24	}
25	])

1	{
2	"name" : "Ribeira Charming Duplex",
3	"address" : {
4	"street" : "Porto, Porto, Portugal",
5	"suburb" : "",
6	"government_area" : "Cedofeita, Ildefonso, Sé, Miragaia, Nicolau, Vitória",
7	"market" : "Porto",
8	"country" : "Portugal",
9	"country_code" : "PT",
10	"location" : {
11	"type" : "Point",
12	"coordinates" : [ -8.61308, 41.1413 ],
13	"is_location_exact" : false
14	}
15	},
16	"score" : 1
17	}
18	{
19	"name" : "DB RIBEIRA - Grey Apartment",
20	"address" : {
21	"street" : "Porto, Porto, Portugal",
22	"suburb" : "",
23	"government_area" : "Cedofeita, Ildefonso, Sé, Miragaia, Nicolau, Vitória",
24	"market" : "Porto",
25	"country" : "Portugal",
26	"country_code" : "PT",
27	"location" : {
28	"type" : "Point",
29	"coordinates" : [ -8.61294, 41.14126 ],
30	"is_location_exact" : true
31	}
32	},
33	"score" : 0.9876177310943604
34	}
35	{
36	"name" : "Ribeira 24 (4)",
37	"address" : {
38	"street" : "Porto, Porto, Portugal",
39	"suburb" : "",
40	"government_area" : "Cedofeita, Ildefonso, Sé, Miragaia, Nicolau, Vitória",
41	"market" : "Porto",
42	"country" : "Portugal",
43	"country_code" : "PT",
44	"location" : {
45	"type" : "Point",
46	"coordinates" : [ -8.61318, 41.14107 ],
47	"is_location_exact" : false
48	}
49	},
50	"score" : 0.973789632320404
51	}

1	db.listingsAndReviews.aggregate([
2	{
3	$search: {
4	"compound": {
5	"must": {
6	"text": {
7	"query": "Apartment",
8	"path": "property_type"
9	}
10	},
11	"should": {
12	"near": {
13	"origin": {
14	"type": "Point",
15	"coordinates": [114.15027, 22.28158]
16	},
17	"pivot": 1000,
18	"path": "address.location"
19	}
20	}
21	}
22	}
23	},
24	{
25	$limit: 3
26	},
27	{
28	$project: {
29	"_id": 0,
30	"property_type": 1,
31	"address": 1,
32	score: { $meta: "searchScore" }
33	}
34	}
35	])

1	{
2	"property_type" : "Apartment",
3	"address" : {
4	"street" : "Hong Kong, Hong Kong Island, Hong Kong",
5	"suburb" : "Central & Western District",
6	"government_area" : "Central & Western",
7	"market" : "Hong Kong",
8	"country" : "Hong Kong",
9	"country_code" : "HK",
10	"location" : {
11	"type" : "Point",
12	"coordinates" : [ 114.15027, 22.28158 ],
13	"is_location_exact" : true
14	}
15	},
16	"score" : 1.177286982536316
17	}
18	{
19	"property_type" : "Apartment",
20	"address" : {
21	"street" : "Hong Kong, Hong Kong Island, Hong Kong",
22	"suburb" : "Central & Western District",
23	"government_area" : "Central & Western",
24	"market" : "Hong Kong",
25	"country" : "Hong Kong",
26	"country_code" : "HK",
27	"location" : {
28	"type" : "Point",
29	"coordinates" : [ 114.15082, 22.28161 ],
30	"is_location_exact" : true
31	}
32	},
33	"score" : 1.1236450672149658
34	}
35	{
36	"property_type" : "Apartment",
37	"address" : {
38	"street" : "Hong Kong,
39	Hong Kong Island, Hong Kong",
40	"suburb" : "Mid-Levels",
41	"government_area" : "Central & Western",
42	"market" : "Hong Kong",
43	"country" : "Hong Kong",
44	"country_code" : "HK",
45	"location" : {
46	"type" : "Point",
47	"coordinates" : [ 114.15007, 22.28215 ],
48	"is_location_exact" : true
49	}
50	},
51	"score" : 1.114811897277832
52	}

near Operator Limitations

Definition

Syntax

Options

Scoring Behavior

Examples

Tip

Number Example

Basic Example

Metadata Example

Date Example

Example

Note

GeoJSON Point Examples

Example

Basic Example

Example

Compound Example

Example

`near` Operator Limitations