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
- 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
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:
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).
- Most desirable time complexity:
- 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).
- Most desirable time complexity:
- 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).
- Most desirable time complexity:
- 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.
- 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,
- 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).
- Most desirable time complexity:
- 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)"