Manage keyspaces

Astra DB Serverless databases store data in collections and tables, which exist inside keyspaces.

Each Astra DB database must have at least one keyspace, and you can create more as needed. For example, you can categorize your data by data model or separate unique data from your other data.

Prerequisites

Create a keyspace

In Astra DB Serverless databases, you use keyspaces to organize related collections and tables, similar to a schema in a relational database. For example, you can have different data models for each keyspace, store unique data in unique keyspaces, or use multiple keyspaces within a single region to build applications on a per-keyspace data model.

Every database has an initial keyspace, and you can create additional keyspaces. For Serverless (Vector) databases, the initial keyspace name is default_keyspace.

  • Astra Portal

  • API/CLI

  • Serverless (Vector) database

  • Serverless (Non-Vector) database

  1. In the Astra Portal navigation menu, click Databases, and then click the name of your Serverless (Vector) database.

  2. Click Data Explorer.

  3. Click the Keyspace menu, and then select Create Keyspace.

  4. Enter a keyspace name.

    Rules for keyspace names
    • Must start and end with a letter or number

    • Can contain letters, numbers, and underscores

    • Must have a length of 2 to 48 characters

    • Cannot be the reserved words dse or system

    • Must be unique within the database

  5. Click Create Keyspace.

  1. In the Astra Portal navigation menu, click Databases, and then click the name of your Serverless (Non-Vector) database.

  2. Click Add Keyspace.

  3. Enter a keyspace name.

    Rules for keyspace names
    • Must start and end with a letter or number

    • Can contain letters, numbers, and underscores

    • Must have a length of 2 to 48 characters

    • Cannot be the reserved words dse or system

    • Must be unique within the database

  4. Click Add Keyspace.

To create keyspaces in Astra DB Serverless databases programmatically, you can use the DevOps API, Data API clients, or Astra CLI. You cannot use CQL because xref:CQL for Astra DB doesn’t support the CREATE KEYSPACE command.

For example, the following curl command creates a keyspace:

curl -sS -L -X POST "https://api.astra.datastax.com/v2/databases/DB_ID/keyspaces/KEYSPACE_NAME" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

For more information, including examples and parameters, see the Databases API reference.

The database enters Maintenance status while creating the keyspace. When the database returns to Active status, you can use the new keyspace. For example, you can create a collection or table in the keyspace.

Delete a keyspace

Deleting a keyspace permanently deletes all collections, tables, and data in the keyspace.

Programmatically, it is possible to delete all keyspaces in a database, but DataStax doesn’t recommend this.

  • Astra Portal

  • API/CLI

  • Serverless (Vector) database

  • Serverless (Non-Vector) database

  1. In the Astra Portal navigation menu, click Databases, and then click the name of your Serverless (Vector) database.

  2. Click Data Explorer.

  3. In the Keyspace menu, find the keyspace that you want to delete, and then click Delete.

  4. To confirm deletion, enter the keyspace name, and then click Delete Keyspace.

  1. In the Astra Portal navigation menu, click Databases, and then click the name of your Serverless (Non-Vector) database.

  2. In the Keyspaces section, find the keyspace you want to delete, click More, and then click Delete.

  3. To confirm deletion, enter the keyspace name, and then click Delete Keyspace.

To programmatically delete keyspaces in Astra DB Serverless databases, you can use the DevOps API, Data API clients, or Astra CLI.

Astra DB doesn’t support the CQL DROP KEYSPACE command.

For example, the following curl command deletes a keyspace:

curl -sS -L -X DELETE "https://api.astra.datastax.com/v2/databases/DB_ID/keyspaces/KEYSPACE_NAME" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

For more information, including examples and parameters, see the Databases API reference.

The database enters Maintenance status while it deletes the keyspace along with any collections, tables, and data within the keyspace.

Troubleshoot keyspaces

CQL KEYSPACE command errors

CQL for Astra DB doesn’t support KEYSPACE commands. You must create and delete keyspaces through a non-CQL interface, such as the Astra Portal, DevOps API, or Astra CLI.

Data API client commands fail when passing namespace

Namespace is a deprecated term for a keyspace in a Serverless (Vector) database. This term is no longer used in the Astra Portal, and namespace was deprecated in version 1.5 of the Data API clients.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax | 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