Create Collection
POST
http://${MILVUS_URI}/v2/vectordb/collections/create
This operation creates a collection in a specified cluster.
Example
You can choose between a quick setup or a custom setup as follows:
Quick setup
The quick setup collection has two fields: the primary and vector fields. It also allows the insertion of undefined fields and their values in key-value pairs in a dynamic field.
export MILVUS_URI="localhost:19530"
curl --location --request POST "http://${MILVUS_URI}/v2/vectordb/collections/create" \
--header "Content-Type: application/json" \
--data-raw '{
"collectionName": "test_collection",
"dimension": 5
}'
In the above setup,
- The primary and vector fields use their default names (id and vector).
- The metric type is also set to its default value (COSINE).
- The primary field accepts integers and does not automatically increments.
- The reserved JSON field named $meta is used to store non-schema-defined fields and their values.
You can modify the names of the primary and vector fields and change the metric type. Additionally, the primary field can be set to increment automatically.
export MILVUS_URI="localhost:19530"
curl --location --request POST "http://${MILVUS_URI}/v2/vectordb/collections/create" \
--header "Content-Type: application/json" \
--data-raw '{
"collectionName": "custom_quick_setup",
"dimension": 5,
"primaryFieldName": "my_id",
"idType": "VarChar",
"vectorFieldName": "my_vector",
"metric_type": "L2",
"autoId": true,
"params": {
"max_length": "512"
}
}'
In the above code, the collection will be created and automatically loaded into memory.
Custom Setup with index parameters
For a customized setup, you need to include the schema object in the request. You are advised to include the index parameters also, so that the collection will be indexed upon creation.
export MILVUS_URI="localhost:19530"
curl --location --request POST "http://${MILVUS_URI}/v2/vectordb/collections/create" \
--header "Content-Type: application/json" \
--data-raw '{
"collectionName": "custom_setup_indexed",
"schema": {
"autoId": false,
"enabledDynamicField": false,
"fields": [
{
"fieldName": "my_id",
"dataType": "Int64",
"isPrimary": true
},
{
"fieldName": "my_vector",
"dataType": "FloatVector",
"elementTypeParams": {
"dim": "5"
}
}
]
},
"indexParams": [
{
"fieldName": "my_vector",
"metricType": "COSINE",
"indexName": "my_vector",
"indexConfig": {
"index_type": "IVF_FLAT",
"nlist": "1024"
}
},
{
"fieldName": "my_id",
"indexName": "my_id",
"indexConfig": {
"index_type": "STL_SORT"
}
}
]
}
Of course, you can leave the index parameters unspecified in the request and create an index for the collection later.
export MILVUS_URI="localhost:19530"
curl --location --request POST "http://${MILVUS_URI}/v2/vectordb/collections/create" \
--header "Content-Type: application/json" \
--data-raw '{
"collectionName": "custom_setup_indexed",
"schema": {
"autoId": false,
"enabledDynamicField": false,
"fields": [
{
"fieldName": "my_id",
"dataType": "Int64",
"isPrimary": true
},
{
"fieldName": "my_vector",
"dataType": "FloatVector",
"elementTypeParams": {
"dim": "5"
}
}
]
}
}
Possible responses for the above requests are similar to the following:
{
"code": 200,
"data": {}
}
Request
Parameters
Header parameters
Parameter Description Request-Timeoutinteger(required)
The timeout duration for this operation. Setting this to None indicates that this operation times out when any response returns or an error occurs.Authorizationstring
The authentication token.No query parameters required
No path parameters required
Request Body
{
"dbName": "string",
"collectionName": "string",
"dimension": "integer",
"metricType": "string",
"idType": "string",
"autoID": "string",
"primaryFieldName": "string",
"vectorFieldName": "string",
"schema": {
"autoID": "string",
"enableDynamicField": "string",
"fields": [
{
"fieldName": "string",
"dataType": "string",
"elementDataType": "string",
"isPrimary": "boolean",
"isPartitionKey": "boolean",
"elementTypeParams": {
"max_length": "integer",
"dim": "integer",
"max_capacity": "integer"
}
}
]
},
"indexParams": [
{
"metricType": "string",
"fieldName": "string",
"indexName": "string",
"indexConfig": {
"index_type": "string",
"M": "integer",
"efConstruction": "integer",
"nlist": "integer"
}
}
],
"params": {
"max_length": "integer",
"enableDynamicField": "boolean",
"shardsNum": "integer",
"consistencyLevel": "integer",
"partitionsNum": "integer",
"ttlSeconds": "integer"
}
}
| Parameter | Description |
|---|---|
dbName | string The name of the database. |
collectionName * | string The name of the collection to create. |
dimension | integer The number of dimensions a vector value should have. This is required if dtype of this field is set to DataType.FLOAT_VECTOR. |
metricType | string The metric type applied to this operation. Possible values are L2, IP, and COSINE. The value defaults to COSINE |
idType | string The data type of the primary field. This parameter is designed for the quick-setup of a collection and will be ignored if schema is defined. |
autoID | string Whether the primary field automatically increments. This parameter is designed for the quick-setup of a collection and will be ignored if schema is defined. The value defaults to false |
primaryFieldName | string The name of the primary field. This parameter is designed for the quick-setup of a collection and will be ignored if schema is defined. |
vectorFieldName | string The name of the vector field. This parameter is designed for the quick-setup of a collection and will be ignored if schema is defined. |
schema | object The schema is responsible for organizing data in the target collection. A valid schema should have multiple fields, which must include a primary key, a vector field, and several scalar fields. |
schema.autoID | string Whether allows the primary field to automatically increment. Setting this to True makes the primary field automatically increment. In this case, the primary field should not be included in the data to insert to avoid errors. Set this parameter in the field with is_primary set to True. |
schema.enableDynamicField | string Whether allows to use the reserved $meta field to hold non-schema-defined fields in key-value pairs. |
schema[].fields | array A list of field objects. |
schema[].fields[] | object A field object |
schema[].fields[].fieldName | string The name of the field to create in the target collection |
schema[].fields[].dataType | string The data type of the field values. |
schema[].fields[].elementDataType | string The data type of the elements in an array field. |
schema[].fields[].isPrimary | boolean Whether the current field is the primary field. Setting this to True makes the current field the primary field. |
schema[].fields[].isPartitionKey | boolean Whether the current field serves as the partition key. Setting this to True makes the current field serve as the partition key. In this case, MilvusZilliz Cloud manages all partitions in the current collection. |
schema[].fields[].elementTypeParams | object Extra field parameters. |
schema[].fields[].elementTypeParams.max_length | integer An optional parameter for VarChar values that determines the maximum length of the value in the current field. |
schema[].fields[].elementTypeParams.dim | integer An optional parameter for FloatVector or BinaryVector fields that determines the vector dimension. |
schema[].fields[].elementTypeParams.max_capacity | integer An optional parameter for Array field values that determines the maximum number of elements in the current array field. |
indexParams | array The parameters that apply to the index-building process. |
indexParams[] | object |
indexParams[].metricType | string The similarity metric type used to build the index. The value defaults to COSINE |
indexParams[].fieldName | string The name of the target field on which an index is to be created. |
indexParams[].indexName | string The name of the index to create, the value defaults to the target field name. |
indexParams[].indexConfig | object The index type and related settings. For details, refer to Vector Indexes. |
indexParams[].indexConfig.index_type | string The type of the index to create |
indexParams[].indexConfig.M | integer The maximum degree of the node and applies only when index_type is set to HNSW. |
indexParams[].indexConfig.efConstruction | integer The search scope. This applies only when index_type is set to HNSW |
indexParams[].indexConfig.nlist | integer The number of cluster units. This applies to IVF-related index types. |
params | object Extra parameters for the collection. |
params.max_length | integer The maximum number of characters in a VarChar field. This parameter is mandatory when the current field type is VarChar. |
params.enableDynamicField | boolean Whether to enable the reserved dynamic field. If set to true, non-schema-defined fields are saved in the reserved dynamic field as key-value pairs. |
params.shardsNum | integer The number of shards to create along with the current collection. |
params.consistencyLevel | integer The consistency level of the collection. Possible values are STRONG, BOUNDED, SESSION, and EVENTUALLY. |
params.partitionsNum | integer The number of partitions to create along with the current collection. This parameter is mandatory if one field of the collection has been designated as the partition key. |
params.ttlSeconds | integer The time-to-live (TTL) period of the collection. If set, the collection is to be dropped once the period ends. |
Response
Returns A collection object.
Response Bodies
- Response body if we process your request successfully
{
"code": "integer",
"data": {}
}
- Response body if we failed to process your request
{
"code": integer,
"message": string
}
Properties
The properties in the returned response are listed in the following table.
| Property | Description |
|---|---|
code | integer Indicates whether the request succeeds.
|
data | object |
message | string Indicates the possible reason for the reported error. |