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 new file mode 100644 index 00000000000..f160ef4ea02 --- /dev/null +++ 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))"`|多边形类型| + + + +## 示例 + +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))" | ++----------+-------------------------------------------------+ +``` \ No newline at end of file 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 new file mode 100644 index 00000000000..7ad2bff38d5 --- /dev/null +++ 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 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] | ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +``` \ No newline at end of file