> 本文首發於 **[Nebula Graph Community 公眾號](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/WeChatOffical.png)**

![Geospatial Data 在 Nebula Graph 中的實踐](https://www-cdn.nebula-graph.com.cn/nebula-blog/geospatial-data-practice.webp)

本文主要介紹了地理空間資料（Geospatial Data）以及它在 Nebula Graph 中的具體實踐。

# Geospatial Data 在 Nebula Graph 中的實踐

## 什麼是 Geospatial Data

地理空間資料（Geospatial Data）是包含簡單地理空間要素資訊的資料，比如點（point）、線（linestring）、多邊形（polygon），或是其他更復雜的形狀。

Nebula Graph 在 2.6 版本中引入了對 Geospatial Data 完整的支援，包括地理空間資料的儲存、計算，以及索引。Nebula Graph 目前支援 Geography 型別的地理空間資料，Geography 型別是建模在地球空間座標系上由經緯度座標對錶示的地理位置資訊。

### Geospatial Data -- 地理空間資料使用

#### 建立 Schema

這裡僅以 Tag 為例，當然 Edgetype 上同樣可以將 Geography 型別作為屬性列。

Nebula 目前支援點、線、多邊形三種空間資料型別。下面介紹一下如何如何建立 Geography 型別屬性以及如何插入地理空間資料到 Nebula 中。

```
CREATE TAG any_shape(geo geography);
CREATE TAG only_point(geo geography(point));
CREATE TAG only_linestring(geo geography(linestring));
CREATE TAG only_polygon(geo geography(polygon));
```

當 `geography` 屬性後面沒有指定具體的地理形狀資訊時，代表該列可以儲存任意地理形狀的資料；當指定形狀型別時，則代表只能儲存該形狀的地理資料，比如 `geography(point)`，就代表該列只能儲存 point 形狀的地理位置資訊。

#### 插入資料

向 Tag `any_shape` 的 `geo` 列插入資料：

```
INSERT VERTEX any_shape(geo) VALUES "101":(ST_GeogFromText("POINT(120.12 30.16)"));
INSERT VERTEX any_shape(geo) VALUES "102":(ST_GeogFromText("LINESTRING(3 8, 4.7 73.23)"));
INSERT VERTEX any_shape(geo) VALUES "103":(ST_GeogFromText("POLYGON((75.3 45.4, 112.5 53.6, 122.7 25.5, 93.9 28.6, 75.3 45.4))"));
```

向 Tag `only_point` 的 `geo` 列插入資料：

```
INSERT VERTEX only_point(geo) VALUES "201":(ST_Point(120.12，30.16)"));;
```

向 Tag `only_linestring` 的 `geo` 插入資料：

```
INSERT VERTEX only_linestring(geo) VALUES "302":(ST_GeogFromText("LINESTRING(3 8, 4.7 73.23)"));
```

向 Tag `only_polygon`的 `geo` 列插入資料：

```
INSERT VERTEX only_polygon(geo) VALUES "403":(ST_GeogFromText("POLYGON((75.3 45.4, 112.5 53.6, 122.7 25.5, 93.9 28.6, 75.3 45.4))"));
```

當插入地理資料形狀不符合該列地理形狀要求時，會報錯無法插入:

```
(root@nebula) [geo]> INSERT VERTEX only_polygon(geo) VALUES "404":(ST_GeogFromText("POINT((75.3 45.4))"));
[ERROR (-1005)]: Wrong value type: ST_GeogFromText("POINT((75.3 45.4))")
```

我們可以看到地理空間資料插入方法比較奇特，和 int、string、bool 等基本型別的插入很不一樣。

我們以 `ST_GeogFromText("POINT(120.12 30.16)")` 為例，ST_GeogFromText 是一個地理位置資訊解析函式，它接受一個 string 型別的 WKT（Well-Known Text）標準格式表示的地理位置資料：

`POINT(120.12 30.16)` 代表一個東經 120°12′，北緯 30°16′ 的地理位置點。ST_GeogFromText 函式會從 wkt 引數中解析並構造一個 geography 資料物件，然後 `INSERT` 語句會將其以 WKB（Well-Known Binary）標準儲存在 Nebula 中。

### Geospatial functions -- 地理空間函式

Nebula 支援的地理空間函式可以分為以下幾大類:

- 建構函式
  * ST_Point(longitude, latitude)，根據一對經緯度構造一個 geography point 物件
- 解析函式
  * ST_GeogFromText(wkt_string)，從 wkt 文字中解析 geography 物件
  * ST_GeogFromWKB(wkb_string)，從 wkb 文字中解析 geography 物件 # 尚未正式支援，因為 Nebula還未支援二進位制字串
- 格式設定函式
  * ST_AsText(geogrpahy)，將 geogrpahy 物件以 wkt 文字格式輸出
  * ST_AsBinary(geography)，將 geography 物件以 wkb 文字格式輸出 # 尚未正式支援，因為 Nebula 還未支援二進位制字串
- 轉換函式
  * ST_Centroid(geography)，計算 geography 物件的重心，重心是一個 geography point 物件
- 謂詞函式
  * ST_Intersects(geography_1, geography_2)，判斷兩個 geography 物件是否相交
  * ST_Covers(geography_1, geography_2)，判斷第一個 geography 物件是否完全覆蓋第二個
  * ST_CoveredBy(geography_1, geography_2)，ST_Covers 的反義詞
  * ST_DWithin(geography_1, geography_2, distance_in_meters)，判斷兩個 geography 物件的最短距離是否小於給定距離
- 度量函式
  * ST_Distance(geography_1, geography_2)，計算兩個 geography 物件之間的距離

這些函式介面遵循 OpenGIS Simple Feature Access 以及 ISO SQL/MM 標準，具體用法參見[Nebula 文件](https://docs.nebula-graph.com.cn/2.6.1/3.ngql-guide/6.functions-and-expressions/14.geo/)

### Geospatial index -- 地理空間索引

#### 什麼是地理空間索引?

地理空間索引用於基於空間謂詞函式的的地理形狀的快速過濾，如：ST_Intersects、ST_Covers 等。

Nebula 使用[Google S2庫](https://s2geometry.io/)做空間索引。

S2 庫將地球表面投影到一個外切的正方體上，然後對正方體的每一個正方形表面遞迴地進行 n 次四等，最後使用一條空間填充曲線--[希爾伯特曲線](https://en.wikipedia.org/wiki/Hilbert_curve)去連線這些小正方格子的中心。

當 n 無窮大時，這條希爾伯特曲線就幾乎填滿了正方形。

S2 庫使用的是 30 階的希爾伯特曲線。

[![oPuZvt.png](https://z3.ax1x.com/2021/11/24/oPuZvt.png)](https://imgtu.com/i/oPuZvt)

如下圖, 是用希爾伯特曲線填充地地球表面的示意圖：

[![oPuPED.png](https://z3.ax1x.com/2021/11/24/oPuPED.png)](https://imgtu.com/i/oPuPED)

可以看到，地球表面最終被這些希爾伯特曲線劃分成了一個個單元格。對於地球表面的任意地理形狀，比如一個城市、一條河流、一個人的位置我們都可以用若干個這樣的格子去完全覆蓋住這個地理形狀。

每個格子都有一個唯一的 int64 的 CellID 來標識。因此，地理物件的空間索引就是構建完全覆蓋該地理形狀的 S2 格子的集合。

當構建地理空間物件的索引時，會構造一個完全覆蓋被索引物件的不同 S2 單元格的集合。基於空間謂詞函式的索引查詢透過查詢覆蓋所查詢物件的 S2 單元格的集合與覆蓋被索引物件的 S2 單元格之間的交集，來快速過濾掉大量不相關的地理物件。

#### 建立 geography 索引

```
CREATE TAG any_shape_geo_index on any_shape(geo)
```

對於形狀為 point 的地理資料，可以用一個 level 為 30 的 S2 單元格來表示它，因此一個 point 對應一個索引條目；對於形狀為 linestring 和 polygon 的地理資料，我們使用多個不同 level 的 S2 單元格來覆蓋，因此會對應多個索引條目；

空間索引會用來加速所有 geo 謂詞的查詢速度，比如對於如下語句

```
LOOKUP ON any_shape WHERE ST_Intersects(any_shape.geo, ST_GeogFromText("LINESTRING(3 8, 4.7 73.23)"));
```

當 any_shape 的 geo 列上沒有空間索引時，該語句會先將 any_shape 的所有資料讀到記憶體，然後用來計算是否和點(3.0, 8.0)相交，這個計算的開銷一般是比較昂貴的。當 any_shape 的資料量較大時，計算開銷將難以接受。

而當 any_shape 的 geo 列有空間索引時，該語句會首先用空間索引過濾掉絕大部分和該線絕對不相交的資料，最終讀到記憶體的還是會有部分可能相交的，因此還需要進行一次計算。這樣空間索引就以很小的代價快速過濾掉了大部分不可能相交的資料，最終進行精確過濾的只有少部分，極大的降低了計算開銷。

---

交流圖資料庫技術？加入 Nebula 交流群請先[填寫下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手會拉你進群~~

Geospatial Data 在 Nebula Graph 中的實踐

相關文章