Navigation

geoShape

Definition

geoShape

The geoShape operator supports querying shapes with a relation to a given geometry if indexShapes is set to true in the index definition.

When specifying the coordinates to search, longitude must be specified first and then the latitude. Longitude values can be between -180 and 180, both inclusive. Latitude values can be between -90 and 90, both inclusive. Coordinate values can be integers or doubles.

Note

Atlas Search does not support the following:

  • Non-default coordinate reference system (CRS)
  • Planar XY coordinate system (2 dimensional)
  • Coordinate pairs Point notation (that is, pointFieldName: [12, 34])

Syntax

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "$search": {
       "index": <index name>, // optional, defaults to "default"
       "geoShape": {
          "path": "<field-to-search>",
          "relation": "contains | disjoint | intersects | within",
          "geometry": <GeoJSON-object>,
          "score": <score-options>
       }
    }
}

Options

geoShape uses the following terms to construct a query:

Field Type Description Necessity
geometry GeoJSON object GeoJSON object that specifies the Polygon, MultiPolygon, or LineString shape or point to search. The polygon must be specified as a closed loop where the last position is the same as the first position. yes
path string or array of strings Indexed geo type field or fields to search. See Path Construction for more information. yes
relation enum

Relation of the query shape geometry to the indexed field geometry. Value can be one of the following:

  • contains - Indicates that the indexed geometry contains the query geometry.
  • disjoint - Indicates that both the query and indexed geometries have nothing in common.
  • intersects - Indicates that both the query and indexed geometries intersect.
  • within - Indicates that the indexed geometry is within the query geometry. within cannot be used with LineString or Point.
yes
score object

Score assigned to matching search results. The score in the results is always 1. You can modify the score using the following options:

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

no

Examples

The following examples use the listingsAndReviews collection in the sample_airbnb database. If you have the sample dataset on your cluster, you can create a custom Atlas Search index for geo type and run the queries on your cluster. The following is a sample index definition for indexing the address.location field in the listingsAndReviews collection:

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

The Tutorial: Create and Query an Atlas Search Index contains instructions for loading the sample dataset, creating an index definition, and running Atlas Search queries.

Note

For the following sample queries, make sure that indexShapes in the index definition is set to true.

Disjoint Example

The following example uses the geoShape operator to search for properties that have nothing in common with the specified longitude and latitude coordinates in Hawaii. The query includes a $limit stage to limit the output to 3 results and a $project stage to exclude all fields except name and address.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
db.listingsAndReviews.aggregate([
  {
    "$search": {
      "geoShape": {
        "relation": "disjoint",
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[-161.323242,22.512557],
                         [-152.446289,22.065278],
                         [-156.09375,17.811456],
                         [-161.323242,22.512557]]]
        },
        "path": "address.location"
      }
    }
  },
  {
    $limit: 3
  },
  {
    $project: {
      "_id": 0,
      "name": 1,
      "address": 1,
      score: { $meta: "searchScore" }
    }
  }
])

The query returns the following search results:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "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
    }
  }
}
{
  "name" : "Horto flat with small garden",
  "address" : {
    "street" : "Rio de Janeiro, Rio de Janeiro, Brazil",
    "suburb" : "Jardim Botânico",
    "government_area" : "Jardim Botânico",
    "market" : "Rio De Janeiro",
    "country" : "Brazil",
    "country_code" : "BR",
    "location" : {
      "type" : "Point",
      "coordinates" : [ -43.23074991429229, -22.966253551739655 ],
      "is_location_exact" : true
    }
  }
}
{
  "name" : "Private Room in Bushwick",
  "address" : {
    "street" : "Brooklyn, NY, United States",
    "suburb" : "Brooklyn",
    "government_area" : "Bushwick",
    "market" : "New York",
    "country" : "United States",
    "country_code" : "US",
    "location" : {
      "type" : "Point",
      "coordinates" : [ -73.93615, 40.69791 ],
      "is_location_exact" : true
    }
  }
}

Intersects Example

The following example uses the geoShape operator to search for properties that intersect with the specified longitude and latitude coordinates in Spain. The query includes a $limit stage to limit the output to 3 results and a $project stage to exclude all fields except name and address.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
db.listingsAndReviews.aggregate([
  {
    "$search": {
      "geoShape": {
        "relation": "intersects",
        "geometry": {
          "type": "MultiPolygon",
          "coordinates": [
                       [[[2.16942,41.40082],
                       [2.17963,41.40087],
                       [2.18146,41.39716],
                       [2.15533,41.40686],
                       [2.14596,41.38475],
                       [2.17519,41.41035],
                       [2.16942,41.40082]]],
                       [[[2.16365,41.39416],
                       [2.16963,41.39726],
                       [2.15395,41.38005],
                       [2.17935,41.43038],
                       [2.16365,41.39416]]]
          ]
        },
        "path": "address.location"
      }
    }
  },
  {
    $limit: 3
  },
  {
    $project: {
      "_id": 0,
      "name": 1,
      "address": 1,
      score: { $meta: "searchScore" }
    }
  }
])

The query returns the following search results:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "name" : "Cozy bedroom Sagrada Familia",
  "address" : {
    "street" : "Barcelona, Catalunya, Spain",
    "suburb" : "Eixample",
    "government_area" : "el Fort Pienc",
    "market" : "Barcelona",
    "country" : "Spain",
    "country_code" : "ES",
    "location" : {
      "type" : "Point",
      "coordinates" : [ 2.17963, 41.40087 ],
      "is_location_exact" : true
    }
  }
}
{
  "name" : "",
  "address" : {
    "street" : "Barcelona, Catalunya, Spain",
    "suburb" : "Vila de Gràcia",
    "government_area" : "la Vila de Gràcia",
    "market" : "Barcelona",
    "country" : "Spain",
    "country_code" : "ES",
    "location" : {
      "type" : "Point",
      "coordinates" : [ 2.15759, 41.40349 ],
      "is_location_exact" : true
    }
  }
}
{
  "name" : "SPACIOUS RAMBLA CATALUÑA",
  "address" : {
    "street" : "Barcelona, Catalunya, Spain",
    "suburb" : "L'Antiga Esquerra de l'Eixample",
    "government_area" : "l'Antiga Esquerra de l'Eixample",
    "market" : "Barcelona",
    "country" : "Spain",
    "country_code" : "ES",
    "location" : {
      "type" : "Point",
      "coordinates" : [ 2.15255, 41.39193 ],
      "is_location_exact" : true
    }
  }
}

Within Example

The following example uses the geoShape operator to search for properties in New York that are within the specified longitude and latitude coordinates. The queries searches the address.location field in the listingsAndReviews collection in the sample_airbnb database. The query includes a $limit stage to limit the output to 3 results and a $project stage to exclude all fields except name and address.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
db.listingsAndReviews.aggregate([
  {
    "$search": {
      "geoShape": {
        "relation": "within",
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[-74.3994140625,40.5305017757],
                         [-74.7290039063,40.5805846641],
                         [-74.7729492188,40.9467136651],
                         [-74.0698242188,41.1290213475],
                         [-73.65234375,40.9964840144],
                         [-72.6416015625,40.9467136651],
                         [-72.3559570313,40.7971774152],
                         [-74.3994140625,40.5305017757]]]
        },
        "path": "address.location"
      }
    }
  },
  {
    $limit: 3
  },
  {
    $project: {
      "_id": 0,
      "name": 1,
      "address": 1,
      score: { $meta: "searchScore" }
    }
  }
])

The query returns the following search results:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
  "name" : "Private Room in Bushwick",
  "address" : {
    "street" : "Brooklyn, NY, United States",
    "suburb" : "Brooklyn",
    "government_area" : "Bushwick",
    "market" : "New York",
    "country" : "United States",
    "country_code" : "US",
    "location" : {
      "type" : "Point",
      "coordinates" : [ -73.93615, 40.69791 ],
      "is_location_exact" : true
    }
  },
  {
    "name" : "New York City - Upper West Side Apt",
    "address" : {
      "street" : "New York, NY, United States",
      "suburb" : "Manhattan",
      "government_area" : "Upper West Side",
      "market" : "New York",
      "country" : "United States",
      "country_code" : "US",
      "location" : {
        "type" : "Point",
        "coordinates" : [ -73.96523, 40.79962 ],
        "is_location_exact" : false
      }
    },
    "score" : 1
  }
  {
    "name" : "Deluxe Loft Suite",
    "address" : {
      "street" : "Brooklyn, NY, United States",
      "suburb" : "Greenpoint",
      "government_area" : "Greenpoint",
      "market" : "New York",
      "country" : "United States",
      "country_code" : "US",
      "location" : {
        "type" : "Point",
        "coordinates" : [ -73.94472, 40.72778 ],
        "is_location_exact" : true
      }
    },
    "score" : 1
  }
←   exists geoWithin  →