Tair (Redis® OSS-Compatible):GIS

Key concepts

Spatial relationship queries: contains, within, and intersects

These three commands query different directional relationships between a geometry you supply and the shapes stored in an area. The distinction matters because GIS.CONTAINS and GIS.WITHIN look similar but operate in opposite directions:

• GIS.CONTAINS — finds stored shapes that *contain* your input. Use this when you have a point (such as a user's GPS location) and want to know which stored regions enclose it. For example: "Which delivery zones does this address fall inside?"

• GIS.WITHIN — finds stored shapes that are *inside* your input. Use this when you have a large bounding shape and want to know which stored shapes fit entirely within it. For example: "Which parking lots are entirely inside this district?"

• GIS.INTERSECTS — finds stored shapes that *share any coordinates* with your input. Use this when partial overlap is enough. For example: "Which roads cross this construction zone?"

WKT geometry types

TairGIS uses well-known text (WKT) to describe geometries. All three types follow the format TYPE (coordinates):

Valid longitude range: -180 to 180. Valid latitude range: -90 to 90.

MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRY, and COLLECTION types are not supported.

The `area` parameter

Every TairGIS command takes an area argument as its first parameter. An area is a logical container — a Redis key — that groups related geometries. All shapes you add to the same area can be queried together.

Prerequisites

Before you begin, ensure that you have:

• A Tair DRAM-based instance

Update your instance to the latest minor version for more features and higher stability. For more information, see Update the minor version of an instance. For cluster or read/write splitting instances, also update the proxy nodes to the latest minor version to ensure all commands run as expected.

Usage notes

TairGIS data is stored on the Tair instance.

Supported commands

Command syntax conventions:

• UPPERCASE: command keyword

• *Italics*: variable

• [options]: optional parameter; parameters without brackets are required

• A|B: mutually exclusive — specify only one

• ...: the preceding parameter can repeat

GIS.ADD

Adds one or more WKT-described geometries to an area.

Parameters

WKT (well-known text) is a standard text markup language for representing vector geometry objects, spatial reference systems, and transformations between spatial reference systems.

Return value

• Success: the count of geometries added or updated

• Failure: an error message

Example

GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'

Output:

(integer) 1

GIS.GET

Retrieves the WKT of a named geometry within an area.

Parameters

Return value

• Success: the WKT representation of the geometry

• Not found (area or geometry does not exist): nil

• Failure: an error message

Example

Prerequisites: run GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'.

GIS.GET hangzhou campus

Output:

'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'

GIS.GETALL

Retrieves all geometry names in an area, with their WKT by default.

Parameters

Return value

• Success: geometry names and WKT (or names only if WITHOUTWKT is specified)

• Not found (area does not exist): nil

• Failure: an error message

Example

Prerequisites: run GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'.

GIS.GETALL hangzhou

Output:

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

GIS.CONTAINS

Returns the geometries stored in an area that contain the input geometry.

Use GIS.CONTAINS when you have a geometry (such as a coordinate point) and want to know which stored regions enclose it.

Parameters

Return value

• Success: the count and WKT of geometries that contain the input

• Not found (area does not exist): empty list or set

• Failure: an error message

Example

Prerequisites: run GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'.

The following example checks which stored polygons contain the point at (30, 11):

GIS.CONTAINS hangzhou 'POINT (30 11)'

Output:

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

GIS.WITHIN

Returns the geometries stored in an area that fall entirely within the input geometry.

Use GIS.WITHIN when you have a boundary (such as a district polygon) and want to know which stored shapes are completely inside it.

Parameters

MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRY, and COLLECTION types are not supported.

Return value

• Success: the count and WKT of geometries within the input

• Not found (area does not exist): empty list or set

• Failure: an error message

Example

Prerequisites: run GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'.

The following example checks which stored polygons fall inside the larger bounding polygon:

GIS.WITHIN hangzhou 'POLYGON ((30 5, 50 50, 20 50, 5 20, 30 5))'

Output:

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

GIS.INTERSECTS

Returns the geometries stored in an area that share any coordinates with the input geometry.

Use GIS.INTERSECTS when partial overlap is enough — for example, finding all roads that cross a construction zone.

Parameters

Return value

• Success: the count and WKT of geometries that intersect with the input

• Not found (area does not exist): empty list or set

• Failure: an error message

Example

Prerequisites: run GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'.

The following example checks which stored polygons intersect with the linestring from (30, 10) to (40, 40):

GIS.INTERSECTS hangzhou 'LINESTRING (30 10, 40 40)'

Output:

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

GIS.SEARCH

Queries point geometries in an area that fall within a given radius or polygon boundary. This command is the TairGIS equivalent of the native Redis GEORADIUS command.

Specify exactly one of RADIUS, MEMBER, or GEOM to define the search boundary.

Search boundary options (specify exactly one)

Additional options

Return value

• Success: the count and WKT of matching points

• Not found (area does not exist): empty list or set

• Failure: an error message

Example

Prerequisites: run GIS.ADD Sicily "Palermo" "POINT (13.361389 38.115556)" "Catania" "POINT(15.087269 37.502669)".

The following example finds all points in the Sicily area within 200 km of (15, 37), sorted by distance:

GIS.SEARCH Sicily RADIUS 15 37 200 km WITHDIST ASC

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

Deletes a named geometry from an area.

Parameters

Return value

• Success: OK

• Not found (area or geometry does not exist): nil

• Failure: an error message

Example

Prerequisites: run GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'.

GIS.DEL hangzhou campus

Output:

OK

What's next

• Implement geofences by using TairGIS

• Implement local purchase services by using TairGIS