Source: https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/ddl/index/create-geo/
Documentation version: v5.3.2

# CREATE SPATIAL INDEX

`CREATE SPATIAL INDEX`语句用于为特定图创建空间索引。

可选择以下任意方法来指定图：

- 在本语句前添加 [USE 子句](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/dql/clauses/use-graph/)来设定工作图。
- 提前使用 [SESSION SET](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/sessions/set/) 设置当前会话的图。

若两种方法均使用，则以 USE 子句中的指定为准。若均未使用，则报错。

您可以基于单个点类型或边类型的单个地理空间类型属性创建空间索引，从而加速空间范围、邻近、交集等空间相关的查询。

若要创建其他类型的索引，请参见 [CREATE NORMAL INDEX](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/ddl/index/create/)、[CREATE VECTOR INDEX](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/ddl/index/create-vector/) 和 [CREATE FULLTEXT INDEX](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/ddl/index/create-fulltext/)。

## 空间索引实现原理

在悦数图数据库开发版中，空间索引的具体实现原理如下：

1. 划分网格层级：将地球的整体地理空间投影到球面上，并分解为多个层级的网格。每个后续层级都会进一步分解其上一级，因此上一级别的每个单元都包含下一级别的整个网格。
2. 确定网格单元的大小和数量：网格层级越高，每个网格单元的覆盖面积越小，因此需要更多的单元来覆盖同一空间对象。
3. 构建索引：系统计算空间对象覆盖的网格单元，并在索引中记录地理空间对象与网格单元的对应关系。
4. 检索数据：系统只需检索与目标地理空间对象重叠的网格单元，快速定位目标空间对象。

下图示例将一个空间分解成级别为`4`的`4x4`网格，总共产生`65,536`个第四级单元。

[![geo index](https://docs-cdn.nebula-graph.com.cn/figures/5.0/spatial_index_20250716.png)](https://docs-cdn.nebula-graph.com.cn/figures/5.0/spatial_index_20250716.png)

您可以参考 [S2 Cell Statistics](https://s2geometry.io/resources/s2cell_statistics.html) 中的`level`（网格层级）和`average area`（每个单元的大小）两列，配置参数 [`s2_max_level`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/ddl/index/create-geo/#s2_max_level) 和 [`s2_max_cells`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/ddl/index/create-geo/#s2_max_cells) 的值，让空间索引更加适配具体使用场景。

Note

对非默认 Schema 或其中的对象执行操作时，用户既要通过隐式访问规则或显式`USAGE`授权获得该 Schema 的访问权，也要具备目标操作所需的权限。Schema 访问校验和目标操作所需的权限校验相互独立，满足其中一项不能替代另一项。Schema 访问控制不适用于临时图、内置 Procedure 和内置 Function。更多信息，请参见 [Schema 访问控制](https://dev-docs.yueshu.com.cn/v5.3.2/server-admin/authorization/schema-access-control/)。

## 前提条件

- 图已创建。更多信息，请参见 [CREATE GRAPH](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/ddl/graph/create/)。
- 若要创建空间索引，必须是图的所有者，或具备在图上执行`INDEX`操作的权限，或具备在当前 Schema 执行`CREATE INDEX`操作的权限。更多信息，请参见[角色与权限](https://dev-docs.yueshu.com.cn/v5.3.2/server-admin/authorization/)。

## 语法

语法图源码

 create_spatial_index_statement spatial_index_configuration  

````
create_spatial_index_statement ::=
    'CREATE' 'SPATIAL' 'INDEX' ('IF NOT EXISTS')? index_name 'ON' ( ( ('NODE' | 'VERTEX') 'TYPE'? node_type_name) | ( ('EDGE'|'RELATIONSHIP') 'TYPE'? edge_type_name) ) '(' spatial_index_configuration ')'

spatial_index_configuration ::=
    'geography_property_name' ',' 's2_max_level' '=' int_value ',' 's2_max_cells' '=' int_value             

````

## 参数

### `IF NOT EXISTS`

该子句会检查是否已存在同名的索引。若已存在，则不会创建索引，也不会抛出异常。

若未指定该子句，且已存在同名的索引，则会抛出异常。

### `index_name`

待创建的空间索引的名称。该名称为常规标识符，在同一个图的所有类型的索引中，索引名称必须唯一。

有关标识符的详细信息，请参见[标识符命名规则](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/overview/keywords-identifiers/#_3)。

### `node_type_name`

待创建空间索引的点类型的名称。该点类型必须至少有一个值类型为`GEOGRAPHY`的属性。

### `edge_type_name`

待创建空间索引的边类型的名称。该边类型必须至少有一个值类型为`GEOGRAPHY`的属性。

### `spatial_index_configuration`

创建空间索引所基于的属性及索引配置，每次仅支持为一个属性创建空间索引。

#### `geography_property_name`

待创建空间索引的属性名称，该属性的值类型必须是`GEOGRAPHY`类型。

#### `s2_max_level`

网格可以划分的最大层级。层级越大，网格划分越细，单元越小，但索引体积和维护成本也越大。取值范围为`(0,30]`。

#### `s2_max_cells`

一个地理空间对象可以覆盖的最多网格单元数。数值越低，索引记录的数量越少，进而降低存储需求和查询复杂度，但会影响索引精度。取值范围为`(0,256]`。

## 示例

以下示例基于[地理空间数据使用示例](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/geo-type/#_2)中创建的图`my_graph`。

### 在点类型上创建空间索引

````
USE my_graph CREATE SPATIAL INDEX IF NOT EXISTS idx_gnode_g ON NODE Person(any_geo, s2_max_level = 30, s2_max_cells = 8)

````

该示例在点类型`Person`上基于属性`any_geo`创建了一个名为`idx_gnode_g`的空间索引，最大层级为`30`，最多覆盖`8`个单元。

### 在边类型上创建空间索引

````
USE my_graph CREATE SPATIAL INDEX IF NOT EXISTS idx_gedge_g ON EDGE GEdge(company_location, s2_max_level = 30, s2_max_cells = 8)

````

该示例在边类型`GEdge`上基于属性`company_location`创建了一个名为`idx_gedge_g`的空间索引，最大层级为`30`，最多覆盖`8`个单元。