Source: https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/ddl/index/create-vector/ Documentation version: v5.3.2 # CREATE VECTOR INDEX `CREATE VECTOR 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 子句中的指定为准。若均未使用，则报错。 您可以基于单个点类型或边类型的单个属性创建向量索引，从而加速基于索引属性进行的近似最近邻（Approximate Nearest Neighbor，简称 ANN）的搜索查询。 若要创建其他类型的索引，请参见 [CREATE NORMAL INDEX](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/ddl/index/create/)、[CREATE SPATIAL INDEX](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/ddl/index/create-geo/) 和 [CREATE FULLTEXT INDEX](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/ddl/index/create-fulltext/)。 ## 向量索引实现原理 在创建向量索引后，会生成以下数据： - 描述向量索引的元数据。 - 存储在 RocksDB 中、将索引向量映射到其对应的点或边的键值对。 - 驻留在内存中用于加速 ANN 搜索的 ANN 索引。 Note 若有多个 Storage 服务在运行，会在每个 Storage 服务上创建并维护多个 ANN 索引。 - ANN 索引的可用性由 Raft 一致性算法保证。即便发生 Leader 更改，新 Leader 上的 ANN 索引也确保与前任上的索引一致。 - 每个 Storage 服务中所有 ANN 索引的最大内存用量由配置项`ann_index_memory_quota_in_kb`控制。若超出此配额，与向量索引相关的插入操作将导致错误。 为了确保 ANN 索引的数据完整性，以[预写日志记录（Write-ahead logging，简称 WAL）](https://en.wikipedia.org/wiki/Write-ahead_logging)的方式，保证对索引的更改只有在记录到日志后才会写入，也即在 WAL 记录持久化到磁盘后才会写入。 每个 ANN 索引对应两个持久化到磁盘的文件：WAL 文件（`.annwal`）和完整索引文件（`.annidx`）。对 ANN 索引的更改只有在记录到 WAL 文件后才会写入。当超出由配置项`ann_write_idx_file_threshold_of_log_num`指定的阈值后，WAL 文件中的记录将被汇总并写入完整索引文件，WAL 文件中对应的重复记录将被删除。 WAL 文件占用的磁盘空间大于完整索引文件，但在 I/O 效率方面优于后者。建议将该阈值设置为能平衡存储使用量和 I/O 效率的值。 WAL 文件和完整索引文件存储在 Storage 服务的配置项`data_path`指定的路径下。当发生系统崩溃时，WAL 文件和完整索引文件都是恢复 ANN 索引所必需的。 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_vector_index_statement ann_index_option ```` create_vector_index_statement ::= 'CREATE' 'VECTOR' 'INDEX' ('IF NOT EXISTS')? index_name 'ON' ( ( ('NODE' | 'VERTEX') 'TYPE'? node_type_name ) | ( ('EDGE'|'RELATIONSHIP') 'TYPE'? edge_type_name ) ) '::' property_name 'OPTIONS' '{' ann_index_option (',' ann_index_option)* '}' ann_index_option ::= 'DIM' ':' int_value | 'METRIC' ':' ( 'L2' | 'IP' ) | 'TYPE' ':' ( 'IVF' | 'HNSW' ) | 'NLIST' ':' int_value | 'TRAINSIZE' ':' int_value | 'MAXDEGREE' ':' int_value | 'EFCONSTRUCTION' ':' int_value | 'CAPACITY' ':' 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` 待创建向量索引的点类型的名称。该点类型必须至少有一个值类型为`VECTOR`的属性。 ### `edge_type_name` 待创建向量索引的边类型的名称。该边类型必须至少有一个值类型为`VECTOR`的属性。 ### `property_name` 待创建向量索引的点类型或边类型的属性名称。属性的值类型必须为`VECTOR`。更多信息，请参见[向量](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/vector-type/)。 ### `ann_index_option` 用于创建向量索引的选项，其中选项`DIM`为必选，其余选项均为可选。 #### `DIM` 待创建的向量索引的维度数，必须与创建索引的属性的维度数相同，该属性的值类型必须为`VECTOR`。 #### `METRIC` 用于计算向量索引中向量之间相似度的度量。可选值包括： - `L2`：使用欧几里得距离度量，即基于向量之间的欧几里得距离计算相似度。 - `IP`：使用内积度量，即基于向量之间的内积计算相似度。 此处指定的相似性度量决定了在执行 ANN 搜索时用于计算向量相似度的函数。更多信息，请参见[最近邻查询](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/dql/nearest-neighbor/)。 若未指定该选项，则默认值`L2`生效。 #### `TYPE` 用于创建向量索引的算法。可选值包括： - `IVF`：使用 [IVF（全称 Inverted File）](https://en.wikipedia.org/wiki/Inverted_index)算法创建索引。 - `HNSW`：使用 [HNSW（全称 Hierarchical Navigable Small World）](https://en.wikipedia.org/wiki/Hierarchical_navigable_small_world)算法创建索引。 若未指定该选项，则默认值`IVF`生效。 #### `NLIST` 构建 IVF 索引时创建的聚类数。每个聚类对应一个倒排列表，用于存储分配给该聚类的向量的引用。此选项仅在选项`TYPE`设置为`IVF`时生效。 该选项决定了 IVF 索引的粒度。取值越大，每个聚类中的平均向量数量越少，从而提高搜索速度，但会降低搜索的召回率。 若未指定该选项且`TYPE`设置为`IVF`，则默认值`8`生效。 #### `TRAINSIZE` 构建 IVF 索引时用于训练索引的向量数。此选项仅在选项`TYPE`设置为`IVF`时生效。 该选项决定了 IVF 索引的聚类质量。取值越大，扫描的向量越多，以找到每个向量的最佳聚类，从而提高搜索的召回率，但会增加训练时间。 若未指定该选项且`TYPE`设置为`IVF`，则默认值`3`生效。 #### `MAXDEGREE` 在 HNSW 图中每个点可以拥有的最大边数。此选项仅在选项`TYPE`设置为`HNSW`时生效。 该选项控制了 HNSW 图的稀疏度，以平衡搜索效率和召回率。取值越大，搜索结果越准确，但搜索速度越慢，内存消耗越大。 若未指定该选项且`TYPE`设置为`HNSW`，则默认值`8`生效。 #### `EFCONSTRUCTION` 构建 HNSW 图时使用的动态候选列表的大小，该列表大小决定了往图中插入新点时评估的邻居数量。此选项仅在选项`TYPE`设置为`HNSW`时生效。 该选项控制了 HNSW 图的质量。取值越大，对潜在邻居的探索越彻底，从而提高搜索的召回率，但会增加构建时间。 若未指定该选项且`TYPE`设置为`HNSW`，则默认值`16`生效。 #### `CAPACITY` 在 HNSW 索引中存储的元素数量上限。此选项仅在选项`TYPE`设置为`HNSW`时生效。 该选项决定了 HNSW 索引的内存使用量。若超出容量，HNSW 索引会自动调整大小，导致构建 HNSW 索引的开销增加。 若未指定该选项且`TYPE`设置为`HNSW`，则默认值`10000`生效。 ## 示例 以下示例基于 [CREATE GRAPH TYPE](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/ddl/graph-type/create/) 中创建的图类型`ann_test`。 ### 在一个点类型上创建 IVF 向量索引 ```` CREATE GRAPH IF NOT EXISTS ann_test_graph TYPED ann_test // Create a graph USE ann_test_graph CREATE VECTOR INDEX IF NOT EXISTS idx_node_vec1 ON NODE N1::vec1 OPTIONS { DIM: 3, METRIC: L2, TYPE: IVF, NLIST: 10, TRAINSIZE: 4 } ```` 该示例在点类型`N1`上基于属性`vec1`创建了一个名为`idx_node_vec1`的 IVF 向量索引。 ### 在一个边类型上创建 HNSW 向量索引 ```` CREATE GRAPH IF NOT EXISTS ann_test_graph TYPED ann_test // Create a graph USE ann_test_graph CREATE VECTOR INDEX IF NOT EXISTS idx_edge_vec2 ON EDGE E1::vec2 OPTIONS { DIM: 7, METRIC: IP, TYPE: HNSW, MAXDEGREE: 3, EFCONSTRUCTION: 6, CAPACITY: 500 } ```` 该示例在边类型`E1`上基于属性`vec2`创建了一个名为`idx_edge_vec2`的 HNSW 向量索引。