milvus-logo
LFAI
< Docs
  • RESTful

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

    ParameterDescription
    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"
    }
}
ParameterDescription
dbNamestring
The name of the database. This parameter applies only to dedicated clusters.
collectionName *string
The name of the collection to create.
dimensioninteger
The number of dimensions a vector value should have.
This is required if dtype of this field is set to DataType.FLOAT_VECTOR.
metricTypestring
The metric type applied to this operation.
Possible values are L2, IP, and COSINE.
The value defaults to COSINE
idTypestring
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.
autoIDstring
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
primaryFieldNamestring
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.
vectorFieldNamestring
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.
schemaobject
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.autoIDstring
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.enableDynamicFieldstring
Whether allows to use the reserved $meta field to hold non-schema-defined fields in key-value pairs.
schema[].fieldsarray
A list of field objects.
schema[].fields[]object
A field object
schema[].fields[].fieldNamestring
The name of the field to create in the target collection
schema[].fields[].dataTypestring
The data type of the field values.
schema[].fields[].elementDataTypestring
The data type of the elements in an array field.
schema[].fields[].isPrimaryboolean
Whether the current field is the primary field. Setting this to True makes the current field the primary field.
schema[].fields[].isPartitionKeyboolean
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[].elementTypeParamsobject
Extra field parameters.
schema[].fields[].elementTypeParams.max_lengthinteger
An optional parameter for VarChar values that determines the maximum length of the value in the current field.
schema[].fields[].elementTypeParams.diminteger
An optional parameter for FloatVector or BinaryVector fields that determines the vector dimension.
schema[].fields[].elementTypeParams.max_capacityinteger
An optional parameter for Array field values that determines the maximum number of elements in the current array field.
indexParamsarray
The parameters that apply to the index-building process.
indexParams[]object
indexParams[].metricTypestring
The similarity metric type used to build the index.
The value defaults to COSINE
indexParams[].fieldNamestring
The name of the target field on which an index is to be created.
indexParams[].indexNamestring
The name of the index to create, the value defaults to the target field name.
indexParams[].indexConfigobject
The index type and related settings. For details, refer to Vector Indexes.
indexParams[].indexConfig.index_typestring
The type of the index to create
indexParams[].indexConfig.Minteger
The maximum degree of the node and applies only when index_type is set to HNSW.
indexParams[].indexConfig.efConstructioninteger
The search scope. This applies only when index_type is set to HNSW
indexParams[].indexConfig.nlistinteger
The number of cluster units. This applies to IVF-related index types.
paramsobject
Extra parameters for the collection.
params.max_lengthinteger
The maximum number of characters in a VarChar field. This parameter is mandatory when the current field type is VarChar.
params.enableDynamicFieldboolean
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.shardsNuminteger
The number of shards to create along with the current collection.
params.consistencyLevelinteger
The consistency level of the collection. Possible values are STRONG, BOUNDED, SESSION, and EVENTUALLY.
params.partitionsNuminteger
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.ttlSecondsinteger
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.

PropertyDescription
codeinteger
Indicates whether the request succeeds.
  • 200: The request succeeds.
  • Others: Some error occurs.
dataobject
messagestring
Indicates the possible reason for the reported error.