更新时间:2025-07-18 GMT+08:00
分享

创建collection

功能介绍

在知识仓实例下创建collection。

URI

POST /v1/collections/create

请求参数

表1 请求Body参数

参数

是否必选

参数类型

描述

store_name

String

参数解释:

知识仓实例名称,region内唯一。

约束限制:

长度范围为3到63个字符,支持小写字母、数字、中划线(-),第一个字符只能够是小写字母,中划线(-)不得出现在字符串末尾。

取值范围:

不涉及

默认取值:

不涉及

collection_name

String

参数解释:

collection名称。

约束限制:

可包含数字、字母和下划线 ()。资源名称必须以字母或下划线 () 开头。最大长度支持255。

取值范围:

不涉及。

默认取值:

不涉及。

primary_field

primary_field object

参数解释:

主键字段。

约束限制:

不涉及。

fields

Array of field objects

参数解释:

集合中通用字段,创建列的schema。

约束限制:

不涉及。

description

String

参数解释:

指定 Collection 的描述信息。

约束限制:

有效长度0-255字节。

取值范围:

不涉及。

默认取值:

不涉及。

index_params

Array of index_params objects

参数解释:

索引的配置信息。

约束限制:

不涉及。

params

Map<String,Object>

参数解释:

collection常用参数。

约束限制:

shards_num: 默认2,取值范围[1, 16]

partitions_num: 默认4,取值范围[1, 1024],若所有field的partition_key为false,则partitions_num固定为1。

max_length: 默认256,取值范围[1, 65535],当primary_field.type为String时,指示String的最大长度。

表2 primary_field

参数

是否必选

参数类型

描述

name

String

参数解释:

指定主键名。

约束限制:

不涉及。

取值范围:

不涉及。

默认取值:

不涉及。

type

String

参数解释:

主键列的数据类型。

约束限制:

不涉及。

取值范围:

"String",“Int64”。

默认取值:

不涉及。

表3 field

参数

是否必选

参数类型

描述

field_name

String

参数解释:

要在集合中创建的字段名称。

约束限制:

不涉及。

取值范围:

不涉及。

默认取值:

不涉及。

data_type

String

参数解释:

字段的数据类型。

约束限制:

不涉及。

取值范围:

“Bool”,“Int8”,“Int16”,“Int32”,“Int64”,“Float”,“String”,“Array”,“JSON”,"FloatVector", "SparseFloatVector"。

默认取值:

不涉及。

element_data_type

String

参数解释:

数组内部的数据类型。

约束限制:

在data_type是Array时生效。

取值范围:

“Bool”,“Int8”,“Int16”,“Int32”,“Int64”,“Float”,“String”。

默认取值:

不涉及。

element_type_params

Map<String,Object>

参数解释:

每个field列的参数。

约束限制:

如果field为FloatVector类型向量字段,则必须设定维度参数dim;

如果field为String类型字段或Array 元素类型为String类型,则可设定字段值最大长度max_length;

如果field为Array类型字段,则可设定数组最大容量max_capacity。

取值范围:

如果field为FloatVector类型向量字段时,参数dim的有效取值范围是[2-32768];

如果field为String类型字段或Array 元素类型为String类型, 参数max_length的有效取值范围是[1-65535];

如果field为Array类型字段,参数max_capacity的有效取值范围是[1-32768]

默认取值:

如果field为String类型字段或Array 元素类型为String类型, 参数max_length的默认值是256

如果field为Array类型字段,参数max_capacity的默认值是32。

partition_key

Boolean

参数解释:

是否将这个filed列设置为分区键。

约束限制:

1.只能在数据类型为String与Int64的field列上设置分区键;

2.最多只能设置1个field为分区键。

取值范围:

true,false。

默认取值:

false。

表4 index_params

参数

是否必选

参数类型

描述

index_name

String

参数解释:

创建的索引名称,collection内唯一。

约束限制:

长度范围为1到255个字符,支持字母、数字、中划线(-)和下划线(),大小写敏感。第一个字符只能够是下划线()和字母,中划线(-)不得出现在字符串末尾。

取值范围:

不涉及。

默认取值:

不涉及。

field_name

String

参数解释:

要创建索引的目标字段名称。

约束限制:

  • 长度范围为1到255个字符,支持字母、数字、中划线(-)和下划线(),大小写敏感。第一个字符只能够是下划线()和字母,中划线(-)不得出现在字符串末尾。

  • field_name必须是collection field schema中存在的字段。

取值范围:

不涉及。

默认取值:

不涉及。

params

Map<String,Object>

参数解释:

创建的索引的参数配置。

可以设置的参数:

  • metric_type:向量度量方式,只有向量索引需要配置。

  • index_type:创建的索引类型。

  • params:对应索引类型的配置参数。

    1. HNSW索引类型参数:

      • M:节点的最大度。

      • efConstruction:构建索引时每个节点邻居数。

    2. HANNS索引相关参数:

      • max_degree:节点的最大度数。较大的值提供更高的召回率但增加索引的大小和构建时间。

      • search_list_size:候选列表的大小。较大的值增加构建索引的时间但提供更高的召回率。

      • encoding_type: SQ/PQ,默认SQ。

      • pq_code_budget_gb_ratio:PQ 码的大小限制。较大的值提供更高的召回率但增加内存使用量,仅当encoding_type为PQ时生效。

      • beamwidth:每个搜索迭代的最大 IO 请求数与 CPU 数之间的比率,可用于提升索引性能。

    3. IVF_FLAT索引相关参数:

      • nlist:聚类的数量。

      • nprobe:查询聚类的数量。

约束限制:

不涉及。

取值范围:

  • metric_type:

    1. 稠密向量支持度量方式:"L2"和"COSINE"。

    2. 稀疏向量支持度量方式:"IP"。

  • index_type:

    1. 稠密向量支持索引类型:"HNSW"、"HANNS"和"IVF_FLAT"。

    2. 稀疏向量支持索引类型:"SPARSE_INVERTED_INDEX"和"SPARSE_WAND"。

    3. 标量字段支持索引类型:"IVF_FLAT"。

  • params:

    1. HNSW索引类型参数:

      • M:[2, 2048]

      • efConstruction:[1, int32_max]

    2. HANNS索引相关参数:

      • max_degree:[1, 512]

      • search_list_size:[1, int32_max]

      • encoding_type: SQ/PQ

      • pq_code_budget_gb_ratio:[0.0, 0.25]

      • beamwidth:[1, 16]

    3. IVF_FLAT索引相关参数:

      • nlist:[1, 65536]

      • nprobe:[1, nlist]

默认值:

  • metric_type:

    1. 稠密向量:"L2"。

    2. 稀疏向量:"IP"。

    3. 标量:无须配置

  • index_type:

    1. 稠密向量:"HANNS"。

    2. 稀疏向量:"SPARSE_INVERTED_INDEX"。

    3. 标量:"IVF_FLAT"。

  • params:对应索引类型的配置参数。

    1. HNSW索引类型参数:

      • M:16。

      • efConstruction:200。

    2. HANNS索引相关参数:

      • max_degree:56。

      • search_list_size:100。

      • encoding_type: 默认SQ。

      • pq_code_budget_gb_ratio:0.125。

      • beamwidth:0.0

    3. IVF_FLAT索引相关参数:

      • nlist:128

      • nprobe:8

响应参数

状态码:200

表5 响应Body参数

参数

参数类型

描述

code

String

参数解释:

返回码。参见错误码章节。

约束限制:

不涉及。

取值范围:

不涉及。

默认取值:

不涉及。

message

String

参数解释:

描述信息。

约束限制:

不涉及。

取值范围:

不涉及。

默认取值:

不涉及。

状态码:400

表6 响应Body参数

参数

参数类型

描述

code

String

参数解释:

返回码。参见错误码章节。

约束限制:

不涉及。

取值范围:

不涉及。

默认取值:

不涉及。

message

String

参数解释:

描述信息。

约束限制:

不涉及。

取值范围:

不涉及。

默认取值:

不涉及。

请求示例

/v1/collections/create

{
  "store_name" : "test-storename",
  "collection_name" : "test-collection",
  "primary_field" : {
    "name" : "pk",
    "type" : "Int64"
  },
  "fields" : [ {
    "field_name" : "vector",
    "data_type" : "FloatVector",
    "element_type_params" : {
      "dim" : 3
    }
  }, {
    "field_name" : "scalar",
    "data_type" : "String"
  } ],
  "index_params" : [ {
    "index_name" : "vector_index",
    "field_name" : "vector"
  } ]
}

响应示例

状态码:200

创建collection成功

{
  "code" : "LMS.00000000",
  "message" : "create collection success"
}

状态码:400

Bad Request

{
  "code" : "LMS.00001001",
  "message" : "ErrInvalidParameter: The input parameter is incorrect."
}

状态码

状态码

描述

200

创建collection成功

400

Bad Request

错误码

请参见错误码

相关文档