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

geography #827

Merged
merged 3 commits into from
Oct 26, 2021
Merged

geography #827

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
085090d
geography
izhuxiaoqing Oct 25, 2021
29f771c
Update 10.geography.md
izhuxiaoqing Oct 26, 2021
db49e9f
Update 10.geography.md
izhuxiaoqing Oct 26, 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

Geography is a data type composed of latitude and longitude that represents geospatial information. Nebula Graph currently supports Point, LineString, and Polygon in [Simple Features](https://en.wikipedia.org/wiki/Simple_Features) and some functions in [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/), such as part of the core geo parsing, construction, formatting, conversion, predicates, and dimensions.

## Type description

A point is the basic data type of geography, which is determined by a latitude and a longitude. For example, `"POINT(3 8)"` means that the longitude is `3°` and the latitude is `8°`. Multiple points can form a linestring or a polygon.

|Shape|Example|Description|
|:--|:--|:--|
|Point|`"POINT(3 8)"`|Specifies the data type as a point.|
|LineString|`"LINESTRING(3 8, 4.7 73.23)"`|Specifies the data type as a linestring.|
|Polygon|`"POLYGON((0 1, 1 2, 2 3, 0 1))"`|Specifies the data type as a polygon.|

<!--
## Index

When creating an index for the geography type data, you can specify the covering options of the [S2 Cell](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>;
```
-->

## Examples

For functions about the geography data type, see [Geography functions](../6.functions-and-expressions/14.geo.md).

```ngql
//Create a Tag to allow storing any geography data type.
nebula> CREATE TAG any_shape(geo geography);

//Create a Tag to allow storing a point only.
nebula> CREATE TAG only_point(geo geography(point));

//Create a Tag to allow storing a linestring only.
nebula> CREATE TAG only_linestring(geo geography(linestring));

//Create a Tag to allow storing a polygon only.
nebula> CREATE TAG only_polygon(geo geography(polygon));

//Create an Edge type to allow storing any geography data type.
nebula> CREATE EDGE any_shape_edge(geo geography);

//Create a vertex to store the geography of a polygon.
nebula> INSERT VERTEX any_shape(geo) VALUES "103":(ST_GeogFromText("POLYGON((0 1, 1 2, 2 3, 0 1))"));

//Create an edge to store the geography of a polygon.
nebula> INSERT EDGE any_shape_edge(geo) VALUES "201"->"302":(ST_GeogFromText("POLYGON((0 1, 1 2, 2 3, 0 1))"));

//Query the geography of Vertex 103.
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))" |
+----------+---------------------------------+

//Query the geography of the edge which traverses from Vertex 201 to Vertex 302.
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))" |
+---------------------+---------------------+----------------------+---------------------------------+

//Create an index for the geography of the Tag any_shape and run 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 @@
# Geography functions

Geography functions are used to generate or perform operations on the value of the geography data type.

For descriptions of the geography data types, see [Geography](../3.data-types/10.geography.md).

## Descriptions

|Function| Description |
|:----|:----|
|GEOGRAPHY ST_Point(longitude, latitude) |Creates the geography that contains a point.|
|GEOGRAPHY ST_GeogFromText(wkt_string) |Returns the geography corresponding to the input WKT string.|
|STRING ST_ASText(geography) |Returns the WKT string of the input geography.|
|GEOGRAPHY ST_Centroid(geography) |Returns the centroid of the input geography in the form of the single point geography.|
|BOOL ST_ISValid(geography) |Returns whether the input geography is valid.|
|BOOL ST_Intersects(geography_1, geography_2) |Returns whether geography_1 and geography_2 have intersections.|
|BOOL ST_Covers(geography_1, geography_2) |Returns whether geography_1 completely contains geography_2. If there is no point outside geography_1 in geography_2, return True.|
|BOOL ST_CoveredBy(geography_1, geography_2) |Returns whether geography_2 completely contains geography_1.If there is no point outside geography_2 in geography_1, return True.|
|BOOL ST_DWithin(geography_1, geography_2, distance)|If the distance between one point (at least) in geography_1 and one point in geography_2 is less than or equal to the distance specified by the distance parameter (measured by meters), return True.|
|FLOAT ST_Distance(geography_1, geography_2) |Returns the smallest possible distance (measured by meters) between two non-empty geographies.|
|INT S2_CellIdFromPoint(point_geography) |Returns the [S2 Cell](https://s2geometry.io/devguide/s2cell_hierarchy) ID that covers the point geography.|
|ARRAY<INT64> S2_CoveringCellIds(geography) |Returns an array of S2 Cell IDs that cover the input geography.|

## Examples

```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] |
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
```