Skip to content

Commit c9269e7

Browse files
izhuxiaoqingizhuxiaoqing
authored
geography (#827)
* geography * Update 10.geography.md * Update 10.geography.md
1 parent f76be88 commit c9269e7

File tree

2 files changed

+179
-0
lines changed

2 files changed

+179
-0
lines changed

‎docs-2.0/3.ngql-guide/3.data-types/10.geography.md

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Geography
2+
3+
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.
4+
5+
## Type description
6+
7+
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.
8+
9+
|Shape|Example|Description|
10+
|:--|:--|:--|
11+
|Point|`"POINT(3 8)"`|Specifies the data type as a point.|
12+
|LineString|`"LINESTRING(3 8, 4.7 73.23)"`|Specifies the data type as a linestring.|
13+
|Polygon|`"POLYGON((0 1, 1 2, 2 3, 0 1))"`|Specifies the data type as a polygon.|
14+
15+
<!--
16+
## Index
17+
18+
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).
19+
20+
```ngql
21+
CREATE TAG INDEX <index_name> ON <tag_name>(<geo_prop_name>) s2_min_level = <int>, s2_max_level = <int>, s2_max_cells = <int>;
22+
```
23+
-->
24+
25+
## Examples
26+
27+
For functions about the geography data type, see [Geography functions](../6.functions-and-expressions/14.geo.md).
28+
29+
```ngql
30+
//Create a Tag to allow storing any geography data type.
31+
nebula> CREATE TAG any_shape(geo geography);
32+
33+
//Create a Tag to allow storing a point only.
34+
nebula> CREATE TAG only_point(geo geography(point));
35+
36+
//Create a Tag to allow storing a linestring only.
37+
nebula> CREATE TAG only_linestring(geo geography(linestring));
38+
39+
//Create a Tag to allow storing a polygon only.
40+
nebula> CREATE TAG only_polygon(geo geography(polygon));
41+
42+
//Create an Edge type to allow storing any geography data type.
43+
nebula> CREATE EDGE any_shape_edge(geo geography);
44+
45+
//Create a vertex to store the geography of a polygon.
46+
nebula> INSERT VERTEX any_shape(geo) VALUES "103":(ST_GeogFromText("POLYGON((0 1, 1 2, 2 3, 0 1))"));
47+
48+
//Create an edge to store the geography of a polygon.
49+
nebula> INSERT EDGE any_shape_edge(geo) VALUES "201"->"302":(ST_GeogFromText("POLYGON((0 1, 1 2, 2 3, 0 1))"));
50+
51+
//Query the geography of Vertex 103.
52+
nebula> FETCH PROP ON any_shape "103" YIELD ST_ASText(any_shape.geo);
53+
+----------+---------------------------------+
54+
| VertexID | ST_ASText(any_shape.geo) |
55+
+----------+---------------------------------+
56+
| "103" | "POLYGON((0 1, 1 2, 2 3, 0 1))" |
57+
+----------+---------------------------------+
58+
59+
//Query the geography of the edge which traverses from Vertex 201 to Vertex 302.
60+
nebula> FETCH PROP ON any_shape_edge "201"->"302" YIELD ST_ASText(any_shape_edge.geo);
61+
+---------------------+---------------------+----------------------+---------------------------------+
62+
| any_shape_edge._src | any_shape_edge._dst | any_shape_edge._rank | ST_ASText(any_shape_edge.geo) |
63+
+---------------------+---------------------+----------------------+---------------------------------+
64+
| "201" | "302" | 0 | "POLYGON((0 1, 1 2, 2 3, 0 1))" |
65+
+---------------------+---------------------+----------------------+---------------------------------+
66+
67+
//Create an index for the geography of the Tag any_shape and run LOOKUP.
68+
nebula> CREATE TAG INDEX any_shape_geo_index ON any_shape(geo);
69+
nebula> REBUILD TAG INDEX any_shape_geo_index;
70+
nebula> LOOKUP ON any_shape YIELD ST_ASText(any_shape.geo);
71+
+----------+-------------------------------------------------+
72+
| VertexID | ST_ASText(any_shape.geo) |
73+
+----------+-------------------------------------------------+
74+
| "103" | "POLYGON((0 1, 1 2, 2 3, 0 1))" |
75+
+----------+-------------------------------------------------+
76+
```

‎docs-2.0/3.ngql-guide/6.functions-and-expressions/14.geo.md

+103
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Geography functions
2+
3+
Geography functions are used to generate or perform operations on the value of the geography data type.
4+
5+
For descriptions of the geography data types, see [Geography](../3.data-types/10.geography.md).
6+
7+
## Descriptions
8+
9+
|Function| Description |
10+
|:----|:----|
11+
|GEOGRAPHY ST_Point(longitude, latitude) |Creates the geography that contains a point.|
12+
|GEOGRAPHY ST_GeogFromText(wkt_string) |Returns the geography corresponding to the input WKT string.|
13+
|STRING ST_ASText(geography) |Returns the WKT string of the input geography.|
14+
|GEOGRAPHY ST_Centroid(geography) |Returns the centroid of the input geography in the form of the single point geography.|
15+
|BOOL ST_ISValid(geography) |Returns whether the input geography is valid.|
16+
|BOOL ST_Intersects(geography_1, geography_2) |Returns whether geography_1 and geography_2 have intersections.|
17+
|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.|
18+
|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.|
19+
|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.|
20+
|FLOAT ST_Distance(geography_1, geography_2) |Returns the smallest possible distance (measured by meters) between two non-empty geographies.|
21+
|INT S2_CellIdFromPoint(point_geography) |Returns the [S2 Cell](https://s2geometry.io/devguide/s2cell_hierarchy) ID that covers the point geography.|
22+
|ARRAY<INT64> S2_CoveringCellIds(geography) |Returns an array of S2 Cell IDs that cover the input geography.|
23+
24+
## Examples
25+
26+
```ngql
27+
nebula> RETURN ST_ASText(ST_Point(1,1))
28+
+--------------------------+
29+
| ST_ASText(ST_Point(1,1)) |
30+
+--------------------------+
31+
| "POINT(1 1)" |
32+
+--------------------------+
33+
34+
nebula> RETURN ST_ASText(ST_GeogFromText("POINT(3 8)"));
35+
+------------------------------------------+
36+
| ST_ASText(ST_GeogFromText("POINT(3 8)")) |
37+
+------------------------------------------+
38+
| "POINT(3 8)" |
39+
+------------------------------------------+
40+
41+
nebula> RETURN ST_ASTEXT(ST_Centroid(ST_GeogFromText("LineString(0 1,1 0)")));
42+
+----------------------------------------------------------------+
43+
| ST_ASTEXT(ST_Centroid(ST_GeogFromText("LineString(0 1,1 0)"))) |
44+
+----------------------------------------------------------------+
45+
| "POINT(0.5000380800773782 0.5000190382261059)" |
46+
+----------------------------------------------------------------+
47+
48+
nebula> RETURN ST_ISValid(ST_GeogFromText("POINT(3 8)"));
49+
+-------------------------------------------+
50+
| ST_ISValid(ST_GeogFromText("POINT(3 8)")) |
51+
+-------------------------------------------+
52+
| true |
53+
+-------------------------------------------+
54+
55+
nebula> RETURN ST_Intersects(ST_GeogFromText("LineString(0 1,1 0)"),ST_GeogFromText("LineString(0 0,1 1)"));
56+
+----------------------------------------------------------------------------------------------+
57+
| ST_Intersects(ST_GeogFromText("LineString(0 1,1 0)"),ST_GeogFromText("LineString(0 0,1 1)")) |
58+
+----------------------------------------------------------------------------------------------+
59+
| true |
60+
+----------------------------------------------------------------------------------------------+
61+
62+
nebula> RETURN ST_Covers(ST_GeogFromText("POLYGON((0 0,10 0,10 10,0 10,0 0))"),ST_Point(1,2));
63+
+--------------------------------------------------------------------------------+
64+
| ST_Covers(ST_GeogFromText("POLYGON((0 0,10 0,10 10,0 10,0 0))"),ST_Point(1,2)) |
65+
+--------------------------------------------------------------------------------+
66+
| true |
67+
+--------------------------------------------------------------------------------+
68+
69+
nebula> RETURN ST_CoveredBy(ST_Point(1,2),ST_GeogFromText("POLYGON((0 0,10 0,10 10,0 10,0 0))"));
70+
+-----------------------------------------------------------------------------------+
71+
| ST_CoveredBy(ST_Point(1,2),ST_GeogFromText("POLYGON((0 0,10 0,10 10,0 10,0 0))")) |
72+
+-----------------------------------------------------------------------------------+
73+
| true |
74+
+-----------------------------------------------------------------------------------+
75+
76+
nebula> RETURN ST_dwithin(ST_GeogFromText("Point(0 0)"),ST_GeogFromText("Point(10 10)"),20000000000.0);
77+
+---------------------------------------------------------------------------------------+
78+
| ST_dwithin(ST_GeogFromText("Point(0 0)"),ST_GeogFromText("Point(10 10)"),20000000000) |
79+
+---------------------------------------------------------------------------------------+
80+
| true |
81+
+---------------------------------------------------------------------------------------+
82+
83+
nebula> RETURN ST_Distance(ST_GeogFromText("Point(0 0)"),ST_GeogFromText("Point(10 10)"));
84+
+----------------------------------------------------------------------------+
85+
| ST_Distance(ST_GeogFromText("Point(0 0)"),ST_GeogFromText("Point(10 10)")) |
86+
+----------------------------------------------------------------------------+
87+
| 1568523.0187677438 |
88+
+----------------------------------------------------------------------------+
89+
90+
nebula> RETURN S2_CellIdFromPoint(ST_GeogFromText("Point(1 1)"));
91+
+---------------------------------------------------+
92+
| S2_CellIdFromPoint(ST_GeogFromText("Point(1 1)")) |
93+
+---------------------------------------------------+
94+
| 1153277837650709461 |
95+
+---------------------------------------------------+
96+
97+
nebula> RETURN S2_CoveringCellIds(ST_GeogFromText("POLYGON((0 1, 1 2, 2 3, 0 1))"));
98+
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
99+
| S2_CoveringCellIds(ST_GeogFromText("POLYGON((0 1, 1 2, 2 3, 0 1))")) |
100+
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
101+
| [1152391494368201343, 1153466862374223872, 1153554823304445952, 1153836298281156608, 1153959443583467520, 1154240918560178176, 1160503736791990272, 1160591697722212352] |
102+
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
103+
```

0 commit comments

Comments
 (0)