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.

Main features

  • R-tree indexes for query and storage.
  • Line and polygon queries, including queries for the intersection of sets.
  • GIS.SEARCH command, which functions like native Redis GEORADIUS command.

Best practices

Monitor user trajectories by using TairGIS

Prerequisites

A Tair DRAM-based instance is created.
Note 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 instance or read/write splitting instance, we recommend that you update the proxy nodes in the instance to the latest minor version to ensure that all commands can be run as expected.

Precautions

The TairGIS data that you want to manage is stored on a Tair instance.

Supported commands

Table 1. TairGIS commands
Command Syntax Description
GIS.ADD GIS.ADD area polygonName polygonWkt [polygonName polygonWkt ...]
Adds one or more specific polygons to a specific 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.
GIS.GET GIS.GET area polygonName

Retrieves the WTK of a specific polygon within a specific area.

GIS.GETALL GIS.GETALL area [WITHOUTWKT]

Retrieves the names and WKTs of all polygons within a specific area. If you specify the WITHOUTWKT parameter, only the names of the polygons are returned.

GIS.CONTAINS GIS.CONTAINS area polygonWkt [WITHOUTWKT]

Checks whether a specified point, linestring, or polygon is located in polygons within a specific area. If yes, this command returns the number and WKTs of polygons that contain the point, linestring, or polygon in the area.

GIS.WITHIN GIS.WITHIN area polygonWkt [WITHOUTWKT]

Checks whether a specific area is located within a specified point, linestring, or polygon. If yes, this command returns the number and WKTs of polygons that are located within the point, linestring, or polygon.

GIS.INTERSECTS GIS.INTERSECTS area polygonWkt

Checks whether a specific point, linestring, or polygon intersects with polygons within a specific area. If yes, this command returns the number and WKTs of polygons within the area that intersect with the point, linestring, or polygon.

GIS.SEARCH 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]

Queries the points within a specific area that are located within a specific radius of a specific longitude and latitude position.

GIS.DEL GIS.DEL area polygonName

Deletes a specific polygon from a specific area.

DEL DEL key [key ...] Deletes one or more TairGIS keys. This is a native Redis command.
Note The following section describes command syntax used in this topic:
  • Uppercase keyword: the command keyword.
  • Italic: Words in italic indicate variable information that you supply.
  • [options]: optional parameters. Parameters that are not included in brackets are required.
  • AB: specifies that these parameters are mutually exclusive. Select one of two or more parameters.
  • ...: specifies to repeat the preceding content.

GIS.ADD

Item Description
Syntax GIS.ADD area polygonName polygonWkt [polygonName polygonWkt ...]
Time complexity

O(log n)
Command description
Adds one or more specific polygons to a specific 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)', which indicates that the point is located at longitude 120.086631 and latitude 30.138141.
    • LINESTRING: the WKT that describes a linestring, which consists of two points. Example: 'LINESTRING (30 10, 40 40)'.
    • POLYGON: the WKT that describes a polygon, which consists of multiple points. Example: 'POLYGON ((31 20, 29 20, 29 21, 31 31))'.
    Note
    • Valid values for a longitude are -180 to 180 and valid values for a latitude are -90 to 90.
    • MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRY, and COLLECTION collection types are not supported.
Output
  • If the operation is successful, the number of polygons that were added and updated is returned.
  • Otherwise, an error message is returned.
Example

Sample command:

GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'

Sample output:

(integer) 1

GIS.GET

Item Description
Syntax GIS.GET area polygonName
Time complexity O(1)
Command description

Retrieves the WTK of a specific polygon within a specific 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 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

Item Description
Syntax GIS.GETALL area [WITHOUTWKT]
Time complexity O(n)
Command description

Retrieves the names and WKTs of all polygons within a specific 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 WKTs of polygons. If this parameter is specified, the WKTs of the polygons are not returned.
Output
  • If the operation is successful, the names and WKTs 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.

Sample command:

GIS.GETALL hangzhou

Sample output:

1) "campus"
2) "POLYGON((30 10,40 40,20 40,10 20,30 10))"

GIS.CONTAINS

Item Description
Syntax GIS.CONTAINS area polygonWkt [WITHOUTWKT]
Time complexity
  • Optimal time complexity: Log formula
  • Least desirable time complexity: log(n)
Command description

Checks whether a specified point, linestring, or polygon is located in polygons within a specific area. If yes, this command returns the number and WKTs 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 description includes longitudes and latitudes. 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 WKTs of polygons. If this parameter is specified, the WKTs of the polygons are not returned.
Output
  • If the operation is successful, the number and WKTs 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.

Sample command:

GIS.CONTAINS hangzhou 'POINT (30 11)'

Sample output:

1) "1"
2) 1) "campus"
   2) "POLYGON((30 10,40 40,20 40,10 20,30 10))"

GIS.WITHIN

Item Description
Syntax GIS.WITHIN area polygonWkt [WITHOUTWKT]
Time complexity
  • Optimal time complexity: Log formula
  • Least desirable time complexity: log(n)
Command description

Checks whether a specific area is located within a specified point, linestring, or polygon. If yes, this command returns the number and WKTs of polygons 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 description includes longitudes and latitudes. 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, and COLLECTION are not supported.
  • WITHOUTWKT: specifies whether to return the WKTs of polygons. If this parameter is specified, the WKTs of the polygons are not returned.
Output
  • If the operation is successful, the number and WKTs 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.

Sample command:

 GIS.WITHIN hangzhou  'POLYGON ((30 5, 50 50, 20 50, 5 20, 30 5))'

Sample output:

1) "1"
2) 1) "campus"
   2) "POLYGON((30 10,40 40,20 40,10 20,30 10))"

GIS.INTERSECTS

Item Description
Syntax GIS.INTERSECTS area polygonWkt
Time complexity
  • Optimal time complexity: Log formula
  • Least desirable time complexity: log(n)
Command description

Checks whether a specific point, linestring, or polygon intersects with polygons within a specific area. If yes, this command returns the number and WKTs 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 description includes longitudes and latitudes. 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 WKTs of polygons. If this parameter is specified, the WKTs of the polygons are not returned.
Output
  • If the operation is successful, the number and WKTs 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.

Sample command:

 GIS.INTERSECTS hangzhou 'LINESTRING (30 10, 40 40)'

Sample output:

1) "1"
2) 1) "campus"
   2) "POLYGON((30 10,40 40,20 40,10 20,30 10))"

GIS.SEARCH

Item Description
Syntax 
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: Log formula
  • Least desirable time complexity: log(n)
Command description

Queries the points within a specific area that are located within a specific radius of a specific longitude and latitude position.

Parameter
  • area: a geometric concept.
  • RADIUS: specifies the longitude, latitude, radius, and radius unit. Valid values for the unit: meters (M), kilometers (KM), feet (FT), and miles (MI). Example: RADIUS 15 37 200 KM.
  • MEMBER: specifies the point in the area that is used as the base point and the radius for the point. Valid values for the radius unit: meters (M), kilometers (KM), feet (FT), and miles (MI). Example: MEMBER Agrigento 100 KM. In this example, Agrigento indicates the name of the polygon, 100 indicates the radius, and KM indicates the radius unit. This order must be used for the parameter syntax.
  • GEOM: the polygon written in WKT that indicates the search range. Example: GEOM 'POLYGON((10 30,20 30,20 40,10 40))'.
  • COUNT: the maximum number of entries returned. Example: COUNT 3.
  • ASC|DESC: specifies the order in which the returned entries are ranked based on distance. ASC indicates that the returned entries are ranked from low to high based on their distance to the center. DESC: indicates that the returned entries are ranked from high to low 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 WKTs of points. If this parameter is specified, the WKTs of the points are not returned.
Note You can specify only one of the RADIUS, MEMBER, and GEOM parameters.
Output
  • If the operation is successful, the number and WKTs 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

Sample output:

1) (integer) 2
2) 1) "Catania"
   2) "POINT(15.087269 37.502669)"
   3) "56.4413"
   4) "Palermo"
   5) "POINT(13.361389 38.115556)"
   6) "190.4424"

GIS.DEL

Item Description
Syntax GIS.DEL area polygonName
Time complexity

O(log n)
Command description

Deletes a specific polygon from a specific area.

Parameter
  • area: a geometric concept.
  • PolygonName: the name of the polygon that you want to manage.
Output
  • If the operation is successful, OK 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.DEL hangzhou campus

Sample output:

OK