# 创建collection - CreateCollection #### 功能介绍 在知识仓实例下创建collection。 #### URI POST /v1/collections/create #### 请求参数 表1请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | store_name | 是 | String | **参数解释：** 知识仓实例名称，region内唯一。 **约束限制：** 长度范围为3到63个字符，支持小写字母、数字、中划线（ - ），第一个字符只能够是小写字母，中划线( - )不得出现在字符串末尾。 **取值范围：** 不涉及 **默认取值：** 不涉及 | | collection_name | 是 | String | **参数解释：** collection名称，知识仓内唯一。 **约束限制：** 长度范围为1到255个字符，支持字母、数字、中划线（ - ）和下划线（ _ ），大小写敏感。第一个字符只能够是下划线（ _ ）和字母，中划线（ - ）不得出现在字符串末尾。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | primary_field | 是 | [primary_field] object | **参数解释：** 主键字段。 **约束限制：** 不涉及。 | | fields | 是 | Array of [field] objects | **参数解释：** 集合中通用字段，创建列的schema。 **约束限制：** 不涉及。 | | description | 否 | String | **参数解释：** 指定 Collection 的描述信息。 **约束限制：** 有效长度0-255字节。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 | | index_params | 否 | Array of [index_param] objects | **参数解释：** 索引的配置信息。 **约束限制：** 不涉及。 | | params | 否 | Map\ | **参数解释：** 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的最大长度。 | 表2primary_field | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | name | 是 | String | **参数解释：** 指定主键名。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 | | type | 是 | String | **参数解释：** 主键列的数据类型。 **约束限制：** 不涉及。 **取值范围：** "String","Int64"。 **默认取值:** 不涉及。 | 表3field | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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\ | **参数解释：** 每个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。 | 表4index_param | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | index_name | 是 | String | **参数解释：** 创建的索引名称，collection内唯一。 **约束限制：** 长度范围为1到255个字符，支持字母、数字、中划线（ - ）和下划线（ _ ），大小写敏感。第一个字符只能够是下划线（ _ ）和字母，中划线（ - ）不得出现在字符串末尾。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | field_name | 是 | String | **参数解释：** 要创建索引的目标字段名称。 **约束限制：** - 长度范围为1到255个字符，支持字母、数字、中划线（ - ）和下划线（ _ ），大小写敏感。第一个字符只能够是下划线（ _ ）和字母，中划线（ - ）不得出现在字符串末尾。 - field_name必须是collection field schema中存在的字段。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | params | 否 | Map\ | **参数解释：** 创建的索引的参数配置。 可以设置的参数： - metric_type：向量度量方式，只有向量索引需要配置。 - index_type：创建的索引类型。 - params：对应索引类型的配置参数。 1. HNSW索引类型参数： - M：节点的最大度。 - efConstruction：构建索引时每个节点邻居数。 2. HANNS索引相关参数： - max_degree：节点的最大度数。较大的值提供更高的召回率但增加索引的大小和构建时间。 - search_list_size：候选列表的大小。较大的值增加构建索引的时间但提供更高的召回率。 - encoding_type: SQ/PQ/HVQ，默认SQ。 - pq_code_budget_gb_ratio：PQ 码的大小限制。较大的值提供更高的召回率但增加内存使用量，仅当encoding_type为PQ时生效。 - hvq_nbits：HVQ码的大小限制。较大的值提高更高的召回率但增加内存使用量，仅当encoding_type为HVQ时生效。 - beamwidth：用于搜索的束宽。表示每次搜索迭代中每个查询发出的最大 I/O 请求数，可用于提升索引性能。 3. IVF_FLAT索引相关参数： - nlist：聚类的数量。 - nprobe：查询聚类的数量。 **约束限制：** 不涉及。 **取值范围：** - metric_type: 1. 稠密向量支持度量方式："IP"、"L2"和"COSINE"。 2. 稀疏向量支持度量方式："IP"。 - index_type: 1. 稠密向量支持索引类型："HNSW"、"HANNS"和"IVF_FLAT"。 2. 稀疏向量支持索引类型："SPARSE_INVERTED_INDEX"和"SPARSE_WAND"。 3. 标量字段支持索引类型："INVERTED"。 - params： 1. HNSW索引类型参数： - M：\[2, 2048\] - efConstruction：\[1, 2000\] 2. HANNS索引相关参数： - max_degree：\[1, 512\] - search_list_size：\[1, 1000\] - encoding_type: SQ/PQ/HVQ - pq_code_budget_gb_ratio：(0.0, 1.0\] - 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. 标量："INVERTED"。 - 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。 - hvq_nbits: 1 - beamwidth：4 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 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-dwr/ErrorCode.html)。