Introduction to the
Redis has added geospatial and index radius queries in version 3.2
Mainly used in applications that require geographical location
Adds the specified geospatial location (latitude, longitude, name) to the specified key. These data will be stored in sorted set, so that it is convenient to use GEORADIUS or GEORADIUSBYMEMBER command to perform radius query and other operations on data
The working principle of
How does it work?
The sorted set is populated using a technique called Geohash. The longitude and latitude bits are interlaced to form a unique 52-bit integer. We know that a sorted set’s double score can represent a 52-bit integer without losing precision.
This format allows the radius query to examine 1 + 8 fields needed to cover the entire radius and discard elements outside the radius. By calculating the range of the region, by calculating the range covered, the score of the sorted set of the less important parts, and by calculating the sorted set of the query with the range of the score for each region.
What kind of Earth model is used?
This only assumes that the Earth is a sphere, since the distance formula used is the Haversine formula. This formula applies only to the earth, not to a perfect sphere. These deviations are not a problem when used on social networking sites and most other applications where you need to query the radius. However, the worst-case deviation can be 0.5%, so some geographically critical applications need to be considered with caution.
The command that
GEOADD
GEOADD key longitude latitude member [longitude latitude member …]
Time complexity: O(log(N)), where N is the number of members
Add the specified geospatial location (latitude, longitude, name) to the specified key. These data will be stored in sorted set, so that it is convenient to use GEORADIUS or GEORADIUSBYMEMBER command to perform radius query and other operations on data
Return value: integer, the number of elements added to the sorted set, but not the elements whose score has been updated
The sample
GEOADD Sicily 13.361389 38.115556 “Palermo” 15.087269 37.502669
Pay attention to
The command takes arguments x,y in standard format, so longitude must precede latitude. The limits of these coordinates can be indexed, and the area can be close to the pole but not indexed. Specific restrictions, specified by EPSG:900913 / EPSG:3785 / OSGEO:41001 are as follows:
Effective longitude ranges from -180 degrees to 180 degrees. Valid latitudes range from -85.05112878 degrees to 85.05112878 degrees. This command returns an error when the coordinates are outside the range specified above.
GEODIST
GEODIST key member1 member2 [unit]
Time complexity: O(log(N))
Functional specifications
- Returns the distance between two given positions, or null if one of the positions does not exist.
- The parameter unit specifying the unit must be one of the following:
- M means in meters (default)
- Km is expressed in kilometers
- Mi means miles
- Ft is in feet
Return value: The calculated distance is returned as a double-precision floating-point number. If the given positional element does not exist, the command returns a null value
Example: GEODIST Sicily Palermo Catania KM
GEOHASH
GEOHASH key member [member …]
Time complexity: O(log(N)), where N is the number of members
Functional specifications
- Returns a Geohash representation of one or more positional elements
- It is common to use a different technique using elements that represent positions, using Geohash position 52-point integer encoding. The encoding is also different from the standard due to the different initial minimum and maximum coordinates used in the encoding and decoding process. This command returns a standard Geohash, described on both Wikipedia and geohash.org
The return value
An array, each item of which is a GeoHash. The position of the geohash returned by the command corresponds to the position of the user-given location element
Example: GEOHASH Sicily Palermo Catania
GEOPOS
GEOPOS key member [member …]
Time complexity: O(log(N))
Returns the latitude and longitude of all elements in a given position from key.
The return value
The GEOPOS command returns an array in which each entry consists of two elements: the first is the longitude of the element at a given location, and the second is the latitude of the element at a given location.
When the given location element does not exist, the corresponding array entry is null
GEORADIUS
GEORADIUS key longitude latitude radius m|km|ft|mi [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count]
Time complexity: O(N+log(M)), where N is the number of elements in the bounding box of the circular region, which is bounded by the center and radius, and M is the number of items in the index
Functional specifications
Returns all of the location elements contained by the key that are within a given maximum distance from the center, centered at a given latitude and longitude
A range can use one of the following units:
- M is in meters.
- Km is expressed in kilometers.
- Mi means miles.
- Ft is in feet.
The command returns additional information when given the following options:
WITHDIST
Return the distance between the location element and the center as well as the location element. The units of distance are the same as the units of range given by the user.
WITHCOORD
Return the longitude and dimension of the positional element as well.
WITHHASH
Returns the original Geohashed ordered set score of the positional element as a 52-bit signed integer. This option is mainly used for low-level applications or debugging, and is not useful in practice. The command returns unsorted positional elements by default.
The user can specify the order of the elements of the returned position with the following two parameters:
ASC: Returns the position element from near to far based on the position of the center.
DESC: Returns the location element from far to near based on the location of the center.
By default, the GEORADIUS command returns all matching positional elements. Although the user can use the COUNT option to retrieve the first N matched elements, because the command may need to process all matched elements internally, even using the COUNT option to retrieve only a few elements in a very large area of a search can be very slow. On the other hand, using the COUNT option to reduce the number of elements that need to be returned is still very useful for reducing bandwidth.
The return value
In the absence of any WITH option, the command simply returns a linear list like [” New York “, “Milan”, “Paris”].
With WITHCOORD, WITHDIST, WITHHASH, etc., the command returns a two-layer nested array, with each subarray of the inner layer representing an element. When returning a nested array, the first element of the subarray is always the name of the positional element.
Additional information is returned as subsequent elements of the subarray in the following order:
- The distance between the center and position elements returned in floating-point format, in the same units as when the user specified a range
- Geohash integer. A coordinate consisting of two elements, longitude and latitude
- A coordinate consisting of two elements, longitude and latitude
GEORADIUSBYMEMBER
GEORADIUSBYMEMBER key member radius m|km|ft|mi [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count]
Time complexity: O(N+log(M)), where N is the number of elements in the bounding box of the circular region, defined by the center and radius, and M is the number of items in the index.
Function Description: This command, like GEORADIUS command, can find the elements in the specified range, but the center point of GEORADIUSBYMEMBER is determined by the given location element, not like GEORADIUS. The location of the specified member is used as the center of the query using the longitude and latitude of the input to determine the center point
The resources
Redis geospatial instructions