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

An Astra DB Serverless database.
A role with keyspace permissions, such as the Database Administrator role.

To create keyspaces programmatically, you need an application token with an appropriately scoped role.

Keyspace name rules

Keyspace names must follow these rules:

Must start with a letter or number
Can contain letters, numbers, and underscores
Cannot exceed 48 characters.
Cannot be the reserved words dse or system
Must be unique within the database

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 is named default_keyspace.

You can use the Astra Portal, DevOps API, Data API clients, or Astra CLI to create keyspaces in Astra DB Serverless databases.

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

Create a keyspace in the Astra Portal

The process to create a keyspace in the Astra Portal depends on the database type:

Serverless (vector) database

In the Astra Portal, click the name of the database that you want to modify.
Click Data Explorer.
Click the Keyspace menu, and then select Create Keyspace.
Enter a keyspace name.
Click Create Keyspace.

Serverless (non-vector) database

In the Astra Portal, click the name of the database that you want to modify.
Click Add Keyspace.
Enter a keyspace name.
Click Add Keyspace.

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.

Create a keyspace with the DevOps API

To create a keyspace with the DevOps API, use POST /v2/databases/DATABASE_ID/keyspaces/KEYSPACE_NAME:

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

Replace the following:

DATABASE_ID: The database ID.
KEYSPACE_NAME: The name of the keyspace to create.
APPLICATION_TOKEN: An application token with the Database Administrator role.

For more information, see Create a keyspace.

Create a keyspace with the Astra CLI

Use the astra db create-keyspace command.

Create a keyspace with the Data API clients

You can use the Data API clients to create keyspaces in Astra DB Serverless databases. For more information and examples, see Create a 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.

You can use the Astra Portal, DevOps API, Data API clients, or Astra CLI to delete keyspaces in Astra DB Serverless databases.

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

Delete a keyspace in the Astra Portal

The process to delete a keyspace in the Astra Portal depends on the database type:

Serverless (vector) database

In the Astra Portal, click the name of the database that you want to modify.
Click Data Explorer.
Click the Keyspace menu, find the keyspace that you want to delete, and then click Delete.
To confirm deletion, enter the keyspace name, and then click Delete Keyspace.

Serverless (non-vector) database

In the Astra Portal, click the name of the database that you want to modify.
In the Keyspaces section, find the keyspace you want to delete, click More, and then click Delete.
To confirm deletion, enter the keyspace name, and then click Delete Keyspace.

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

Delete a keyspace with the DevOps API

To delete a keyspace with the DevOps API, use DELETE /v2/databases/DATABASE_ID/keyspaces/KEYSPACE_NAME:

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

Replace the following:

DATABASE_ID: The database ID.
KEYSPACE_NAME: The name of the keyspace to delete.
APPLICATION_TOKEN: An application token with the Database Administrator role.

For more information, see Drop a keyspace.

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

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.

Manage keyspaces

Prerequisites

Keyspace name rules

Create a keyspace

Create a keyspace in the Astra Portal

Create a keyspace with the DevOps API

Create a keyspace with the Astra CLI

Create a keyspace with the Data API clients

Delete a keyspace

Delete a keyspace in the Astra Portal

Delete a keyspace with the DevOps API

Delete a keyspace with the Astra CLI

Delete a keyspace with the Data API clients

Troubleshoot keyspaces

Was this helpful?

Give Feedback