add geo (#1081)

* add geo * update * update * update
vesoft-inc · Oct 22, 2021 · 8d02242 · 8d02242
1 parent e0a53eb
commit 8d02242
Show file tree

Hide file tree

Showing 2 changed files with 179 additions and 0 deletions.
diff --git a/docs-2.0/3.ngql-guide/3.data-types/10.geography.md b/docs-2.0/3.ngql-guide/3.data-types/10.geography.md
@@ -0,0 +1,76 @@
+# 地理位置
+
+地理位置（GEOGRAPHY）是由经纬度构成的表示地理空间信息的数据类型。Nebula Graph当前支持[简单地理要素](https://en.wikipedia.org/wiki/Simple_Features)中的Point、LineString和Polygon三种地理形状。支持[SQL-MM 3](https://www.techrepublic.com/index.php/resource-library/whitepapers/sql-mm-spatial-the-standard-to-manage-spatial-data-in-relational-database-systems/)中的部分核心geo解析、构造、格式设置、转换、谓词和度量等函数。
+
+## GEOGRAPHY
+
+GEOGRAPHY的基本类型是点，由经纬度确定一个点，例如`"POINT(3 8)"`表示经度为`3°`，纬度为`8°`。多个点可以构成线段或多边形。
+
+|类型|示例|说明|
+|:--|:--|:--|
+|Point|`"POINT(3 8)"`|点类型|
+|LineString|`"LINESTRING(3 8, 4.7 73.23)"`|线段类型|
+|Polygon|`"POLYGON((0 1, 1 2, 2 3, 0 1))"`|多边形类型|
+
+<!--
+## 索引
+
+为GEOGRAPHY类型数据创建索引时，支持指定[S2单元](https://s2geometry.io/devguide/s2cell_hierarchy)覆盖选项。
+
+```ngql
+CREATE TAG INDEX <index_name> ON <tag_name>(<geo_prop_name>) s2_min_level = <int>, s2_max_level = <int>, s2_max_cells = <int>;
+```
+-->
+
+## 示例
+
+geo相关函数请参见[geo函数](../6.functions-and-expressions/14.geo.md)。
+
+```ngql
+//创建Tag，允许存储任意形状地理位置数据类型。
+nebula> CREATE TAG any_shape(geo geography);
+
+//创建Tag，只允许存储点形状地理位置数据类型。
+nebula> CREATE TAG only_point(geo geography(point));
+
+//创建Tag，只允许存储线段形状地理位置数据类型。
+nebula> CREATE TAG only_linestring(geo geography(linestring));
+
+//创建Tag，只允许存储多边形形状地理位置数据类型。
+nebula> CREATE TAG only_polygon(geo geography(polygon));
+
+//创建Edge type，允许存储任意形状地理位置数据类型。
+nebula> CREATE EDGE any_shape_edge(geo geography);
+
+//创建存储多边形地理位置的点。
+nebula> INSERT VERTEX any_shape(geo) VALUES "103":(ST_GeogFromText("POLYGON((0 1, 1 2, 2 3, 0 1))"));
+
+//创建存储多边形地理位置的边。
+nebula> INSERT EDGE any_shape_edge(geo) VALUES "201"->"302":(ST_GeogFromText("POLYGON((0 1, 1 2, 2 3, 0 1))"));
+
+//查询点103的属性geo。
+nebula> FETCH PROP ON any_shape "103" YIELD ST_ASText(any_shape.geo);
++----------+---------------------------------+
+| VertexID | ST_ASText(any_shape.geo)        |
++----------+---------------------------------+
+| "103"    | "POLYGON((0 1, 1 2, 2 3, 0 1))" |
++----------+---------------------------------+
+
+//查询边201->302的属性geo。
+nebula> FETCH PROP ON any_shape_edge "201"->"302" YIELD ST_ASText(any_shape_edge.geo);
++---------------------+---------------------+----------------------+---------------------------------+
+| any_shape_edge._src | any_shape_edge._dst | any_shape_edge._rank | ST_ASText(any_shape_edge.geo)   |
++---------------------+---------------------+----------------------+---------------------------------+
+| "201"               | "302"               | 0                    | "POLYGON((0 1, 1 2, 2 3, 0 1))" |
++---------------------+---------------------+----------------------+---------------------------------+
+
+//为geo属性创建索引并使用LOOKUP查询。
+nebula> CREATE TAG INDEX any_shape_geo_index ON any_shape(geo);
+nebula> REBUILD TAG INDEX any_shape_geo_index;
+nebula> LOOKUP ON any_shape YIELD ST_ASText(any_shape.geo);
++----------+-------------------------------------------------+
+| VertexID | ST_ASText(any_shape.geo)                        |
++----------+-------------------------------------------------+
+| "103"    | "POLYGON((0 1, 1 2, 2 3, 0 1))"                 |
++----------+-------------------------------------------------+
+```
diff --git a/docs-2.0/3.ngql-guide/6.functions-and-expressions/14.geo.md b/docs-2.0/3.ngql-guide/6.functions-and-expressions/14.geo.md
@@ -0,0 +1,103 @@
+# geo函数
+
+geo函数用于生成地理位置（GEOGRAPHY）数据类型的值或对其执行操作。
+
+关于地理位置数据类型说明请参见[地理位置](../3.data-types/10.geography.md)。
+
+## 函数说明
+
+|函数| 说明 |
+|:----|:----|
+|GEOGRAPHY ST_Point(longitude, latitude)            |创建包含一个点的地理位置。|
+|GEOGRAPHY ST_GeogFromText(wkt_string)              |返回与传入的WKT字符串形式相对应的GEOGRAPHY。|
+|STRING ST_ASText(geography)                        |返回传入的GEOGRAPHY的WKT字符串形式。|
+|GEOGRAPHY ST_Centroid(geography)                   |以单点GEOGRAPHY的形式返回传入的GEOGRAPHY的形心。|
+|BOOL ST_ISValid(geography)                         |返回传入的GEOGRAPHY是否有效。 |
+|BOOL ST_Intersects(geography_1, geography_2)       |返回传入的两个GEOGRAPHY是否有交集。|
+|BOOL ST_Covers(geography_1, geography_2)           |返回geography_1是否完全包含geography_2。如果geography_2中没有位于geography_1外部的点，返回True。|
+|BOOL ST_CoveredBy(geography_1, geography_2)        |返回geography_2是否完全包含geography_1。如果geography_1中没有位于geography_2外部的点，返回True。|
+|BOOL ST_DWithin(geography_1, geography_2, distance)|如果geography_1中至少有一个点与geography_2中的一个点的距离小于或等于distance参数（以米为单位）指定的距离，则返回True。   |
+|FLOAT ST_Distance(geography_1, geography_2)        |返回两个非空GEOGRAPHY之间的最短距离（以米为单位）。|
+|INT S2_CellIdFromPoint(point_geography)            |返回覆盖点GEOGRAPHY的[S2单元](https://s2geometry.io/devguide/s2cell_hierarchy)ID。|
+|ARRAY<INT64> S2_CoveringCellIds(geography)         |返回覆盖传入的GEOGRAPHY的S2单元ID的数组。|
+
+## 示例
+
+```ngql
+nebula> RETURN ST_ASText(ST_Point(1,1))
++--------------------------+
+| ST_ASText(ST_Point(1,1)) |
++--------------------------+
+| "POINT(1 1)"             |
++--------------------------+
+
+nebula> RETURN ST_ASText(ST_GeogFromText("POINT(3 8)"));
++------------------------------------------+
+| ST_ASText(ST_GeogFromText("POINT(3 8)")) |
++------------------------------------------+
+| "POINT(3 8)"                             |
++------------------------------------------+
+
+nebula> RETURN ST_ASTEXT(ST_Centroid(ST_GeogFromText("LineString(0 1,1 0)")));
++----------------------------------------------------------------+
+| ST_ASTEXT(ST_Centroid(ST_GeogFromText("LineString(0 1,1 0)"))) |
++----------------------------------------------------------------+
+| "POINT(0.5000380800773782 0.5000190382261059)"                 |
++----------------------------------------------------------------+
+
+nebula> RETURN ST_ISValid(ST_GeogFromText("POINT(3 8)"));
++-------------------------------------------+
+| ST_ISValid(ST_GeogFromText("POINT(3 8)")) |
++-------------------------------------------+
+| true                                      |
++-------------------------------------------+
+
+nebula> RETURN ST_Intersects(ST_GeogFromText("LineString(0 1,1 0)"),ST_GeogFromText("LineString(0 0,1 1)"));
++----------------------------------------------------------------------------------------------+
+| ST_Intersects(ST_GeogFromText("LineString(0 1,1 0)"),ST_GeogFromText("LineString(0 0,1 1)")) |
++----------------------------------------------------------------------------------------------+
+| true                                                                                         |
++----------------------------------------------------------------------------------------------+
+
+nebula> RETURN ST_Covers(ST_GeogFromText("POLYGON((0 0,10 0,10 10,0 10,0 0))"),ST_Point(1,2));
++--------------------------------------------------------------------------------+
+| ST_Covers(ST_GeogFromText("POLYGON((0 0,10 0,10 10,0 10,0 0))"),ST_Point(1,2)) |
++--------------------------------------------------------------------------------+
+| true                                                                           |
++--------------------------------------------------------------------------------+
+
+nebula> RETURN ST_CoveredBy(ST_Point(1,2),ST_GeogFromText("POLYGON((0 0,10 0,10 10,0 10,0 0))"));
++-----------------------------------------------------------------------------------+
+| ST_CoveredBy(ST_Point(1,2),ST_GeogFromText("POLYGON((0 0,10 0,10 10,0 10,0 0))")) |
++-----------------------------------------------------------------------------------+
+| true                                                                              |
++-----------------------------------------------------------------------------------+
+
+nebula> RETURN ST_dwithin(ST_GeogFromText("Point(0 0)"),ST_GeogFromText("Point(10 10)"),20000000000.0);
++---------------------------------------------------------------------------------------+
+| ST_dwithin(ST_GeogFromText("Point(0 0)"),ST_GeogFromText("Point(10 10)"),20000000000) |
++---------------------------------------------------------------------------------------+
+| true                                                                                  |
++---------------------------------------------------------------------------------------+
+
+nebula> RETURN ST_Distance(ST_GeogFromText("Point(0 0)"),ST_GeogFromText("Point(10 10)"));
++----------------------------------------------------------------------------+
+| ST_Distance(ST_GeogFromText("Point(0 0)"),ST_GeogFromText("Point(10 10)")) |
++----------------------------------------------------------------------------+
+| 1568523.0187677438                                                         |
++----------------------------------------------------------------------------+
+
+nebula> RETURN S2_CellIdFromPoint(ST_GeogFromText("Point(1 1)"));
++---------------------------------------------------+
+| S2_CellIdFromPoint(ST_GeogFromText("Point(1 1)")) |
++---------------------------------------------------+
+| 1153277837650709461                               |
++---------------------------------------------------+
+
+nebula> RETURN S2_CoveringCellIds(ST_GeogFromText("POLYGON((0 1, 1 2, 2 3, 0 1))"));
++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| S2_CoveringCellIds(ST_GeogFromText("POLYGON((0 1, 1 2, 2 3, 0 1))"))                                                                                                     |
++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| [1152391494368201343, 1153466862374223872, 1153554823304445952, 1153836298281156608, 1153959443583467520, 1154240918560178176, 1160503736791990272, 1160591697722212352] |
++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+```