Geospatial Queries

You can execute some special queries when using geospatial indexes like checking for documents within a rectangle or circle.

Mapping

First, setup some documents like the following:

• PHP

  <?php
  
  /**
   * @Document
   * @Index(keys={"coordinates"="2d"})
   */
  class City
  {
      /** @Id */
      public $id;
  
      /** @Field(type="string") */
      public $name;
  
      /** @EmbedOne(targetDocument="Coordinates") */
      public $coordinates;
  
      /** @Distance */
      public $distance;
  }
  
  /** @EmbeddedDocument */
  class Coordinates
  {
      /** @Field(type="float") */
      public $x;
  
      /** @Field(type="float") */
      public $y;
  }
  

• XML

  <indexes>
      <index>
          <key name="coordinates" order="2d" />
      </index>
  </indexes>
  

• YAML

  indexes:
    coordinates:
      keys:
        coordinates: 2d
  

Near Query

Now you can execute queries against these documents like the following. Check for the 10 nearest cities to a given longitude and latitude with the near($longitude, $latitude) method:

<?php

$cities = $this->dm->createQuery('City')
    ->field('coordinates')->near(-120, 40)
    ->execute();

GeoNear Command

You can also execute the geoNear command using the query builder's geoNear() method. Additional builder methods can be used to set options for this command (e.g. distanceMultipler(), maxDistance(), spherical()). Unlike near(), which uses a query operator, geoNear() does not require the location field to be specified in the builder, as MongoDB will use the single geospatial index for the collection. Documents will be returned in order of nearest to farthest.

<?php

$cities = $this->dm->createQuery('City')
    ->geoNear(-120, 40)
    ->spherical(true)
    // Convert radians to kilometers (use 3963.192 for miles)
    ->distanceMultiplier(6378.137)
    ->execute();

If the model has a property mapped with @Distance, that field will be set with the calculated distance between the document and the query coordinates.

<?php

foreach ($cities as $city) {
    printf("%s is %f kilometers away.\n", $city->name, $city->distance);
}

Within Box

You can also query for cities within a given rectangle using the withinBox($x1, $y1, $x2, $y2) method:

<?php

$cities = $this->dm->createQuery('City')
    ->field('coordinates')->withinBox(41, 41, 72, 72)
    ->execute();

Within Center

In addition to boxes you can check for cities within a circle using the withinCenter($x, $y, $radius) method:

<?php

$cities = $this->dm->createQuery('City')
    ->field('coordinates')->withinCenter(50, 50, 20)
    ->execute();