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

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. When calculating geospatial results, Atlas Search geoShape and geoWithin operators and MongoDB $geoIntersects operator use different geometries. This difference can be seen in how Atlas Search and MongoDB draw polygonal edges. Atlas Search draws polygons based on Cartesian distance, which is the shortest line between two points in the coordinate reference system. MongoDB draws polygons using the geodesic mode based on 2dsphere indexes that is built on top of a third-party library for geodesic types, or the flat mode, from 2d indexes. To learn more, see GeoJSON Objects. Atlas Search and MongoDB could return different results for geospatial queries involving polygons.	yes
`path`	string or array of strings	Indexed geo type field or fields to search.	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. You can't use `within` with `LineString` or `Point`.	yes
`score`	object	Score to assign to matching search results. By default, the score in the results is `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. `function`: replace the result score with the given expression. For information on using `score` in your query, see Score the Documents in the Results.	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 example queries on your cluster. The Atlas Search Quick Start contains instructions for loading the sample dataset, creating an index definition, and running Atlas Search queries.

The following is a sample index definition for indexing the address.location field in the listingsAndReviews collection:

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

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.
$project stage to exclude all fields except name and address.

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

{
  "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.
$project stage to exclude all fields except name and address.

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

{
  "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.
$project stage to exclude all fields except name and address.

Basic Search

The following query returns the documents that match the specified search criteria.

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

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

Metadata Search

The following query returns the number of types of properties (such as apartment, house, and so on) for the specified search criteria.

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

[
  {
    count: { lowerBound: Long('599') },
    facet: {
      propertyTypeFacet: {
        buckets: [
          { _id: 'Apartment', count: Long('486') },
          { _id: 'House', count: Long('43') },
          { _id: 'Townhouse', count: Long('24') },
          { _id: 'Condominium', count: Long('19') },
          { _id: 'Loft', count: Long('19') },
          { _id: 'Guest suite', count: Long('2') },
          { _id: 'Guesthouse', count: Long('2') },
          { _id: 'Aparthotel', count: Long('1') },
          { _id: 'Hostel', count: Long('1') },
          { _id: 'Serviced apartment', count: Long('1') }
        ]
      }
    }
  }
]

The query results show the different types of properties in the specified coordinates.

Back

facet

geoWithin

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

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

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

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