表空间操作¶

http://master_server代表master服务，$db_name是创建的库名, $space_name是创建的表空间名

创建表空间¶

curl -XPUT -H "content-type: application/json" -d'
{
    "name": "space1",
    "partition_num": 1,
    "replica_num": 1,
    "engine": {
        "index_size": 70000,
        "id_type": "String",
        "retrieval_type": "IVFPQ",
        "retrieval_param": {
            "metric_type": "InnerProduct",
            "ncentroids": 2048,
            "nsubvector": 32
        }
    },
    "properties": {
        "field1": {
            "type": "keyword"
        },
        "field2": {
            "type": "integer"
        },
        "field3": {
            "type": "float",
            "index": true
        },
        "field4": {
            "type": "string",
            "array": true,
            "index": true
        },
        "field5": {
            "type": "integer",
            "index": true
        },
        "field6": {
            "type": "vector",
            "dimension": 128
        },
        "field7": {
            "type": "vector",
            "dimension": 256,
            "format": "normalization",
            "store_type": "RocksDB",
            "store_param": {
                "cache_size": 2048,
                "compress": {"rate":16}
            }
        }
    }
}
' http://master_server/space/$db_name/_create

参数说明:

字段标识	字段含义	类型	是否必填	备注
name	空间名称	string	是
partition_num	分片数量	int	是
replica_num	副本数量	int	是
engine	引擎配置	json	是	引擎配置
properties	空间配置	json	是	定义表字段及类型

1、name 不能为空，不能以数字或下划线开头，尽量不使用特殊字符等。

2、partition_num 指定表空间数据分片数量，不同的分片可分布在不同的机器，来避免单台机器的资源限制。

3、replica_num 副本数量，建议设置成3，表示每个分片数据有两个备份，保证数据高可用。

engine配置:

字段标识	字段含义	类型	是否必填	备注
index_size	分片索引阀值	int	否	默认100000
id_type	唯一主键类型	string	否
retrieval_type	检索模型	string	是
retrieval_param	检索模型参数配置	json	否

1、index_size 指定每个分片的记录数量达到多少开始创建索引，默认值100000。

2、id_type 指定唯一记录主键类型，支持String和Long(定义为Long可节省内存占用)。

3、retrieval_type 检索模型，目前支持六种类型，IVFPQ，HNSW，GPU，IVFFLAT，BINARYIVF，FLAT，不同的检索模型需要的参数配置及默认值如下:

IVFPQ:

现在IVFPQ可以与HNSW和OPQ组合使用。如果要使用HNSW，建议将ncentroids设置为较大的值。对于HNSW的组合，现在解除了对训练数据量的限制，您可以使用不超过ncentroids * 256的数据进行训练。而在组合使用OPQ时，训练占用的内存为 2 * indexing_size * dimension * sizeof（float），因此对于HNSW和OPQ的组合使用，训练将占用更多的内存并花费较长时间，故要特别注意indexing_size的设置，防止使用的太多内存。

index_size：对于IVFPQ，在建立索引之前需要训练，因此您应该将index_size设置为合适的值，例如100000，如果与HNSW结合使用，index_size可以是 ncentroids * 39 到 ncentroids * 256 之间的值。

如何组合使用HNSW和OPQ由retrieve_param控制。如果同时设置HNSW和OPQ，则将使用OPQ + IVF + HNSW + PQ，建议将OPQ的nsubvector设置为与PQ的nsubvector相同。如果只想使用IVF + HNSW + PQ，则只需要设置HNSW。如果您只想使用IVFPQ，则无需在retrieval_param中设置HNSW或OPQ。

字段标识	字段含义	类型	是否必填	备注
metric_type	计算方式	string	是	L2或者InnerProduct
ncentroids	聚类中心数量	int	是	默认2048
nsubvector	PQ拆分子向量大小	int	是	默认64
bucket_init_size	倒排链表（IVF）初始化的大小	int	否	默认1000
bucket_max_size	倒排链表（IVF）最大容量	int	否	默认1280000

"retrieval_type": "IVFPQ",
"retrieval_param": {
    "metric_type": "InnerProduct",
    "ncentroids": 2048,
    "nsubvector": 64
}

您可以这样设置hnsw或opq：

"index_size": 2600000,
"id_type": "string",
"retrieval_type": "IVFPQ",
"retrieval_param": {
    "metric_type": "InnerProduct",
    "ncentroids": 65536,
    "nsubvector": 64,
    "hnsw" : {
        "nlinks": 32,
        "efConstruction": 200,
        "efSearch": 64
    },
    "opq": {
        "nsubvector": 64
    }
}

HNSW:

字段标识	字段含义	类型	是否必填	备注
metric_type	计算方式	string	是	L2或者InnerProduct
nlinks	节点邻居数量	int	是	默认32
efConstruction	构图时寻找节点邻居过程中在图中遍历的深度	int	是	默认40

"retrieval_type": "HNSW",
"retrieval_param": {
    "metric_type": "InnerProduct",
    "nlinks": 32,
    "efConstruction": 40
}

注意: 1、向量存储只支持MemoryOnly
      2、创建索引不需要训练，index_size 值大于0均可

GPU（针对GPU编译版本）:

字段标识	字段含义	类型	是否必填	备注
metric_type	计算方式	string	是	L2或者InnerProduct
ncentroids	聚类中心数量	int	是	默认2048
nsubvector	PQ拆分子向量大小	int	是	默认64

"retrieval_type": "GPU",
"retrieval_param": {
    "metric_type": "InnerProduct",
    "ncentroids": 2048,
    "nsubvector": 64
}

SCANN（针对SCANN编译版本）:

字段标识	字段含义	类型	是否必填	备注
metric_type	计算方式	string	是	L2或者InnerProduct
ncentroids	聚类中心数量	int	是	默认2048
nsubvector	PQ拆分子向量大小	int	是	默认128, 量化为4bit，建议使用ivfpq模型nsubvector的2倍
thread_num	线程池线程数	int	否	可以不使用，如果使用建议为cpu核数

"retrieval_type": "VEARCH",
"retrieval_param": {
    "metric_type": "InnerProduct",
    "ncentroids": 2048,
    "nsubvector": 64,
    "thread_num": 8
}

注意: 1、目前scann模型，索引不支持dump/load；不支持update。

IVFFLAT:

字段标识	字段含义	类型	是否必填	备注
metric_type	计算方式	string	是	L2或者InnerProduct
ncentroids	聚类中心数量	int	是	默认2048

 "retrieval_type": "IVFFLAT",
 "retrieval_param": {
     "metric_type": "InnerProduct",
     "ncentroids": 2048
 }

注意: 1、向量存储方式只支持RocksDB

BINARYIVF:

字段标识	字段含义	类型	是否必填	备注
ncentroids	聚类中心数量	int	是	默认2048

"retrieval_type": "BINARYIVF",
"retrieval_param": {
    "ncentroids": 2048
}

注意: 1、向量长度是8的倍数

properties配置:

1、表空间结构定义字段支持的类型(即type的值)有6种: string(keyword)，integer， long， float，double， vector。

2、string类型的字段支持index、array属性，index定义是否创建索引，array指定是否允许多个值，创建索引后支持term过滤。

3、integer，long，float，double类型的字段支持index属性，index设为true创建索引后支持数值范围过滤查询(range)。

4、vector 类型字段为特征字段，一个表空间中支持多个特征字段，vector类型的字段支持的属性如下:

字段标识	字段含义	类型	是否必填	备注
dimension	特征维数	int	是
format	归一化处理	string	否	设置为normalization对添加的特征向量归一化处理
store_type	特征存储类型	string	否	支持MemoryOnly、Mmap和RocksDB, 默认MemoryOnly
store_param	存储参数设置	json	否	针对不同store_type的存储参数
model_id	特征插件模型	string	否	使用特征插件服务时指定

5、dimension 定义type是vector的字段，指定特征维数大小。

6、store_type 特征向量存储类型，有以下三个选项：

“MemoryOnly”：原始向量都存储在内存中，存储数量的多少受内存限制，适用于数据量不大（千万级），对性能要求高的场景

“RocksDB”：原始向量存储在RockDB（磁盘）中，存储数量受磁盘大小限制，适用单机数据量巨大（亿级以上），对性能要求不高的场景

“Mmap”：原始向量存储在磁盘文件中，使用cache提高性能，存储数量受磁盘大小限制，适用单机数据量巨大（亿级以上），对性能要求不高的场景

7、store_param 针对不同store_type的存储参数，其包含以下两个子参数。

cache_size: 数值类型，单位是M bytes，默认1024。store_type=”RocksDB”时，表示RocksDB的读缓冲大小，值越大读向量的性能越好，一般设置1024、2048、4096和6144即可；store_type=”Mmap”时，表示读缓冲的大小，一般512、1024、2048和4096即可，可根据实际应用场景设置大小；store_type=”MemoryOnly”，cache_size不生效。

compress: 设置为{“rate”:16} 压缩50%；默认不压缩。

标量索引

Gamma引擎支持标量索引，提供对标量数据的过滤功能，开启方式参考“properties配置”中的第2条和第3条，检索方式参考“查询”中的“filter json结构说明”

查看表空间¶

curl -XGET http://master_server/space/$db_name/$space_name

删除表空间¶

curl -XDELETE http://master_server/space/$db_name/$space_name

修改cache大小¶

curl -H "content-type: application/json" -XPOST -d'
{
    "cache_models": [
        {
            "name": "table",
            "cache_size": 1024,
        },
        {
            "name": "string",
            "cache_size": 1024,
        },
        {
            "name": "field7",
            "cache_size": 1024,
        }
    ]
}
' http://master_server/config/$db_name/$space_name

1、table cache size：表示所有定长的标量字段（integer，long，float，double）使用cache的大小，默认为512M，单位为M bytes。

2、string cache size：表示所有变长的标量字段（string）使用cache的大小，默认为512M，单位为M bytes。

3、对于向量字段只支持store_type为Mmap的进行修改cache size。

查看cache大小¶

curl -XGET http://master_server/config/$db_name/$space_name

1、对于向量字段只支持store_type为Mmap的查看cache size。