You need to enable JavaScript to run this app.
导航

list

最近更新时间2023.12.27 15:44:56

首次发布时间2023.11.03 15:00:09

概述

/index/list 接口用于查询和数据集 Collection 关联的索引 Index列表。

请求接口

说明

请求向量数据库 VikingDB 的 OpenAPI 接口时,需要构造签名进行鉴权,详细的 OpenAPI 签名调用方法请参见 API签名调用指南

URI

/api/index/list

统一资源标识符

请求方法

GET

客户端对向量数据库服务器请求的操作类型

请求头

Content-Type: application/json

请求消息类型

Authorization: HMAC-SHA256 ***

鉴权

请求参数

参数

类型

是否必选

参数说明

collection_name

string

指定要查询索引所属的 Collection 名称。

  • 只能使用英文字母、数字、下划线_,并以英文字母开头,不能为空。
  • 长度要求:[1, 128]。
  • Collection 名称不能重复。

响应消息

参数

参数说明

code

状态码

message

返回信息

request_id

标识每个请求的唯一标识符

data

索引信息,每个索引的详细信息见 Index 参数说明。

Index 参数

参数

子参数

类型

参数说明

collection_name

string

显示创建索引所属的 Collection 名称。

index_name

string

显示创建的索引 Index 名称。

cpu_quota

int

显示索引线上检索消耗的 CPU 配额。

description

string

显示索引的自定义描述。

shard_count

int

分片数。索引分片是指在大规模数据量场景下,可以把索引数据切分成多个小的索引块,分发到同一个集群不同节点进行管理,每个节点负责存储和处理一部分数据,可以将查询负载分散到不同的节点上,并发的进行处理。当一个节点发生故障时,系统可以自动将其上的分片数据迁移到其他的正常节点上,保证稳定性,以实现数据的水平扩展和高性能的读写操作。

  • 取值范围:[1, 256]。

partition_by

string

partition_by 用于划分子索引 partition 。根据某个标量字段可以将数据集划分成不同的子数据集,不同的子数据集构建为不同的子索引,实现混合检索时在子索引内检索并减少过滤,从而提升检索性能。

  • partition_by 对应字段名称 field_name,支持 field 类型为 int64、list<int64>、string、list<string>。partition 对应 field 的字段值。
  • partition_by 划分的子索引 partition 数量建议不超过1000个。
  • partition_by 参数未设置时,则子索引 partition 默认为 “default”。
  • 适用场景:适用于将数据集划分为多个子数据集,在某个子数据集/子索引内部检索等检索模式固定的场景。比如,根据国家ID将数据集拆分,针对某个国家ID的子索引检索场景,无需对国家ID进行过滤,提升检索性能。

vector_index

index_type

string

显示向量索引类型。取值如下:

  • hnsw:全称是 Hierarchical Navigable Small World,一种用于在高维空间中采用 ANN 搜索的数据结构和算法,是基于图的索引。HNSW通过构建多层网络减少搜索过程中需要访问的节点数量,实现快速高效地搜索最近邻,适合对搜索效率要求较高的场景。
    hnsw的相关参数包含 quant、distance、hnsw_m、hnsw_cef、hnsw_sef
  • flat:暴力索引,搜索时遍历整个向量数据库的所有向量与目标向量进行距离计算和比较,查询速度较慢,但是 flat 能提供100%的检索召回率,适用于向量候选集较少,且需要100%检索召回率的场景。
    flat 的相关参数包含 quant、distance

distance

string

显示距离类型,衡量向量之间距离的算法。取值如下:

  • ip:全称是 Inner Product,内积,该算法基于向量的内积,即两个元素的对应元素相乘并求和的结果计算相似度,内积值越大相似度越高。
  • l2:欧几里得距离,它计算两个向量的欧几里得空间距离,欧式距离越小相似度越高。
  • cosine:余弦相似度(Cosine Similarity),也称为余弦距离(Cosine Distance),用于计算两个高维向量的夹角余弦值从而衡量向量相似度,夹角余弦值越小表示两向量的夹角越大,则两个向量差异越大。
    当 distance=cosine 时,默认对向量做归一化处理。

quant

string

显示量化方式。量化方式是索引中对向量的压缩方式,可以降低向量间相似性计算的复杂度。基于向量的高维度和大规模特点,采用向量量化可以有效减少向量的存储和计算成本。取值如下:

  • int8:将4字节的 float 压缩为单个字节,以获取内存和计算延迟的收益,会造成微小的损失精度,比如 cosine 距离会出现大于1的分值。
  • float:全精度,未做压缩量化。

hnsw_m

数值

hnsw 索引参数,表示邻居节点个数。

  • 当 index_type 配置为 hnsw 时可选配置。

hnsw_cef

数值

hnsw 索引参数,表示构建图时搜索邻居节点的广度。

  • 当 index_type 配置为 hnsw 时可选配置。

hnsw_sef

数值

hnsw 索引参数,表示线上检索的搜索广度。

  • 当 index_type 配置为 hnsw 时可选配置。

enum_index

array

根据 scalar_index 推断出可用于枚举检索的标量字段名称,非 float 字段可用于枚举检索。

range_index

array

根据 scalar_index 推断出可用于范围检索的标量字段名称,float、int64 字段可用于范围检索。

scalar_index

field_name

string

标量字段名称。

field_type

string

标量字段类型。

status

tring

索引状态。取值如下:

  • init:初始化,可能在构建或加载中。
  • ready:已上线,可以正式提供服务。

index_cost

cpu_core

int

索引占用的 CPU 核数。

mem_gb

string

索引所占内存大小。

create_time

string

索引创建时间。

update_time

string

索引更新时间。

update_person

string

索引更新人。

状态码说明

状态码

http状态码

返回信息

状态码说明

0

200

list index success

查询指定 Collection 的索引列表成功。

1000005

400

collection not exist

指定的 Collection 不存在。

1000003

400

invalid request:%s

非法参数:

  • 缺失必选参数。

1000001

401

unauthorized

请求头中缺乏鉴权信息。

1000002

403

no permission

权限不足。

完整示例

请求消息

curl -i -X GET \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  http://***/api/index/list \
  -d '{
    "collection_name": "test_name"
}'

响应消息

执行成功返回:

HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
 
{
    "code":0,
    "message":"success",
    "request_id":"021695029757920fd001de6666600000000000000000002569b8f",
    "data": [
        {
            "index_name": "index_test_1",
            "status": "ready",
            "description": "test for index",
            "cpu_quota": 10,
            "vector_index": {
                "index_type": "hnsw",
                "distance": l2,
                "quant": "float"
            },
        "enum_index": ["city", "date"],
        "range_index": ["score"],
        "scalar_index": [
            {
                "field_name":"score",
                "field_type":"float32"
            },
            {
                "field_name":"city",
                "field_type":"string"
            },
            {
                "field_name":"date",
                "field_type":"string"
            }
        ],
        "create_time": "2023-11-21 12:22:57",
        "update_time": "2023-11-22 11:15:45",
        "update_person": "zhangsan",
        },
        {
            "index_name": "index_test_2",
            "status": "init",
            "description": "test for index",
            "cpu_quota": 10,
            "vector_index": {
                "index_type": "hnsw",
                "distance": l2,
                "quant": "float"
            },
        "enum_index": ["city", "date"],
        "range_index": ["score"],
        "scalar_index": [
            {
                "field_name":"score",
                "field_type":"float32"
            },
            {
                "field_name":"city",
                "field_type":"string"
            },
            {
                "field_name":"date",
                "field_type":"string"
            }
        ]
        "create_time": "2023-11-21 10:22:57",
        "update_time": "2023-11-22 12:15:45",
        "update_person": "zhangsan"
        }   
    ] 
}

执行失败返回:

HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
 
{"code":1000005,"message":"collection not exist","request_id":"021695029757920fd001de6666600000000000000000002569b8f"}