Create a collection (HTTP)

For details about additional languages, see:

Creates a new collection in a database.

Ready to write code? See the examples for this method to get started.

Result

Creates a collection with the specified parameters.

If the command succeeds, the response indicates the success.

Example successful response:

{
  "status": {
    "ok": 1
  }
}

You cannot edit a collection’s definition after you create the collection.

Signature

Use the createCollection command.

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "createCollection": {
    "name": "COLLECTION_NAME",
    "options": OPTIONS
  }
}'

Parameters

Name Type Summary

name

string

The name of the new collection.

Collection names must follow these rules:

  • Can contain letters, numbers, and underscores

  • Cannot exceed 48 characters

  • Must be unique within the keyspace

options

object

Optional. The options for this operation. See Properties of options for more details.
Properties of options
Name Type Summary

defaultId

object

Optional. Specifies the default ID type for documents in the collection. This is used when you insert a document without an _id field.

Can be one of:

  • {"type": "objectId"}: Each autogenerated _id value is an objectId as provided by the bson library.

  • {"type": "uuidv7"}: Each autogenerated _id value is a version 7 UUID. This is designed as a replacement for version 1 time UUID, and it is recommended for use in new systems.

  • {"type": "uuidv6"}: Each autogenerated _id value is a version 6 UUID. This is field-compatible with version 1 time UUIDs, and it supports lexicographical sorting.

  • {"type": "uuid"}: Each autogenerated _id value is a version 4 UUID. This type is analogous to the uuid type and functions in Apache Cassandra®.

For examples, see Create a collection and specify the default ID format.

For more information, see Document IDs (HTTP).

Default: Each autogenerated _id value is a string form of a version 4 UUID

vector

object

Optional. The vector configuration for the collection. This includes things like the vector dimension, similarity metric, and source model.

Required for vector search.

For an example, see Create a collection that can store vector embeddings.

The vector object contains the following properties:

  • dimension (int): The dimension for vector embeddings in the collection. This should match the dimension of the vector that your embedding model produces. Optional if you specify a vector.service.modelName value that has a default dimension value.

  • metric (string): The similarity metric to use for vector search. Can be one of: cosine (default), dot_product, euclidean.

  • sourceModel (string): Optional. The model used to generate the vector embeddings. This enables certain vector optimizations on the index. Can be one of: ada002, bert, cohere-v3, gecko, nv-qa-4, openai-v3-large, openai-v3-small, other.

indexing

object

Optional. Configures selective indexing for data inserted to the collection.

The indexing object must contain one of:

  • allow (array): The properties to index. Must contain at least one property. "allow": ["*"] indexes all properties, which is the same as the default behavior.

  • deny (array): The properties to not index. Must contain at least one property. "deny": ["*"] means that no properties are indexed.

You must use & to escape any . or & in field names in the indexing clause. You cannot use & to escape any other characters. Dot notation, which is used to reference nested fields, should not be escaped. For more information, see Work with . and & in field names (HTTP).

For examples, see Create a collection and specify which fields to index and Create a collection and specify which fields shouldn’t be indexed.

Default: All fields of all documents.

Examples

The following examples demonstrate how to create a collection.

Create a collection that is not vector-enabled

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createCollection": {
    "name": "COLLECTION_NAME",
    "options": {}
  }
}'

Create a collection that can store vector embeddings

Collections that are vector-enabled can store vector embeddings in the reserved $vector field and work with vector search.

For optimal vector search results, you should specify the dimension, metric, and source model of your vector embeddings. All vector embeddings in a collection should be generated by the same model with the same dimensions. The source model can be one of: ada002, bert, cohere-v3, gecko, nv-qa-4, openai-v3-large, openai-v3-small, other.

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createCollection": {
    "name": "COLLECTION_NAME",
    "options": {
      "vector": {
        "dimension": 1024,
        "metric": "cosine",
        "source_model": "nv-qa-4"
      }
    }
  }
}'

Create a collection and specify the default ID format

For more information about the default ID format, see Document IDs (HTTP). For allowed values, see the Parameters.

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createCollection": {
    "name": "COLLECTION_NAME",
    "options": {
      "defaultId": {
        "type": "uuidv7"
      }
    }
  }
}'

Create a collection and specify which fields to index

For more information about selective indexing, see Indexes in collections (HTTP).

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createCollection": {
    "name": "COLLECTION_NAME",
    "options": {
      "indexing": {
        "allow": ["city", "country"]
      }
    }
  }
}'

Create a collection and specify which fields shouldn’t be indexed

For more information about selective indexing, see Indexes in collections (HTTP).

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createCollection": {
    "name": "COLLECTION_NAME",
    "options": {
      "indexing": {
        "deny": ["city", "country"]
      }
    }
  }
}'

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | Privacy policy | Terms of use |  Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: Contact IBM