`near` (MongoDB Search Operator)

near (MongoDB Search Operator)

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

`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](https://www.mongodb.com/docs/search/query/operators-collectors/range.md#std-label-range-ref only to query indexed numeric or date values inside arrays.

Definition

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](https://www.mongodb.com/docs/manual/reference/geojson.md#std-label-geojson-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](https://www.mongodb.com/docs/search/indexes/field-types/geo-type.md#std-label-bson-data-types-geo fields. the value must be a [GeoJSON point.](https://www.mongodb.com/docs/manual/reference/geojson.md#std-label-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.](https://www.mongodb.com/docs/search/query/score/overview.md#std-label-scoring-ref To learn more, see [Scoring Behavior.](https://www.mongodb.com/docs/search/query/operators-collectors/near.md#std-label-near-query-score	no

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.

The near operator uses the following distance decay function to calculate document score:

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

where each term is defined as follows:

Factor	Description
`pivot`	Value specified as a reference point to make the score equal to `0.5` if the distance between `fieldValue` and `origin` is equal to it. This defines how quickly the score decays as the distance between `fieldValue` and `origin` grows. For a given distance between `fieldValue` and `origin`, if `pivot` decreases, the score also decreases.
`distance`	Absolute distance between `fieldValue` and `origin`. MongoDB Search computes this value using the following formula: `abs(fieldValue - origin)` where: `fieldValue` is the value of the field that you are querying in the document.; `origin` is the number, date, or geographic point to search near.

You can modify the default score using score option in your query. To learn more about the options, [Modify the Score.](https://www.mongodb.com/docs/search/query/score/modify-score.md#std-label-scoring-options

Examples

The [number](https://www.mongodb.com/docs/search/query/operators-collectors/near.md#std-label-near-number-eg and [date](https://www.mongodb.com/docs/search/query/operators-collectors/near.md#std-label-near-date-eg examples use the movies collection in the sample_mflix database. The [GeoJSON point](https://www.mongodb.com/docs/search/query/operators-collectors/near.md#std-label-near-geo-point-eg example uses the listingsAndReviews collection in the sample_airbnb database.

If you [load the sample data](https://www.mongodb.com/docs/atlas/import/load-sample-data.md#std-label-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](https://www.mongodb.com/docs/manual/sample-data.md#std-label-available-sample-datasets, refer to the [MongoDB Search Quick Start](https://www.mongodb.com/docs/search/tutorial.md#std-label-fts-tutorial-ref tutorial to create an [index definition](https://www.mongodb.com/docs/search/indexes/index-definitions.md#std-label-ref-index-definitions 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](https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit.md#mongodb-pipeline-pipe.-limit stage to limit the output to 7 results and a [$project](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project stage to:

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

The score is calculated using pivot.

db.movies.aggregate([
  {
    $search: {
      "index": "runtimes",
      "near": {
        "path": "year",
        "origin": 2000,
        "pivot": 2
      }
    }
  },
  {
    $limit: 7
  },
  {
    $project: {
      "_id": 0,
      "title": 1,
      "runtime": 1,
      score: { $meta: "searchScore" }
    }
  }
])

Output:

[
  { 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](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-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

db.movies.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "near": {
            "path": "runtime",
            "origin": 279,
            "pivot": 2
          }
        },
        "facets": {
          "yearFacet": {
            "type": "number",
            "path": "year",
            "boundaries": [2000, 2005, 2010, 2015 ]
          }
        }
      }
    }
  }
])

Output:

[
  {
    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:

{
   "mappings": {
      "dynamic": false,
      "fields": {
         "released": {
            "type": "date"
         }
      }
   }
}

The following query searches for movies released near September 13, 1. It includes a [$limit](https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit.md#mongodb-pipeline-pipe.-limit stage to limit the output to 3 results and a [$project](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project stage to:

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

The score of results is calculated using pivot.

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

db.movies.aggregate([
   {
      $search: {
         "index": "releaseddate",
         "near": {
            "path": "released",
            "origin": ISODate("1915-09-13T00:00:00.000+00:00"),
            "pivot": 7776000000
         }
      }
   },
   {
      $limit: 3
   },
   {
      $project: {
         "_id": 0,
         "title": 1,
         "released": 1,
         score: { $meta: "searchScore" }
      }
   }
])

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:

{
  "mappings": {
    "fields": {
      "address": {
        "fields": {
          "location": {
            "type": "geo"
          }
        },
        "type": "document"
      },
      "property_type": {
        "type": "string"
      }
    }
  }
}

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](https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit.md#mongodb-pipeline-pipe.-limit stage to limit the output to 3 results and a [$project](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-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.

db.listingsAndReviews.aggregate([
  {
    "$search": {
      "near": {
        "origin": {
          "type": "Point",
          "coordinates": [-8.61308, 41.1413]
        },
        "pivot": 1000,
        "path": "address.location"
      }
    }
  },
  {
    $limit: 3
  },
  {
    $project: {
      "_id": 0,
      "name": 1,
      "address": 1,
      score: { $meta: "searchScore" }
    }
  }
])

The above query returns the following search results:

{
  "name" : "Ribeira Charming Duplex",
  "address" : {
    "street" : "Porto, Porto, Portugal",
    "suburb" : "",
    "government_area" : "Cedofeita, Ildefonso, Sé, Miragaia, Nicolau, Vitória",
    "market" : "Porto",
    "country" : "Portugal",
    "country_code" : "PT",
    "location" : {
      "type" : "Point",
      "coordinates" : [ -8.61308, 41.1413 ],
      "is_location_exact" : false
    }
  },
  "score" : 1
}
{
  "name" : "DB RIBEIRA - Grey Apartment",
  "address" : {
    "street" : "Porto, Porto, Portugal",
    "suburb" : "",
    "government_area" : "Cedofeita, Ildefonso, Sé, Miragaia, Nicolau, Vitória",
    "market" : "Porto",
    "country" : "Portugal",
    "country_code" : "PT",
    "location" : {
      "type" : "Point",
      "coordinates" : [ -8.61294, 41.14126 ],
      "is_location_exact" : true
    }
  },
  "score" : 0.9876177310943604
}
{
  "name" : "Ribeira 24 (4)",
  "address" : {
    "street" : "Porto, Porto, Portugal",
    "suburb" : "",
    "government_area" : "Cedofeita, Ildefonso, Sé, Miragaia, Nicolau, Vitória",
    "market" : "Porto",
    "country" : "Portugal",
    "country_code" : "PT",
    "location" : {
      "type" : "Point",
      "coordinates" : [ -8.61318, 41.14107 ],
      "is_location_exact" : false
    }
  },
  "score" : 0.973789632320404
}

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](https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit.md#mongodb-pipeline-pipe.-limit stage to limit the output to 3 results and a [$project](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-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.

db.listingsAndReviews.aggregate([
  {
    $search: {
      "compound": {
        "must": {
          "text": {
            "query": "Apartment",
            "path": "property_type"
          }
        },
        "should": {
          "near": {
            "origin": {
              "type": "Point",
              "coordinates": [114.15027, 22.28158]
            },
            "pivot": 1000,
            "path": "address.location"
          }
        }
      }
    }
  },
  {
    $limit: 3
  },
  {
    $project: {
      "_id": 0,
      "property_type": 1,
      "address": 1,
      score: { $meta: "searchScore" }
    }
  }
])

The above query returns the following search results:

{
  "property_type" : "Apartment",
  "address" : {
    "street" : "Hong Kong, Hong Kong Island, Hong Kong",
    "suburb" : "Central & Western District",
    "government_area" : "Central & Western",
    "market" : "Hong Kong",
    "country" : "Hong Kong",
    "country_code" : "HK",
    "location" : {
      "type" : "Point",
      "coordinates" : [ 114.15027, 22.28158 ],
      "is_location_exact" : true
    }
  },
  "score" : 1.177286982536316
}
{
  "property_type" : "Apartment",
  "address" : {
    "street" : "Hong Kong, Hong Kong Island, Hong Kong",
    "suburb" : "Central & Western District",
    "government_area" : "Central & Western",
    "market" : "Hong Kong",
    "country" : "Hong Kong",
    "country_code" : "HK",
    "location" : {
      "type" : "Point",
      "coordinates" : [ 114.15082, 22.28161 ],
      "is_location_exact" : true
    }
  },
  "score" : 1.1236450672149658
}
{
  "property_type" : "Apartment",
  "address" : {
    "street" : "Hong Kong,
    Hong Kong Island, Hong Kong",
    "suburb" : "Mid-Levels",
    "government_area" : "Central & Western",
    "market" : "Hong Kong",
    "country" : "Hong Kong",
    "country_code" : "HK",
    "location" : {
      "type" : "Point",
      "coordinates" : [ 114.15007, 22.28215 ],
      "is_location_exact" : true
    }
  },
  "score" : 1.114811897277832
}

Create a Deployment

near (MongoDB Search Operator)