All Products
Search
Document Center

Tair:GIS

Last Updated:Jun 27, 2024

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.

Best practices

Prerequisites

A Tair DRAM-based instance is created.

Note

The latest minor version provides more features and higher stability. We recommend that you update the 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.

Supported commands

Table 1. TairGIS commands

Command

Syntax

Description

GIS.ADD

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.

GIS.GET

GIS.GET area polygonName

Retrieves the WKT representation of a polygon within an area.

GIS.GETALL

GIS.GETALL area [WITHOUTWKT]

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.

GIS.CONTAINS

GIS.CONTAINS area polygonWkt [WITHOUTWKT]

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.

GIS.WITHIN

GIS.WITHIN area polygonWkt [WITHOUTWKT]

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.

GIS.INTERSECTS

GIS.INTERSECTS area polygonWkt

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.

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 in an area that are located within a radius of a specific longitude and latitude position.

GIS.DEL

GIS.DEL area polygonName

Deletes a specific polygon from an 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.
  • A|B: specifies that these parameters are mutually exclusive. Select one of two or more parameters.
  • ...: specifies to repeat the preceding content.

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.

  • 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

Parameter

Description

Syntax

GIS.GET area polygonName

Time complexity

O(1)

Command description

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.

Sample command:

GIS.GETALL hangzhou

Sample output:

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

GIS.CONTAINS

Parameter

Description

Syntax

GIS.CONTAINS area polygonWkt [WITHOUTWKT]

Time complexity

  • Optimal time complexity: log公式

  • Least desirable time complexity: O(log n)

Command description

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.

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

Parameter

Description

Syntax

GIS.WITHIN area polygonWkt [WITHOUTWKT]

Time complexity

  • Optimal time complexity: log公式

  • Least desirable time complexity: O(log n)

Command description

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.

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

Parameter

Description

Syntax

GIS.INTERSECTS area polygonWkt

Time complexity

  • Optimal time complexity: log公式

  • Least desirable time complexity: O(log n)

Command description

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.

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

Parameter

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公式

  • 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

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

Parameter

Description

Syntax

GIS.DEL area polygonName

Time complexity

O(log n)

Command description

Deletes a specific polygon from an 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