Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add geo #1081

Merged
merged 4 commits into from
Oct 22, 2021
Merged

add geo #1081

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
31027f8
add geo
cooper-lzy Oct 21, 2021
1324190
update
cooper-lzy Oct 22, 2021
450f5ba
update
cooper-lzy Oct 22, 2021
7233d1a
update
cooper-lzy Oct 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 76 additions & 0 deletions docs-2.0/3.ngql-guide/3.data-types/10.geography.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# 地理位置

地理位置（GEOGRAPHY）是由经纬度构成的表示地理空间信息的数据类型。Nebula Graph当前支持部分WKT（Well-Know-Text）标准的数据类型，通过函数将地理空间信息数据转化为WKB(Well-Know-Binary)标准的二进制序列进行存储。
cooper-lzy marked this conversation as resolved.
Show resolved Hide resolved

## GEOGRAPHY

GEOGRAPHY的基本类型是点，由`经度 纬度`确定一个点，例如`"POINT(3 8)"`表示经度为`3°`，纬度为`8°`。多个点可以构成线段或多边形。
cooper-lzy marked this conversation as resolved.
Show resolved Hide resolved

|类型|示例|说明|
|:--|:--|:--|
|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，仅支持点形状地理位置数据类型。
cooper-lzy marked this conversation as resolved.
Show resolved Hide resolved
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))" |
+----------+-------------------------------------------------+
```
103 changes: 103 additions & 0 deletions docs-2.0/3.ngql-guide/6.functions-and-expressions/14.geo.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
# geo函数

geo函数用于生成地理位置（GEOGRAPHY）数据类型的值或对其执行操作。

关于地理位置数据类型说明请参见[地理位置](../3.data-types/10.geography.md)。

## 函数说明

|函数| 说明 |
|:----|:----|
|GEOGRAPHY ST_Point(longitude, latitude) |创建包含一个点的地理位置。如需将GEOGRAPHY的格式设置为WKT，请使用`ST_ASText`。|
cooper-lzy marked this conversation as resolved.
Show resolved Hide resolved
|GEOGRAPHY ST_GeogFromText(wkt_string) |返回与传入的WKT字符串形式相对应的GEOGRAPHY。如需将GEOGRAPHY的格式设置为WKT，请使用`ST_ASText`。|
cooper-lzy marked this conversation as resolved.
Show resolved Hide resolved
|STRING ST_ASText(geography_expression) |返回传入的GEOGRAPHY的WKT字符串形式。|
|GEOGRAPHY ST_Centroid(geography_expression) |以单点GEOGRAPHY的形式返回传入的GEOGRAPHY的形心。|
|BOOL ST_ISValid(geography_expression) |返回传入的GEOGRAPHY是否有效。 |
cooper-lzy marked this conversation as resolved.
Show resolved Hide resolved
|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] |
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
```