This topic describes the commands supported by TairGISs.

Overview

A TairGIS is a data structure that uses R-tree indexes and supports Geographic Information System (GIS) API operations. The GEO commands of Redis allows you to use GeoHash and Redis SortedSet to query points. Compared with GEO commands, TairGIS allows you to query points, lines, and planes, and provides more features.

Key features:

  • Supports R-tree indexing.
  • Allows you to query points, lines, and planes (including querying intersection relationships).

Prerequisites

The commands described in this topic take effect only if the following conditions are met:

  • A performance-enhanced instance of ApsaraDB for Redis Enterprise Edition is used.
  • The TairGIS data to be managed is stored on the performance-enhanced instance.

Commands

Table 1. TairGIS commands
Command Syntax Description
GIS.ADD GIS.ADD <area> <PolygonName> <POLYGON> [<PolygonName2> <POLYGON> ...] This command can be used to add one or more polygons to a specified area. The PolygonName field specifies a polygon name. 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> This command can be used to retrieve the WKT information about a polygon in a specified area. The PolygonName field specifies the polygon name.
GIS.DEL GIS.DEL <area> <PolygonName> This command can be used to delete a polygon in a specified area. The PolygonName field specifies the polygon name.
GIS.SEARCH GIS.SEARCH <area> <POINT | LINESTRING | POLYGON> This command can be used to query a polygon that contains a specified point, line, or plane in a specified area. The polygon name and relevant WKT information are returned.
GIS.CONTAINS GIS.CONTAINS <area> <POINT | LINESTRING | POLYGON> This command can be used to check whether a polygon in a specified area contains a specified point, line, or plane.
GIS.INTERSECTS GIS.INTERSECTS <area> <POINT | LINESTRING | POLYGON> This command can be used to check the intersection relationship between a polygon in a specified area and a specified point, line, or plane.

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.
POINT The well-known text (WKT) information that describes a point.
LINESTRING The WKT information that describes a line.
POLYGON The WKT information that describes a polygon.

GIS.ADD

  • Syntax

    GIS.ADD <area> <polygonName> <polygonWkt> [<polygonName> <polygonWkt> ...]

  • Time complexity

    O(log n)

  • Description

    This command is used to add one or more polygons to a specified area. The polygons are described in WKT. For example, 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'. You can specify one or more polygons.

  • Returned values
    • 1: the operation is successful.
    • Expected result: If one or more polygon names exist in the area, the specified WKT information overwrites the current WKT information and a value of 1 is returned.
    • Otherwise, an exception is returned.
  • Example 
    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.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'
(integer) 0
127.0.0.1:6379> GIS.GET hangzhou campus
"POLYGON((30 10,40 40,20 40,10 20,30 10))"

GIS.GET

  • Syntax

    GIS.GET <area> <polygonName>

  • Time complexity

    O(1)

  • Description

    This command is used to retrieve the WKT information about a polygon in a specified area. The PolygonName parameter specifies the polygon name.

  • Returned values
    • The WKT information is returned if the operation is successful.
    • nil: the specified area or polygon name does not exist.
    • Otherwise, an exception is returned.
  • Example 
    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.DEL

  • Syntax

    GIS.DEL <area> <polygonName>

  • Time complexity

    O(log n)

  • Description

    This command is used to delete a polygon in a specified area. The PolygonName parameter specifies the polygon name.

  • Returned values
    • OK: the operation is successful.
    • nil: the specified area or polygon name does not exist.
    • Otherwise, an exception is returned.
  • Example 
    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.SEARCH

  • Syntax

    GIS.SEARCH <area> <POINT/LINESTRING/POLYGONNAME>

  • Time complexity
    • Most desired time complexity: O(logM n).
    • Least desired time complexity: log(n).
  • Description

    This command is used to query a polygon that contains a specified point, line, or plane in a specified area. The name and WKT information of the polygon are returned.

  • Returned values
    • The WKT information is returned if the operation is successful.
    • nil: no data is found.
    • Otherwise, an exception is returned.
  • Example 
    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.SEARCH 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.SEARCH 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.SEARCH 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.CONTAINS

  • Syntax

    GIS.CONTAINS <area> <POINT | LINESTRING | POLYGON> [WITHOUTWKT]

  • Time complexity
    • Most desired time complexity: O(logM n).
    • Least desired 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 about a polygon that contains the specified points, lines, or planes are returned if the operation is successful. If you specify the WITHOUTWKT parameter, the WKT information of the polygon is not returned.
    • nil: no data is found.
    • Otherwise, an exception is returned.
  • Example 
    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> <POINT/LINESTRING/POLYGONNAME>

  • Time complexity
    • Most desired time complexity: O(logM n).
    • Least desired 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 WKT information of the specified polygon is returned if the operation is successful.
    • nil: no data is found.
    • Otherwise, an exception is returned.
  • Example 
    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.GETALL

  • Syntax

    GIS.GETALL <area> [WITHOUTWKT]

  • Time complexity

    O(n)

  • Description

    This command is used to query all polygons in a specified area. If you specify the WITHOUTWKT parameter, the WKT information of the polygons is not returned.

  • Returned values
    • The name and WKT information of the polygon are returned if the operation is successful. If you specify the WITHOUTWKT parameter, the WKT information of the polygons is not returned.
    • nil: no data is found.
    • Otherwise, an exception is returned.
  • Example 
    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"
127.0.0.1:6379>