TairGIS commands - Product Introduction| Alibaba Cloud Documentation Center

Prerequisites

The ApsaraDB for Redis instance is of Enhanced Edition (Performance-enhanced instances).
The instance uses the latest minor version. For more information about how to upgrade the minor version, see Upgrade the minor version.

Features

Supports R-tree indexing.
Allows you to query points, lines, and planes (including querying intersection relationships).
Compatible with Redis GEO commands.

Commands

Table 1. TairGIS commands
Statement	Syntax	Description
GIS.ADD	`GIS.ADD <area> <polygonName> <polygonWkt> [<polygonName> <polygonWkt> ...]`	Adds one or more specified polygons to a specified area. The polygons are described in well-known text (WKT). Note WKT is a text markup language that you can use to represent vector geometry objects on a map and the spatial reference systems of spatial objects. WKT also allows you to perform transformations between spatial reference systems.
GIS.GET	`GIS.GET <area> <polygonName>`	Retrieves the WKT information about a specified polygon in an area.
GIS.GETALL	`GIS.GETALL <area> [WITHOUTWKT]`	Queries all polygons in a specified area. The names and WKT information of the polygons are returned.
GIS.DEL	`GIS.DEL <area> <polygonName>`	Deletes a specified polygon in an area.
DEL	`DEL <key> [key ...]`	Deletes one or more TairGISs. This is a native Redis command.
GIS.CONTAINS	`GIS.CONTAINS <area> <polygonWkt> [WITHOUTWKT]`	Checks whether a polygon in a specified area contains a specified point, line, or plane.
GIS.INTERSECTS	`GIS.INTERSECTS <area> <polygonWkt>`	Queries the intersection relationship between a polygon in a specified area and a specified point, line, or plane.
GIS.SEARCH	`GIS.SEARCH [RADIUS longitude latitude distance m\|km\|ft\|mi] [MEMBER field distance m\|km\|ft\|mi] [GEOM geom] [COUNT count] [ASC\|DESC] [WITHDIST] [WITHOUTWKT]`	Retrieves points within a sphere with a specified radius, latitude, and longitude.
GIS.WITHIN	`GIS.WITHIN <area> <polygonWkt> [WITHOUTWKT]`	Retrieves points, lines, or planes within a specified polygon in an area.

Parameters


Parameter	Description
area	The geometric area in which you want to manage the data.
PolygonName	The name of the polygon that you want to manage.
polygonWkt	The description of a polygon, which is described by using WKT. The following types are supported: POINT: the WKT information that describes a point, such as `'POINT (30 11)'`. LINESTRING: the WKT information that describes a line, such as `'LINESTRING (30 10, 40 40)'`. POLYGON: the WKT information that describes a polygon, such as `'POLYGON ((31 20, 29 20, 29 21, 31 31))'`. Note MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRY, and COLLECTION are not supported.
WITHOUTWKT	Specifies whether to return the WKT information of polygons. If you use the GIS.GETALL, GIS.CONTAINS, GIS.SEARCH or GIS.WITHIN command and specify the WITHOUTWKT parameter, the WKT information of the polygon is not returned.

GIS.ADD

Syntax
GIS.ADD <area> <polygonName> <polygonWkt> [<polygonName> <polygonWkt>...]
Time complexity, which is used to indicate the trend of statement execution time as data size increases.
O(log n)
Description
This command is used to add one or more polygons to a specified area. The polygons are described in WKT.
Returned values
- The number of successful inserts and updates are returned if the operation is successful.
- Otherwise, an exception is returned.

Examples

127.0.0.1:6379> GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'
(integer) 1

GIS.GET

Syntax
```
GIS.GET <area> <polygonName>
```
Time complexity
O(1)
Description
This command is used to retrieve the WKT information about a specified polygon in an area.
Returned values
- The WKT information about the polygon is returned if the operation is successful.
- A value of nil is returned if the specified area or polygon name does not exist.
- Otherwise, an exception is returned.

Examples

127.0.0.1:6379> GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'
(integer) 1
127.0.0.1:6379> GIS.GET hangzhou campus
"POLYGON((30 10,40 40,20 40,10 20,30 10))"
127.0.0.1:6379> GIS.GET hangzhou not-exists
(nil)
127.0.0.1:6379> GIS.GET not-exists campus
(nil)

GIS.GETALL

Syntax
```
GIS.GETALL <area> [WITHOUTWKT]
```
Time complexity
O(n)
Description
This command is used to query all polygons in a specified area. The names and WKT information of the polygons are returned. If you specify the WITHOUTWKT parameter, only the name of the polygon is returned.
Returned values
- The name and WKT information of the polygon are returned if the operation is successful. If you specify the WITHOUTWKT parameter, only the name of the polygon is returned.
- A value of nil is returned if no data is found.
- Otherwise, an exception is returned.

Examples

127.0.0.1:6379> GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'
(integer) 1
127.0.0.1:6379> GIS.GETALL hangzhou
1) "campus"
2) "POLYGON((30 10,40 40,20 40,10 20,30 10))"
127.0.0.1:6379> GIS.GETALL hangzhou WITHOUTWKT
1) "campus"

GIS.DEL

Syntax
GIS.DEL <area> <polygonName>
Time complexity
O(log n)
Description
This command is used to delete a specified polygon in an area.
Returned values
- OK is returned if the operation is successful.
- A value of nil is returned if the specified area or polygon name does not exist.
- Otherwise, an exception is returned.

Examples

127.0.0.1:6379> GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'
(integer) 1
127.0.0.1:6379> GIS.GET hangzhou campus
"POLYGON((30 10,40 40,20 40,10 20,30 10))"
127.0.0.1:6379> GIS.DEL hangzhou not-exists
(nil)
127.0.0.1:6379> GIS.DEL not-exists campus
(nil)
127.0.0.1:6379> GIS.DEL hangzhou campus
OK
127.0.0.1:6379> GIS.GET hangzhou campus
(nil)

GIS.CONTAINS

Syntax
GIS.CONTAINS <area> <polygonWkt>
Time complexity
- Most desirable time complexity: .
- Least desirable time complexity: log(n).
Description
This command is used to check whether a polygon in a specified area contains a specified point, line, or plane.
Returned values
- The name and WKT information of the specified polygon that contains the specified point, line or plane are returned if the operation is successful. If you specify the WITHOUTWKT parameter, only the name of the polygon is returned.
- A value of nil is returned if no data is found.
- Otherwise, an exception is returned.

Examples

127.0.0.1:6379> GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'
(integer) 1
127.0.0.1:6379> GIS.CONTAINS hangzhou 'POINT (30 11)'
1) "0"
2) 1) "campus"
   2) "POLYGON((30 10,40 40,20 40,10 20,30 10))"
127.0.0.1:6379> GIS.CONTAINS hangzhou 'LINESTRING (30 10, 40 40)'
1) "0"
2) 1) "campus"
   2) "POLYGON((30 10,40 40,20 40,10 20,30 10))"
127.0.0.1:6379> GIS.CONTAINS hangzhou 'POLYGON ((31 20, 29 20, 29 21, 31 31))'
1) "0"
2) 1) "campus"
   2) "POLYGON((30 10,40 40,20 40,10 20,30 10))"

GIS.INTERSECTS

Syntax
GIS.INTERSECTS <area> <polygonWkt>
Time complexity
- Most desirable time complexity: .
- Least desirable time complexity: log(n).
Description
This command is used to query the intersection relationship between a polygon in a specified area and a specified point, line, or plane.
Returned values
- The name and WKT information of the specified polygon that intersects with the specified point, line or plane are returned if the operation is successful.
- A value of nil is returned if no data is found.
- Otherwise, an exception is returned.

Examples

127.0.0.1:6379> GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'
(integer) 1
127.0.0.1:6379> GIS.INTERSECTS hangzhou 'POINT (30 11)'
1) "0"
2) 1) "campus"
   2) "POLYGON((30 10,40 40,20 40,10 20,30 10))"
127.0.0.1:6379> GIS.INTERSECTS hangzhou 'LINESTRING (30 10, 40 40)'
1) "0"
2) 1) "campus"
   2) "POLYGON((30 10,40 40,20 40,10 20,30 10))"
127.0.0.1:6379> GIS.INTERSECTS hangzhou 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'
1) "0"
2) 1) "campus"
   2) "POLYGON((30 10,40 40,20 40,10 20,30 10))"
127.0.0.1:6379>

GIS.SEARCH

Syntax

GIS.SEARCH [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
- Most desirable time complexity: .
- Least desirable time complexity: log(n).
Description
This command is used to retrieve points within a sphere with a given radius, latitude, and longitude. The following parameters are supported:
- RADIUS: searches points by the longitude, latitude, and radius. Specify the parameter values in the following order: longitude, latitude, radius and radius unit, for example, RADIUS 15 37 200 km.
- MEMBER: searches points by the latitude and longitude from an existing polygon, and a specified radius. Specify the parameter values in the following order: polygon name, radius, and radius unit, for example, MEMBER Agrigento 100 km.
- GEOM: specifies the search range in the WKT format for a random polygon, such as GIS.SEARCH Sicily "POINT (13.361389 38.115556)".
- COUNT: limits the number of returned entries, such as COUNT 3.
- ASC|DESC: sorts returned entries by distance. For example, ASC indicates that the entries are sorted from nearest to farthest from the center.
- WITHDIST: specifies whether to return the distance.
- WITHOUTWKT: specifies whether the WKT information of polygons is returned.
Returned values
- The name and WKT information of the specified polygon are returned if the operation is successful.
- A value of nil is returned if no data is found.
- Otherwise, an exception is returned.

Examples

127.0.0.1:6379> GIS.ADD Sicily "Palermo" "POINT (13.361389 38.115556)" "Catania" "POINT(15.087269 37.502669)"
(integer) 2
127.0.0.1:6379> GIS.SEARCH Sicily RADIUS 15 37 200 km WITHDIST
1) "2"
2) 1) "Palermo"
   2) "POINT(13.361389 38.115556)"
   3) "190.4424"
   4) "Catania"
   5) "POINT(15.087269 37.502669)"
   6) "56.4413"
127.0.0.1:6379> GIS.SEARCH Sicily RADIUS 15 37 200 km WITHDIST WITHOUTWKT
1) "2"
2) 1) "Palermo"
   2) "190.4424"
   3) "Catania"
   4) "56.4413"
127.0.0.1:6379> GIS.SEARCH Sicily RADIUS 15 37 200 km WITHDIST WITHOUTWKT ASC
1) "2"
2) 1) "Catania"
   2) "56.4413"
   3) "Palermo"
   4) "190.4424"
127.0.0.1:6379> GIS.SEARCH Sicily RADIUS 15 37 200 km WITHDIST WITHOUTWKT ASC COUNT 1
1) "2"
2) 1) "Catania"
   2) "56.4413"
127.0.0.1:6379> GIS.ADD Sicily "Agrigento" "POINT (13.583333 37.316667)"
(integer) 1
127.0.0.1:6379> GIS.SEARCH Sicily MEMBER Agrigento 100 km
1) "2"
2) 1) "Palermo"
   2) "POINT(13.361389 38.115556)"
   3) "Agrigento"
   4) "POINT(13.583333 37.316667)"

GIS.WITHIN

Syntax

GIS.WITHIN <area> <polygonWkt> [WITHOUTWKT]

Time complexity
- Most desirable time complexity: .
- Least desirable time complexity: log(n).
Description
This command is used to retrieve points, lines, or planes within a specified polygon in an area. If you specify the WITHOUTWKT parameter, only the name of the polygon is returned.

Returned values
- The name and WKT information of the polygon are returned if the operation is successful.
- nil: no data is found.
- Otherwise, an exception is returned.

Examples

127.0.0.1:6379> GIS.ADD hangzhou campus 'POINT (30 10)'
(integer) 1
127.0.0.1:6379> GIS.ADD hangzhou campus1 'LINESTRING (30 10, 40 40)'
(integer) 1
127.0.0.1:6379> GIS.WITHIN hangzhou 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'
1) "2"
2) 1) "campus"
   2) "POINT(30 10)"
   3) "campus1"
   4) "LINESTRING(30 10,40 40)"