Create a collection

Creates a new collection in a database.

Ready to write code? See the examples for this method to get started. If you are new to the Data API, check out the quickstart.

Result

  • Python

  • TypeScript

  • Java

  • curl

Creates a collection with the specified parameters.

Returns a Collection object. You can use this object to work with documents in the collection.

Unless you specify the document_type parameter, the collection is typed as Collection[dict]. For more information, see Typing support.

Creates a collection with the specified parameters.

Returns a promise that resolves to a Collection object. You can use this object to work with documents in the collection.

A Collection is typed as Collection<Schema>, where Schema defaults to SomeDoc (Record<string, any>). Providing the specific Schema type enables stronger typing for collection operations. For more information, see Typing collections and tables.

Creates a collection with the specified parameters.

Returns a Collection object.

You can use this object to work with documents in the collection.

Creates a collection with the specified parameters.

If the command succeeds, the response indicates the success.

Example successful response:

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

Parameters

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

  • Python

  • TypeScript

  • Java

  • curl

The signature of this method changed in Python client version 2.0.

If you are using an earlier version, DataStax recommends upgrading to the latest version. For more information, see Data API client upgrade guide.

Use the create_collection method, which belongs to the astrapy.Database class.

Method signature 
create_collection(
  name: str,
  *,
  definition: CollectionDefinition | dict[str, Any] | None,
  document_type: type[Any],
  keyspace: str,
  collection_admin_timeout_ms: int,
  spawn_api_options: APIOptions,
) -> Collection

Most astrapy objects have an asynchronous counterpart for use within the asyncio framework. To get an AsyncCollection, use the create_collection method of instances of AsyncDatabase, or use the to_async method of the synchronous Collection class. For more information, see AsyncCollection.

Name Type Summary

name

str

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

definition

CollectionDefinition

Optional. The full configuration for the collection. See Properties of CollectionDefinition and Examples for more details.

document_type

type

Optional. A formal specifier for the type checker. If provided, document_type must match the type hint specified in the assignment. For more information, see Typing support.

Default: Collection[dict]

keyspace

str

Optional if you specified a keyspace when instantiating the Database object. The keyspace in which to create the collection.

Default: The working keyspace for the database.

collection_admin_timeout_ms

int

Optional. A timeout, in milliseconds, to impose on the underlying API request. If not provided, the corresponding Database defaults apply.

spawn_api_options

APIOptions

Optional. A complete or partial specification of the APIOptions to override the defaults inherited from the Database. Use this to customize the interaction of the Python client with the collection. For example, you can change the serialization/deserialization options or default timeouts. If APIOptions is passed together with a named parameter such as a timeout, the latter takes precedence over the corresponding spawn_api_options setting.
Properties of CollectionDefinition
Name Type Summary

vector

CollectionVectorOptions

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

Required for vector search.

See Create a collection that can store vector embeddings for usage.

indexing

dict

Optional. The selective indexing configuration for the collection.

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.

See Create a collection and specify which fields to index and Create a collection and specify which fields shouldn’t be indexed for usage.

Default: All fields of all documents.

default_id

CollectionDefaultIDOptions

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:

  • CollectionDefaultIDOptions(DefaultIdType.OBJECTID): Each autogenerated _id value is an objectId as provided by the bson library.

  • CollectionDefaultIDOptions(DefaultIdType.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.

  • CollectionDefaultIDOptions(DefaultIdType.UUIDV6): Each autogenerated _id value is a version 6 UUID. This is field-compatible with version 1 time UUIDs, and it supports lexicographical sorting.

  • CollectionDefaultIDOptions(DefaultIdType.UUID): Each autogenerated _id value is a version 4 UUID. This type is analogous to the uuid type and functions in Apache Cassandra®.

  • CollectionDefaultIDOptions(DefaultIdType.DEFAULT): Each autogenerated _id value is a string form of a version 4 UUID.

See Create a collection and specify the default ID format for usage.

For more information, see Document IDs.

Default: CollectionDefaultIDOptions(DefaultIdType.DEFAULT)

Use the createCollection method, which belongs to the Db class.

Method signature 
async createCollection<Schema extends SomeDoc = SomeDoc>(
  name: string,
  options?: {
    vector?: CollectionVectorOptions,
    indexing?: CollectionIndexingOptions<Schema>,
    defaultId?: CollectionDefaultIdOptions,
    logging?: DataAPILoggingConfig,
    keyspace?: string,
    serdes?: CollectionSerDesConfig,
    timeoutDefaults?: TimeoutDescriptor,
    timeout?: number | TimeoutDescriptor,
  }
): Collection<Schema>
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

CreateCollectionOptions

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

vector

CollectionVectorOptions

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

Required for vector search.

See Create a collection that can store vector embeddings for usage.

indexing

CollectionIndexingOptions<Schema>

Optional. The selective indexing configuration for the collection.

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.

See Create a collection and specify which fields to index and Create a collection and specify which fields shouldn’t be indexed for usage.

Default: All fields of all documents.

defaultId

CollectionDefaultIdOptions

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®.

See Create a collection and specify the default ID format for usage.

For more information, see Document IDs.

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

keyspace

string

Optional if you specified a keyspace when instantiating the Db object. The keyspace in which to create the collection.

Default: The working keyspace for the database.

logging

string

Optional. The configuration for logging events emitted by the DataAPIClient.

serdes

string

Optional. The configuration for serialization/deserialization by the DataAPIClient.

For more information, see Custom Ser/Des.

timeoutDefaults

TimeoutDescriptor

Optional.

The default timeout(s) to apply to operations performed on this Collection instance. You can specify requestTimeoutMs, generalMethodTimeoutMs, and collectionAdminTimeoutMs.

Details about the timeoutDefaults parameter

The default timeout options for any operation performed on this Collection instance.

The TimeoutDescriptor object can contain these properties:

  • requestTimeoutMs (number): The maximum time, in milliseconds, that the client should wait for each underlying HTTP request.

    Default: 10 seconds.

  • generalMethodTimeoutMs (number): The maximum time, in milliseconds, that the whole operation, which may involve multiple HTTP requests, can take.

    Default: 30 seconds.

  • collectionAdminTimeoutMs (number): The maximum time, in milliseconds, for collection admin operations like creating, dropping, and listing collections.

    Default: 60 seconds.

timeout

number | TimeoutDescriptor

Optional.

The timeout to apply to this method.

Only collectionAdminTimeoutMs applies to this method. This is the maximum time, in milliseconds, for collection admin operations like creating, dropping, and listing collections.

Default: 60 seconds, unless you specified a different default along the Options Hierarchy.

Use the createCollection method, which belongs to the com.datastax.astra.client.Database class.

Method signature 
Collection<Document> createCollection(String collectionName)
Collection<Document> createCollection(
  String collectionName,
  CollectionDefinition collectionDefinition
)
Collection<Document> createCollection(
  String collectionName,
  CollectionDefinition collectionDefinition,
  CreateCollectionOptions options
)
<T> Collection<T> createCollection(
  String collectionName,
  Class<T> documentClass
)
<T>  Collection<T> createCollection(
  String collectionName,
  CollectionDefinition collectionDefinition,
  Class<T> documentClass
)
<T> Collection<T> createCollection(
  String collectionName,
  CollectionDefinition collectionDefinition,
  Class<T> documentClass,
  CreateCollectionOptions options
)
Name Type Summary

collectionName

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

collectionDefinition

CollectionDefinition

Settings for the collection, including vector options, the default ID format, and indexing options.

options

CreateCollectionOptions

Options for the operation, including the keyspace.

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.

documentClass

Class<T>

Work with specialized beans for the collection instead of the default Document type.

Use the createCollection command.

Command signature 
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
  }
}'
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®.

See Create a collection and specify the default ID format for usage.

For more information, see Document IDs.

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 and similarity metric.

Required for vector search.

The vector object contains the following properties:

  • dimension (int): The dimension for vector embeddings in the collection. This should match the dimension 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.

See Create a collection that can store vector embeddings for usage.

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.

See Create a collection and specify which fields to index and Create a collection and specify which fields shouldn’t be indexed for usage.

Default: All fields of all documents.

Examples

The following examples demonstrate how to create a collection.

Create a collection that is not vector-enabled

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get a database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)

# Create a collection
collection = database.create_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

  • Typed collections

  • Untyped collections

You can manually define a client-side type for your collection to help statically catch errors.

import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get a database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});

// Define the type for the collection
interface User {
  name: string;
  age?: number;
}

// Create a collection
(async function () {
  const collection = await database.createCollection<User>(
    "COLLECTION_NAME",
    {
      keyspace: "KEYSPACE_NAME",
    },
  );
})();

If you don’t pass a type parameter, the collection remains untyped. This is a more flexible but less type-safe option.

import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get a database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});

// Create a collection
(async function () {
  const collection = await database.createCollection("COLLECTION_NAME", {
    keyspace: "KEYSPACE_NAME",
  });
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.CollectionDefinition;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.databases.Database;

public class Example {

  public static void main(String[] args) {
    // Get a database
    DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
    Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");

    // Create a collection
    Collection<Document> collection =
        database.createCollection("COLLECTION_NAME", new CollectionDefinition());
  }
}
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.

  • Python

  • TypeScript

  • Java

  • curl

The Python client supports multiple ways to create a collection:

  • You can define the collection parameters in a CollectionDefinition object and then create the collection from the CollectionDefinition object.

  • You can use a fluent interface to build the collection definition and then create the collection from the definition.

  • CollectionDefinition object

  • Fluent interface

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.constants import VectorMetric
from astrapy.info import CollectionDefinition, CollectionVectorOptions

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)

# Create a collection
collection_definition = CollectionDefinition(
    vector=CollectionVectorOptions(
        dimension=1024,
        metric=VectorMetric.COSINE,
    ),
)
collection = database.create_collection(
    "COLLECTION_NAME",
    keyspace="KEYSPACE_NAME",
    definition=collection_definition,
)
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import CollectionDefinition
from astrapy.constants import VectorMetric

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)

collection_definition = (
    CollectionDefinition.builder()
    .set_vector_dimension(1024)
    .set_vector_metric(VectorMetric.COSINE)
    .build()
)

collection = database.create_collection(
    "COLLECTION_NAME",
    keyspace="KEYSPACE_NAME",
    definition=collection_definition,
)

  • Typed collections

  • Untyped collections

You can manually define a client-side type for your collection to help statically catch errors.

You can define $vector as an inline field in your interfaces, or you can extend the utility VectorDoc type provided by the client.

import {
  DataAPIClient,
  VectorDoc,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get a database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});

// Define the type for the collection
interface User extends VectorDoc {
  name: string;
  age?: number;
}

(async function () {
  const collection = await database.createCollection<User>(
    "COLLECTION_NAME",
    {
      vector: {
        dimension: 1024,
        metric: "cosine",
      },
      keyspace: "KEYSPACE_NAME",
    },
  );
})();

If you don’t pass a type parameter, the collection remains untyped. This is a more flexible but less type-safe option.

The $vector field must still be number[] or DataAPIVector, or type-related issues will occur.

Consider using a type like VectorDoc & SomeDoc which allows the documents to remain untyped, but still statically requires the $vector field to have the correct type.

import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get a database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});

(async function () {
  const collection = await database.createCollection("COLLECTION_NAME", {
    vector: {
      dimension: 1024,
      metric: "cosine",
    },
    keyspace: "KEYSPACE_NAME",
  });
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.CollectionDefinition;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.vector.SimilarityMetric;
import com.datastax.astra.client.databases.Database;

public class Example {

  public static void main(String[] args) {
    // Get a database
    DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
    Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");

    // Create a collection
    CollectionDefinition collectionDefinition =
        new CollectionDefinition().vectorDimension(1024).vectorSimilarity(SimilarityMetric.COSINE);

    Collection<Document> collection =
        database.createCollection("COLLECTION_NAME", collectionDefinition);
  }
}
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"
      }
    }
  }
}'

Create a collection and specify the default ID format

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

  • Python

  • TypeScript

  • Java

  • curl

The Python client supports multiple ways to create a collection:

  • You can define the collection parameters in a CollectionDefinition object and then create the collection from the CollectionDefinition object.

  • You can use a fluent interface to build the collection definition and then create the collection from the definition.

  • CollectionDefinition object

  • Fluent interface

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import (
    CollectionDefinition,
    CollectionDefaultIDOptions,
)
from astrapy.constants import DefaultIdType

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)

# Create a collection
collection_definition = CollectionDefinition(
    default_id=CollectionDefaultIDOptions(DefaultIdType.OBJECTID),
)
collection = database.create_collection(
    "COLLECTION_NAME",
    keyspace="KEYSPACE_NAME",
    definition=collection_definition,
)
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import CollectionDefinition
from astrapy.constants import DefaultIdType

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)

# Create a collection
collection_definition = (
    CollectionDefinition.builder().set_default_id(DefaultIdType.OBJECTID).build()
)
collection = database.create_collection(
    "COLLECTION_NAME",
    keyspace="KEYSPACE_NAME",
    definition=collection_definition,
)

  • Typed collections

  • Untyped collections

You can manually define a client-side type for your collection to help statically catch errors.

The _id field type should match the defaultId type.

import {
  DataAPIClient,
  ObjectId,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get a database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});

// Define the type for the collection
interface User {
  _id: ObjectId;
  name: string;
  age?: number;
}

(async function () {
  const collection = await database.createCollection<User>(
    "COLLECTION_NAME",
    {
      defaultId: {
        type: "objectId",
      },
      keyspace: "KEYSPACE_NAME",
    },
  );
})();

If you don’t pass a type parameter, the collection remains untyped. This is a more flexible but less type-safe option.

However, if you later specify _id when you insert a document, DataStax recommends that it has the same type as the defaultId.

Consider using a type like { id: ObjectId } & SomeDoc which allows the documents to remain untyped, but still statically requires the _id field to have the correct type.

import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get a database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});

(async function () {
  const collection = await database.createCollection("COLLECTION_NAME", {
    defaultId: {
      type: "objectId",
    },
    keyspace: "KEYSPACE_NAME",
  });
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.CollectionDefaultIdTypes;
import com.datastax.astra.client.collections.definition.CollectionDefinition;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.databases.Database;

public class Example {

  public static void main(String[] args) {
    // Get a database
    DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
    Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");

    // Create a collection
    CollectionDefinition collectionDefinition =
        new CollectionDefinition().defaultId(CollectionDefaultIdTypes.OBJECT_ID);

    Collection<Document> collection =
        database.createCollection("COLLECTION_NAME", collectionDefinition);
  }
}
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.

  • Python

  • TypeScript

  • Java

  • curl

The Python client supports multiple ways to create a collection:

  • You can define the collection parameters in a CollectionDefinition object and then create the collection from the CollectionDefinition object.

  • You can use a fluent interface to build the collection definition and then create the collection from the definition.

  • CollectionDefinition object

  • Fluent interface

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import CollectionDefinition

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)

# Create a collection
collection_definition = CollectionDefinition(
    indexing={"allow": ["city", "country"]},
)
collection = database.create_collection(
    "COLLECTION_NAME",
    keyspace="KEYSPACE_NAME",
    definition=collection_definition,
)
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import CollectionDefinition

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)

# Create a collection
collection_definition = (
    CollectionDefinition.builder().set_indexing("allow", ["city", "country"]).build()
)
collection = database.create_collection(
    "COLLECTION_NAME",
    keyspace="KEYSPACE_NAME",
    definition=collection_definition,
)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get a database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});

(async function () {
  const collection = await database.createCollection("COLLECTION_NAME", {
    indexing: {
      allow: ["city", "country"],
    },
    keyspace: "KEYSPACE_NAME",
  });
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.CollectionDefinition;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.databases.Database;

public class Example {

  public static void main(String[] args) {
    // Get a database
    DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
    Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");

    // Create a collection
    CollectionDefinition collectionDefinition =
        new CollectionDefinition().indexingAllow("city", "country");

    Collection<Document> collection =
        database.createCollection("COLLECTION_NAME", collectionDefinition);
  }
}
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.

  • Python

  • TypeScript

  • Java

  • curl

The Python client supports multiple ways to create a collection:

  • You can define the collection parameters in a CollectionDefinition object and then create the collection from the CollectionDefinition object.

  • You can use a fluent interface to build the collection definition and then create the collection from the definition.

  • CollectionDefinition object

  • Fluent interface

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import CollectionDefinition

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)

# Create a collection
collection_definition = CollectionDefinition(
    indexing={"deny": ["city", "country"]},
)
collection = database.create_collection(
    "COLLECTION_NAME",
    keyspace="KEYSPACE_NAME",
    definition=collection_definition,
)
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import CollectionDefinition

# Get an existing database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)

# Create a collection
collection_definition = (
    CollectionDefinition.builder().set_indexing("deny", ["city", "country"]).build()
)
collection = database.create_collection(
    "COLLECTION_NAME",
    keyspace="KEYSPACE_NAME",
    definition=collection_definition,
)
import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

// Get a database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});

(async function () {
  const collection = await database.createCollection("COLLECTION_NAME", {
    indexing: {
      deny: ["city", "country"],
    },
    keyspace: "KEYSPACE_NAME",
  });
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.definition.CollectionDefinition;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.databases.Database;

public class Example {

  public static void main(String[] args) {
    // Get a database
    DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
    Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");

    // Create a collection
    CollectionDefinition collectionDefinition =
        new CollectionDefinition().indexingDeny("city", "country");

    Collection<Document> collection =
        database.createCollection("COLLECTION_NAME", collectionDefinition);
  }
}
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"]
      }
    }
  }
}'

Client reference

  • Python

  • TypeScript

  • Java

  • curl

For more information, see the client reference.

For more information, see the client reference.

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax, an IBM Company | 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: +1 (650) 389-6000, info@datastax.com