Solr 3 was the first release to have spatial support, and its implementation is still appropriate for common requirements. It is principally comprised of the LatLonType and PointType field types, the geofilt and bbox query parsers, and the geodist, dist, and sqedist functions. There are some other lesser used functions too.

LatLonType is geospatially oriented: latitude and longitude with geodetic math—notably the Haversine distance formula. PointType holds x and y coordinates on a classic 2D Cartesian plane with faster and simpler Euclidean geometry calculations, such as the Pythagorean Theorem for distance. PointType uniquely supports a variable number of dimensions; it's an obscure feature.

The underlying implementation resides in Solr itself, not Lucene-spatial. The overall approach is straightforward, notwithstanding some optimization tricks. The latitude and longitude (or x and y) are internally indexed into separate numeric fields. This approach doesn't support multivalued data, such as modeling businesses with multiple locations. If the query is just a rectangular filter, then it's pretty fast since it just needs to do a couple simple numeric range queries. If, on the other hand, the query shape is a point-distance (circle) shape, then the distance is calculated to potentially all points, depending on the circumstances; consequently, it isn't very scalable. Another thing to be aware of is that the FieldCache is used whenever the distance is required, which is for a point-distance query shape, and/or to sort by distance. The FieldCache holds all coordinate values in memory.

Some of the key characteristics have been summarized here:

<field name="store" type="location" indexed="true"
  stored="true"/>
<fieldType name="location" class="solr.LatLonType"
  subFieldSuffix="_coordinate"/>
<dynamicField name="*_coordinate" type="tdouble"
  indexed="true" stored="false"/>

Solr 4 introduced SpatialRecursivePrefixTreeFieldType, referred to as RPT because it's a mouthful. This one field type can be configured for either geodetic or Euclidean math. The Solr code is not much more than an adapter to the technology that mostly lives in the Lucene spatial module, plus a dependency on Spatial4j for the shape implementations. Additionally, the third-party JTS Topology Suite is required for some shapes, such as polygons. The implementation scheme is based on a variable-depth hierarchical grid in which the world is decomposed into grid cells, which are in turn recursively decomposed into smaller grid cells, until the desired precision is reached.

Indexed shapes of basically any kind are represented completely on the grid, and there are scalable algorithms to find them in relation to a query shape at search time. It's more powerful and often faster at filtering than the comparatively simple LatLonType. For distance sorting/boosting, it includes a custom point cache, but this feature should be avoided as it doesn't scale well.

This picture shows how a polygon of France is decomposed into geohash grid cells of varying sizes. This was easily generated using a utility in the web demo of Spatial Solr Sandbox on GitHub that generates a KML file that Google Earth can render.

Its key characteristics can be summarized as follows:

<fieldType name="location_rpt"
  class="solr.SpatialRecursivePrefixTreeFieldType"
  geo="true" distErrPct="0.025" maxDistErr="0.000009"
  units="degrees" />

The simplest and most common spatial data to index is a point.

When providing data to this field, it is formatted as a string with the latitude then the longitude, separated by a comma. Here's an example in Solr's Update-XML format:

<field name="store">43.17614,-90.57341</field>

Whether you use SolrJ, the DIH, or any other client/format, it appears as a string going in and coming out of Solr. If you have multiple points to index, simply supply them as additional values, as you would for any other multivalued field. LatLonType can't handle this but RPT will.

If the field type is PointType, then the dimension order is x,y. If the field type is RPT and geo is false, then you should supply points as x y (a space in between). If you use a comma in this circumstance, then the dimensions will be flipped. This is probably a bug, so don't rely on that behavior.

Perhaps the most common geospatial need is to filter search results to those documents within a distance radius from a center point. If you are building an application in which the user is presented with a map, perhaps using Google Maps, then the center point is the center of the map the user is looking at and the distance radius is the distance from the center to the nearest map edge. Such a query is generally specified using a Solr filter query (fq parameter) leaving q open for the possibility of a combined keyword search if desired. Both the geofilt and bbox query parsers perform geospatial filtering. The geofilt query parser implements a point-distance based filter, a circle shape, whereas bbox uses the minimum bounding latitude-longitude box surrounding that circle. You can also specify an arbitrary rectangle using Solr's standard range syntax but using points.

Here is a quick example based on Solr's example schema and dataset, showing the URL parameters needed to do the search:

q=*:*&fq={!bbox}&sfield=store&pt=45.15,-93.85&d=5

The parameters that geofilt and bbox require can be specified as either local-params (between the parser name and closing bracket) or standard request parameters, as shown above. To be clear, here's the same query using local-params:

q=*:*&fq={!bbox sfield=store pt=45.15,-93.85 d=5}

The advantage of not using local-params is that a combined distance sort can reuse the same parameters, as you'll see in a bit. Here are geofilt and bbox's parameters:

To query by an arbitrary latitude-longitude rectangle, use a range query between the lower-left corner (smallest latitude and longitude) to the upper-right like so:

q=*:*&fq=store:[43.2,-94.1 TO 46.3,-92.0]

Solr can sort search results by the distance between a document's point and another point supplied at query time. That point is typically the center point of a combined spatial filter. The typical way to spatially sort is to use Solr's ability to sort by a function query—a spatial function, geodist() in particular. The geodist() function calculates the geospatial distance (the "great circle distance") as calculated using the Haversine formula between a pair of points. The points are each taken from the first available of an argument, the pt parameter, or the sfield parameter. Any of these might be absent, but at least two must be specified. When a point is specified as an argument (within the parenthesis), it can either be a geospatial field name or a pair of arguments that are in latitude then longitude order. The latitude or longitude can be constants, or they may reference numeric fields' names. Here's an example of this:

&sort=geodist(store,42.4,-71.1) asc

Before the RPT field supported geodist() in Solr 4.5, a different, more awkward syntax was needed. You used to have to add a score=distance local-param to the spatial query and then put the spatial query into q to sort by score and filter at the same time. Or, even more awkwardly, you could sort by the query() function query. You can find examples of that syntax, if you must, online.

&fl=*,score,dist:geodist()&sfield=store&pt=45.15,-93.8

&defType=edismax&q=…&qf=…&sort=score desc
&fq={!geofilt}&sfield=store&pt=45.15,-93.85&d=100
&boost=recip(geodist(),1,10,10)

This book sets aside a fair amount of space to cover spatial search in Solr for the needs of most applications, but there's more that couldn't be included:

For more coverage of these spatial topics, see the Solr Reference Guide at https://cwiki.apache.org/confluence/display/solr/Spatial+Search.