GIS

TairGis是一种使用R-Tree做索引,支持地理信息系统GIS(Geographic Information System)相关接口的数据结构。Redis的原生GEO命令是使用GeoHash和Redis Sorted Set结构完成的,主要用于点的查询,TairGIS在此基础上还支持线、面的查询,功能更加强大。

主要特性

  • 使用R-Tree作为索引存储。

  • 支持线、面的相关查询(含相交查询)。

  • 通过GIS.SEARCH可实现原生Redis GEORADIUS命令的功能。

该Module已开源,更多信息请参见TairGIS

最佳实践

前提条件

实例为Tair内存型

说明

最新小版本将提供更丰富的功能与稳定的服务,建议将实例的小版本升级到最新,具体操作请参见升级小版本。如果您的实例为集群架构或读写分离架构,请将代理节点的小版本也升级到最新,否则可能出现命令无法识别的情况。

注意事项

操作对象为Tair实例中的TairGIS数据。

命令列表

表 1. TairGIS命令

命令

语法

说明

GIS.ADD

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

在area中添加指定名称的多边形(可添加多个),使用WKT(Well-known text)描述。

说明

WKT是一种文本标记语言,用于描述矢量几何对象、空间参照系统及空间参照系统之间的转换。

GIS.GET

GIS.GET area polygonName

获取目标area中指定多边形的WKT信息。

GIS.GETALL

GIS.GETALL area [WITHOUTWKT]

获取目标area中所有多边形的名称和WKT信息。如果设置了WITHOUTWKT选项,仅返回多边形的名称。

GIS.CONTAINS

GIS.CONTAINS area polygonWkt [WITHOUTWKT]

判断指定的点、线或面是否包含在目标area的多边形中,若包含,则返回目标area中命中的多边形数量与多边形信息。

GIS.WITHIN

GIS.WITHIN area polygonWkt [WITHOUTWKT]

判断目标area是否包含在指定的点、线或面中,若包含,则返回目标area中命中的多边形数量与多边形信息。

GIS.INTERSECTS

GIS.INTERSECTS area polygonWkt

判断指定的点、线或面与目标area的多边形是否相交,若相交,则返回目标area中与其相交的多边形数量与多边形信息。

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]

在指定经、纬度及半径距离范围内,查找目标area中的点。

GIS.DEL

GIS.DEL area polygonName

删除目标area中指定的多边形。

DEL

DEL key [key ...]

原生Redis命令,可以删除一条或多条TairGIS数据。

说明

本文的命令语法定义如下:

  • 大写关键字:命令关键字。

  • 斜体:变量。

  • [options]:可选参数,不在括号中的参数为必选。

  • A|B:该组参数互斥,请进行二选一或多选一。

  • ...:前面的内容可重复。

GIS.ADD

类别

说明

语法

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

时间复杂度

O(log n)

命令描述

在area中添加指定名称的多边形(可添加多个),使用WKT(Well-known text)描述。

说明

WKT是一种文本标记语言,用于描述矢量几何对象、空间参照系统及空间参照系统之间的转换。

选项

  • area:一个几何概念。

  • PolygonName:多边形的名称。

  • polygonWkt:多边形的描述信息,表示现实世界的经、纬度,使用WKT(Well-known text)描述,支持如下类型。

    • POINT:描述一个点的WKT信息,例如'POINT (120.086631 30.138141)',表示该POINT位于经度120.086631,纬度30.138141。

    • LINESTRING:描述一条线的WKT信息,由两个POINT组成,例如'LINESTRING (30 10, 40 40)'

    • POLYGON:描述一个多边形的WKT信息,由多个POINT组成,例如'POLYGON ((31 20, 29 20, 29 21, 31 31))'

    说明
    • 经度的取值范围为(-180,180), 纬度的取值范围为(-90,90)。

    • 不支持如下集合类型:MULTIPOINT、MULTILINESTRING、MULTIPOLYGON、GEOMETRY和COLLECTION。

返回值

  • 执行成功:返回插入和更新成功的多边形数量。

  • 其它情况返回相应的异常信息。

示例

命令示例:

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

返回示例:

(integer) 1

GIS.GET

类别

说明

语法

GIS.GET area polygonName

时间复杂度

O(1)

命令描述

获取目标area中指定多边形的WKT信息。

选项

  • area:一个几何概念。

  • PolygonName:多边形的名称。

返回值

  • 执行成功:WKT信息。

  • area或polygonName不存在:nil。

  • 其它情况返回相应的异常信息。

示例

提前执行GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'命令。

命令示例:

GIS.GET hangzhou campus

返回示例:

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

GIS.GETALL

类别

说明

语法

GIS.GETALL area [WITHOUTWKT]

时间复杂度

O(n)

命令描述

获取目标area中所有多边形的名称和WKT信息。如果设置了WITHOUTWKT选项,仅返回多边形的名称。

选项

  • area:一个几何概念。

  • WITHOUTWKT:用于控制是否返回多边形的WKT信息,如果加上该参数,则不返回多边形的WKT信息。

返回值

  • 执行成功:返回多边形名称和WKT信息,如果设置了WITHOUTWKT选项,仅返回多边形的名称。

  • area不存在:nil。

  • 其它情况返回相应的异常信息。

示例

提前执行GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'命令。

命令示例:

GIS.GETALL hangzhou

返回示例:

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

GIS.CONTAINS

类别

说明

语法

GIS.CONTAINS area polygonWkt [WITHOUTWKT]

时间复杂度

  • 最理想情况:log公式

  • 最差情况:O(log n)

命令描述

判断指定的点、线或面是否包含在目标area的多边形中,若包含,则返回目标area中命中的多边形数量与多边形信息。

选项

  • area:一个几何概念。

  • polygonWkt:指定与目标area进行比较的多边形描述信息,使用WKT(Well-known text)描述,支持如下类型。

    • POINT:描述一个点的WKT信息。

    • LINESTRING:描述一条线的WKT信息。

    • POLYGON:描述一个多边形的WKT信息。

  • WITHOUTWKT:用于控制是否返回多边形的WKT信息,如果加上该参数,则不返回多边形的WKT信息。

返回值

  • 执行成功:命中的多边形数量与多边形信息。

  • area不存在:empty list or set。

  • 其它情况返回相应的异常信息。

示例

提前执行GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'命令。

命令示例:

GIS.CONTAINS hangzhou 'POINT (30 11)'

返回示例:

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

GIS.WITHIN

类别

说明

语法

GIS.WITHIN area polygonWkt [WITHOUTWKT]

时间复杂度

  • 最理想情况:log公式

  • 最差情况:O(log n)

命令描述

判断目标area是否包含在指定的点、线或面中,若包含,则返回目标area中命中的多边形数量与多边形信息。

选项

  • area:一个几何概念。

  • polygonWkt:指定与目标area进行比较的多边形描述信息,使用WKT(Well-known text)描述,支持如下类型。

    • POINT:描述一个点的WKT信息。

    • LINESTRING:描述一条线的WKT信息。

    • POLYGON:描述一个多边形的WKT信息。

    说明

    不支持MULTIPOINT、MULTILINESTRING、MULTIPOLYGON、GEOMETRY和COLLECTION。

  • WITHOUTWKT:用于控制是否返回多边形的WKT信息,如果加上该参数,则不返回多边形的WKT信息。

返回值

  • 执行成功:命中的多边形数量与多边形信息。

  • area不存在:empty list or set。

  • 其它情况返回相应的异常信息。

示例

提前执行GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'命令。

命令示例:

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

返回示例:

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

GIS.INTERSECTS

类别

说明

语法

GIS.INTERSECTS area polygonWkt

时间复杂度

  • 最理想情况:log公式

  • 最差情况:O(log n)

命令描述

判断指定的点、线或面与目标area的多边形是否相交,若相交,则返回目标area中与其相交的多边形数量与多边形信息。

选项

  • area:一个几何概念。

  • polygonWkt:指定与目标area进行比较的多边形描述信息,使用WKT(Well-known text)描述,支持如下类型。

    • POINT:描述一个点的WKT信息。

    • LINESTRING:描述一条线的WKT信息。

    • POLYGON:描述一个多边形的WKT信息。

  • WITHOUTWKT:用于控制是否返回多边形的WKT信息,如果加上该参数,则不返回多边形的WKT信息。

返回值

  • 执行成功:命中的多边形数量与多边形信息。

  • area不存在:empty list or set。

  • 其它情况返回相应的异常信息。

示例

提前执行GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'命令。

命令示例:

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

返回示例:

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

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]

时间复杂度

  • 最理想情况:log公式

  • 最差情况:O(log n)

命令描述

在指定经、纬度及半径距离范围内,查找目标area中的点。

选项

  • area:一个几何概念。

  • RADIUS:传入经度(longitude)、纬度(latitude)、半径距离(distance)和半径单位(M表示米、KM表示千米、FT表示英尺、MI表示英里)进行搜索,例如RADIUS 15 37 200 KM

  • MEMBER:选择当前area中已存在的POINT作为搜索原点,并指定半径进行搜索,取值顺序为多边形名称(field)、半径(distance)、半径单位(M表示米、KM表示千米、FT表示英尺、MI表示英里),例如MEMBER Agrigento 100 KM

  • GEOM:按照WKT的格式设置搜索范围,可以是任意多边形,例如GEOM 'POLYGON((10 30,20 30,20 40,10 40))'

  • COUNT:用于限定返回的个数,例如COUNT 3

  • ASC|DESC:用于控制返回信息按照距离排序,ASC表示根据中心位置,由近到远排序;DESC表示由远到近排序。

  • WITHDIST:用于控制是否返回目标点与搜索原点的距离。

  • WITHOUTWKT:用于控制是否返回目标点的WKT信息,如果加上该参数,则不返回WKT信息。

说明

只能同时使用RADIUSMEMBERGEOM中的一种方式。

返回值

  • 执行成功:命中的目标点数量与WKT信息。

  • area不存在:empty list or set。

  • 其它情况返回相应的异常信息。

示例

提前执行GIS.ADD Sicily "Palermo" "POINT (13.361389 38.115556)" "Catania" "POINT(15.087269 37.502669)"命令。

命令示例:

GIS.SEARCH Sicily RADIUS 15 37 200 km WITHDIST ASC

返回示例:

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

类别

说明

语法

GIS.DEL area polygonName

时间复杂度

O(log n)

命令描述

删除目标area中指定的多边形。

选项

  • area:一个几何概念。

  • PolygonName:多边形的名称。

返回值

  • 执行成功:OK。

  • area或polygonName不存在:nil。

  • 其它情况返回相应的异常信息。

示例

提前执行GIS.ADD hangzhou campus 'POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'命令。

命令示例:

GIS.DEL hangzhou campus

返回示例:

OK