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.
To manage keyspaces, you must have the appropriate keyspace permissions, such as the Database Administrator role. To programmatically manage keyspaces, you need an application token with sufficient permissions.
Database terminology
Depending on your background and experience, you might be familiar with various terminology for database components. For example, Apache Cassandra® users might use terms like clusters, keyspaces, tables, and columns. Whereas other developers might use terms like namespaces, collections, documents, and fields to refer to functionally similar or identical components.
In Astra DB, the terminology you encounter depends on the database types and features that you use. The following table explains some of these terms. Each set of terms describe functionally similar components, but these components are not always exact equivalents. For example, a single field of vector data doesn’t necessarily translate directly to a single column of non-vector data.
| Serverless (Vector) databases | Serverless (Non-Vector) databases and CQL | Description |
|---|---|---|
Keyspace |
Keyspace |
A container for one or more collections or tables within a database. Namespace is a deprecated term for a keyspace in a Serverless (Vector) database. |
Collection |
Table |
A container for data within a database, such as vector data, non-vector data, and CQL table data. The Astra DB Data API and clients use collection. The Astra Portal uses collection in Serverless (Vector) databases and table in Serverless (Non-Vector) databases. If you use CQL to |
Document |
Row |
A piece of data, having one or more properties, stored in a collection or table in a database. |
Field |
Column |
Properties or attributes of data, such as vector dimensions or IDs. |
Create a keyspace
In a Astra DB Serverless, 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
-
In the Astra Portal, go to Databases, and then select your Serverless (Vector) database.
-
Click Data Explorer.
-
Click the Keyspace menu, and then select Create Keyspace.
-
Enter a keyspace name that is no more than 48 characters and contains only numbers, letters, and underscores.
-
Click Create Keyspace.
-
In the Astra Portal, go to Databases, and then select your Serverless (Non-Vector) database.
-
Click Add Keyspace.
-
Enter a keyspace name that is no more than 48 characters, contains only numbers, letters, and underscores, and is not the reserved words
dseorsystem. -
Click Add Keyspace.
To programmatically create keyspaces in Serverless (Vector) databases, you can use the DevOps API, the Data API clients, and the Astra CLI.
To programmatically create keyspaces in Serverless (Non-Vector) databases, you can use CQL, the DevOps API, the Data API clients, and the Astra CLI.
For example, the following curl command creates a keyspace:
curl -sS --location -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 and Cassandra Query Language (CQL) for Astra DB quickstart.
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
-
In the Astra Portal, go to Databases, and then select your Serverless (Vector) database.
-
Click Data Explorer.
-
In the Keyspace menu, locate the keyspace that you want to delete, and then click Delete.
-
To confirm deletion, enter the keyspace name, and then click Delete Keyspace.
-
In the Astra Portal, go to Databases, and then select your Serverless (Non-Vector) database.
-
In the Keyspaces section, locate the keyspace you want to delete, click More, and then click Delete.
-
To confirm deletion, enter the keyspace name, and then click Delete Keyspace.
To programmatically delete keyspaces in Serverless (Vector) databases, you can use the DevOps API, the Data API clients, and the Astra CLI.
To programmatically delete keyspaces in Serverless (Non-Vector) databases, you can use CQL, the DevOps API, the Data API clients, and the Astra CLI.
For example, the following curl command deletes a keyspace:
curl -sS --location -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 and Cassandra Query Language (CQL) for Astra DB quickstart.
The database enters Maintenance status while it deletes the keyspace along with any collections, tables, and data within the keyspace.
