TairGIS is a data structure that uses R-tree indexes and supports APIs related to a geographic information system (GIS). Compared with native Redis GEO commands that allow you to use Geohash and Redis Sorted Set to query points, TairGIS provides more features by allowing you to query points, linestrings, and polygons.
Features
Uses R-tree indexes for query and storage.
Supports linestring and polygon queries, including queries for the intersection of sets.
Provides the GIS.SEARCH command, which serves the same purpose as the GEORADIUS command of native Redis.
The module is open-sourced. For more information, visit GitHub.
The latest minor version provides more features and higher stability. We recommend that you update your instance to the latest minor version. For more information, see Update the minor version of an instance. If your instance is a cluster or read/write splitting instance, we recommend that you update the proxy nodes in the instance to the latest minor version. This ensures that all commands can be run as expected.
Usage notes
The TairGIS data that you want to manage is stored on a Tair instance.
GIS.ADD area polygonName polygonWkt [polygonName polygonWkt ...]
Adds one or more polygons to an area. The polygons are described in well-known text (WKT).
Note
WKT is a text markup language for representing vector geometry objects on a map, spatial reference systems of spatial objects, and transformations between spatial reference systems.
Retrieves the names and WKT representation of all polygons within an area. If you specify the WITHOUTWKT parameter, only the names of the polygons are returned.
Checks whether a point, linestring, or polygon is located in polygons within a specific area. If yes, this command returns the number and WKT representation of polygons that contain the point, linestring, or polygon in the area.
Checks whether an area is located within a point, linestring, or polygon. If yes, this command returns the number and WKT representation of polygons in the area that are located within the point, linestring, or polygon.
Checks whether a point, linestring, or polygon intersects with polygons within a specific area. If yes, this command returns the number and WKT representation of polygons within the area that intersect with the point, linestring, or polygon.
Deletes one or more TairGIS keys. This is a native Redis command.
Note
The following list describes the conventions for the command syntax used in this topic:
Uppercase keyword: indicates the command keyword.
Italic text: indicates variables.
[options]: indicates that the enclosed parameters are optional. Parameters that are not enclosed by brackets must be specified.
A|B: indicates that the parameters separated by the vertical bars (|) are mutually exclusive. Only one of the parameters can be specified.
...: indicates that the parameter preceding this symbol can be repeatedly specified.
GIS.ADD
Parameter
Description
Syntax
GIS.ADD area polygonName polygonWkt [polygonName polygonWkt ...]
Time complexity
O(log n)
Command description
Adds one or more polygons to an area. The polygons are described in well-known text (WKT).
Note
WKT is a text markup language for representing vector geometry objects on a map, spatial reference systems of spatial objects, and transformations between spatial reference systems.
Parameter
area: a geometric concept.
PolygonName: the name of the polygon that you want to manage.
polygonWkt: the description of the polygon that is written in WKT. The description includes longitudes and latitudes. The following polygon types can be described in WKT:
POINT: the WKT that describes a point. Example: 'POINT (120.086631 30.138141)'. The value indicates that the point is located at longitude 120.086631 and latitude 30.138141.
LINESTRING: the WKT that describes a linestring. The linestring consists of two points. Example: 'LINESTRING (30 10, 40 40)'.
POLYGON: the WKT that describes a polygon. The polygon consists of multiple points. Example: 'POLYGON ((31 20, 29 20, 29 21, 31 31))'.
Note
Valid values of a longitude are -180 to 180, and valid values of a latitude are -90 to 90.
The MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRY, or COLLECTION collection type is not supported.
Output
If the operation is successful, the number of polygons that have been added and updated is returned.
Retrieves the WKT representation of a polygon within an area.
Parameter
area: a geometric concept.
PolygonName: the name of the polygon that you want to manage.
Output
If the operation is successful, the WKT representation of the polygon is returned.
If the area or polygon does not exist, nil is returned.
Otherwise, an error message is returned.
Example
The GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))' command is run in advance.
Sample command:
GIS.GET hangzhou campus
Sample output:
'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'
GIS.GETALL
Parameter
Description
Syntax
GIS.GETALL area [WITHOUTWKT]
Time complexity
O(n)
Command description
Retrieves the names and WKT representation of all polygons within an area. If you specify the WITHOUTWKT parameter, only the names of the polygons are returned.
Parameter
area: a geometric concept.
WITHOUTWKT: specifies whether to return the WKT representation of polygons. If this parameter is specified, the WKT representation of the polygons is not returned.
Output
If the operation is successful, the names and WKT representation of the polygons are returned. If the WITHOUTWKT parameter is specified, only the names of the polygons are returned.
If the area does not exist, nil is returned.
Otherwise, an error message is returned.
Example
The GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))' command is run in advance.
Checks whether a point, linestring, or polygon is located in polygons within a specific area. If yes, this command returns the number and WKT representation of polygons that contain the point, linestring, or polygon in the area.
Parameter
area: a geometric concept.
polygonWkt: the description of the polygon that is written in WKT. The following polygon types can be described in WKT:
POINT: the WKT that describes a point.
LINESTRING: the WKT that describes a linestring.
POLYGON: the WKT that describes a polygon.
WITHOUTWKT: specifies whether to return the WKT representation of polygons. If this parameter is specified, the WKT representation of the polygons is not returned.
Output
If the operation is successful, the number and WKT representation of the polygons are returned.
If the area does not exist, the "empty list or set" message is returned.
Otherwise, an error message is returned.
Example
The GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))' command is run in advance.
Checks whether an area is located within a point, linestring, or polygon. If yes, this command returns the number and WKT representation of polygons in the area that are located within the point, linestring, or polygon.
Parameter
area: a geometric concept.
polygonWkt: the description of the polygon that is written in WKT. The following polygon types can be described in WKT:
POINT: the WKT that describes a point.
LINESTRING: the WKT that describes a linestring.
POLYGON: the WKT that describes a polygon.
Note
MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRY, or COLLECTION is not supported.
WITHOUTWKT: specifies whether to return the WKT representation of polygons. If this parameter is specified, the WKT representation of the polygons is not returned.
Output
If the operation is successful, the number and WKT representation of the polygons are returned.
If the area does not exist, the "empty list or set" message is returned.
Otherwise, an error message is returned.
Example
The GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))' command is run in advance.
Checks whether a point, linestring, or polygon intersects with polygons within a specific area. If yes, this command returns the number and WKT representation of polygons within the area that intersect with the point, linestring, or polygon.
Parameter
area: a geometric concept.
polygonWkt: the description of the polygon that is written in WKT. The following polygon types can be described in WKT:
POINT: the WKT that describes a point.
LINESTRING: the WKT that describes a linestring.
POLYGON: the WKT that describes a polygon.
WITHOUTWKT: specifies whether to return the WKT representation of polygons. If this parameter is specified, the WKT representation of the polygons is not returned.
Output
If the operation is successful, the number and WKT representation of the polygons are returned.
If the area does not exist, the "empty list or set" message is returned.
Otherwise, an error message is returned.
Example
The GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))' command is run in advance.
GIS.SEARCH area [RADIUS longitude latitude distance M|KM|FT|MI]
[MEMBER field distance M|KM|FT|MI]
[GEOM geom]
[COUNT count]
[ASC|DESC]
[WITHDIST]
[WITHOUTWKT]
Time complexity
Optimal time complexity:
Least desirable time complexity: O(log n)
Command description
Queries the points in an area that are located within a radius of a specific longitude and latitude position.
Parameter
area: a geometric concept.
RADIUS: the longitude, latitude, radius, and radius unit. Valid values for the unit: M (meter), KM (kilometer), FT (feet), and MI (mile). Example: RADIUS 15 37 200 KM.
MEMBER: the point in the area that is used as the base point and the radius for the point. The values must be provided in the following order: the name of the polygon (field), the search radius (distance), and the radius unit. Valid values for the radius unit: M (meter), KM (kilometer), FT (feet), and MI (mile). Example: MEMBER Agrigento 100 KM.
GEOM: the polygon written in WKT that specifies the search range. Example: GEOM 'POLYGON((10 30,20 30,20 40,10 40))'.
COUNT: the maximum number of entries that can be returned. Example: COUNT 3.
ASC|DESC: the order in which the returned entries are ranked. ASC indicates that the returned entries are ranked from short to long based on their distance to the center. DESC indicates that the returned entries are ranked from long to short based on their distance to the center.
WITHDIST: specifies whether to return the distance between a specific point and the point specified by the MEMBER parameter.
WITHOUTWKT: specifies whether to return the WKT representation of points. If this parameter is specified, the WKT representation of the points is not returned.
Note
You can specify only one of the RADIUS, MEMBER, and GEOM parameters.
Output
If the operation is successful, the number and WKT representation of the points are returned.
If the area does not exist, the "empty list or set" message is returned.
Otherwise, an error message is returned.
Example
The GIS.ADD Sicily "Palermo" "POINT (13.361389 38.115556)" "Catania" "POINT(15.087269 37.502669)" command is run in advance.
Sample command:
GIS.SEARCH Sicily RADIUS 15 37 200 km WITHDIST ASC
