Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/geo-type/
Documentation version: v5.3.2

# Spatial types

Spatial types are composite data types that consist of longitude and latitude coordinates to represent spatial data. GQL supports three spatial types: point, linestring, and polygon.

For ease of reading, we use the [Well-Known Text (WKT)](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) string to represent the spatial values projected onto the surface of a sphere.

## Point type

WKT format: `POINT(longitude latitude)`

The point type represents a single point on the surface of a sphere, defined by its longitude and latitude coordinates. For example, `POINT(37.7749 -12.4194)`, where `37.7749` is the longitude and `-12.4194` is the latitude.

Note that the coordinates must be in the range of `-180` to `180` for longitude and `-90` to `90` for latitude, which applies to all spatial types.

## Linestring type

WKT format: `LINESTRING(longitude1 latitude1, longitude2 latitude2, ...)`

The linestring type represents a sequence of points connected by straight lines, forming a continuous path on the surface of a sphere.

Each pair of longitude and latitude coordinates represents a point in the path. For example, `LINESTRING(1 2, 2 4, 4 8, 8 16)` represents a path that starts at the point `POINT(1 2)`, goes to `POINT(2 4)`, then to `POINT(4 8)`, and finally to `POINT(8 16)`.

The linestring type can also represent a closed path by repeating the first point at the end, but it is not required to do so.

## Polygon type

WKT format: `POLYGON((longitude1 latitude1, longitude2 latitude2, ...), ...)`

The polygon type represents a shape with a closed outer boundary and may include zero or more holes. It is defined by a sequence of points that form the outer boundary, and optionally, one or more sequences of points that define holes within the polygon.

For example, `POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))` defines a polygon with an outer boundary that starts at the point `POINT(0 0)`, goes to `POINT(0 10)`, then to `POINT(10 10)`, to `POINT(10 0)`, and finally back to `POINT(0 0)` to close the shape. It has no holes.

To define a polygon containing multiple holes, you can refer to this example: `POLYGON((0 0, 0 10, 10 10, 10 0, 0 0), (2 2, 4 2, 4 4, 2 4, 2 2), (6 6, 8 6, 8 8, 6 8, 6 6))`. In this case, the outer boundary is defined by the first sequence of points, and the two subsequent sequences of points define the holes within the polygon.

Note the following limitations when defining polygons:

- Each polygon must have at least four points connected in a closed loop as its outer boundary. The first and last points must be the same to close the polygon.
- Each polygon must not intersect itself, meaning the lines connecting the points must not cross each other.
- If a polygon contains holes:

  - Each hole must also be defined by at least four points connected in a closed loop, with the first and last points being the same.
  - The holes must not intersect with each other or with the outer boundary of the polygon, except at the boundary points.
  - The holes must be completely contained within the outer boundary of the polygon and must not overlap each other.

## How to use

To use spatial types to store spatial data, follow these steps:

1. 

Declare the spatial types in your graph type definition.

````
'''
CREATE GRAPH TYPE IF NOT EXISTS location AS 
  { NODE Person 
      ( { 
          id INT64 PRIMARY KEY, 
          any_geo Geography(Any), 
          home_location Geography(Point), 
          commute_route Geography(LineString), 
          favorite_area Geography(Polygon) } ), 
  EDGE GEdge (Person)-[LABEL hire {company_location Geography(Point)}]->(Person) }
'''

````

The syntax for declaring spatial types is as follows:

  - `Geography(Any)` or `Geography` alone refers to a generic spatial type that can be any of the three types (point, linestring, or polygon).
  - `Geography(Point)` refers specifically to the point type.
  - `Geography(LineString)` refers specifically to the linestring type.
  - `Geography(Polygon)` refers specifically to the polygon type.

2. 

Create a graph based on the declared graph type.

````
CREATE GRAPH IF NOT EXISTS my_graph TYPED location

````

3. 

Insert data into the graph. Note that you must use [spatial functions](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/geo/) to generate spatial values when inserting data.

Insert new nodes:

````
'''
USE my_graph INSERT OR REPLACE 
(@Person {id: 101, 
  any_geo: ST_GeogFromText('POINT(37.7749 -12.4194)'), 
  home_location: ST_GeogFromText('POINT(37.7749 -12.4194)'), 
  commute_route: ST_GeogFromText('LINESTRING(1 2, 2 4, 4 8, 8 16)'), 
  favorite_area: ST_GeogFromText('POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))') }), 
(@Person {id: 102, 
  any_geo: ST_GeogFromText('POINT(34.0522 -18.2437)'), 
  home_location: ST_GeogFromText('POINT(34.0522 -18.2437)'), 
  commute_route: ST_GeogFromText('LINESTRING(3 4, 5 6, 7 8, 9 10)'), 
  favorite_area: ST_GeogFromText('POLYGON((0 0, 0 10, 10 10, 10 0, 0 0), (2 2, 4 2, 4 4, 2 4, 2 2))') })
'''

````

Based on the above nodes, insert new edges:

````
'''
USE my_graph Match (n@Person{id:101}), (m@Person{id:102}) 
INSERT (n)-[@GEdge {company_location: ST_GeogFromText('POINT(37.7749 -12.4194)')}]->(m)
'''

````

4. 

Query the graph to retrieve spatial data. You must use the function [`ST_ASText()`](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/geo/#st_astext) to convert spatial values to Well-Known Text (WKT) strings for display purposes.

````
'''
USE my_graph MATCH (p {id:101}) RETURN p.id, ST_ASText(p.home_location) AS home_location, 
ST_ASText(p.commute_route) AS commute_route, ST_ASText(p.favorite_area) AS favorite_area
'''

````

Return:

````
+------+-------------------------+---------------------------------+----------------------------------------+
| p.id | home_location           | commute_route                   | favorite_area                          |
+------+-------------------------+---------------------------------+----------------------------------------+
| 101  | POINT(37.7749 -12.4194) | LINESTRING(1 2, 2 4, 4 8, 8 16) | POLYGON((0 0, 0 10, 10 10, 10 0, 0 0)) |
+------+-------------------------+---------------------------------+----------------------------------------+

````

## More information

[Spatial functions](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/geo/)