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

Prerequisites

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: 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: 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: 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: 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)"