Manage namespaces and keyspaces

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

In the Astra Portal, keyspaces are also referred to as namespaces. Astra DB APIs use the term keyspace to refer to both namespaces and 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

Namespace/Keyspace

Keyspace

A container for one or more collections or tables within a database.

The Astra Portal generally uses namespace in Serverless (Vector) databases and keyspace in Serverless (Non-Vector) databases. However, the name of the default namespace for each Serverless (Vector) database is default_keyspace.

CQL and Astra DB APIs use the term keyspace to refer to both namespaces and keyspaces. For more information, see Intro to Astra DB APIs and Databases reference.

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 CREATE TABLE in a keyspace in a Serverless (Vector) database, the Astra Portal still uses the terms collection and namespace. However, if you use CQL to load data, you must continue to use CQL to manage that data. You can’t use the Data Explorer or the Data API to manage CQL data.

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.

Keyspaces for collections (namespaces)

In a Serverless (Vector) database, you use keyspaces to organize related collections. Collections can contain vector or non-vector data.

In the Astra Portal, keyspaces are also referred to as namespaces. Astra DB APIs use the term keyspace to refer to both namespaces and keyspaces.

Every Serverless (Vector) database has an initial default namespace/keyspace, and you can create additional namespaces/keyspaces.

Unless you specify a default keyspace name when you create the collection, the initial keyspace’s name is default_keyspace.

Create a namespace

  • Astra Portal

  • API/CLI

  1. In the Astra Portal, go to Databases, and then select your Serverless (Vector) database.

  2. Click Data Explorer.

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

  4. In the Create Namespace dialog, enter a name that is no more than 48 characters and contains only numbers, letters, and underscores.

  5. Click Create Namespace.

You can use the DevOps API, the Data API clients, and the Astra CLI to programmatically create keyspaces in Serverless (Vector) databases. 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.

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 in the keyspace.

Delete a namespace

You can delete a namespace/keyspace if the database has more than one namespace/keyspace.

Deleting a namespace/keyspace permanently deletes all collections and data in the namespace/keyspace.

  • Astra Portal

  • API/CLI

  1. In the Astra Portal, go to Databases, and then select your Serverless (Vector) database.

  2. Click Data Explorer.

  3. In the Namespace menu, locate the namespace that you want to delete, and then click delete Delete.

  4. In the Delete Namespace dialog, enter the namespace name, and then click Delete Namespace.

You can use the DevOps API, the Data API clients, and the Astra CLI to programmatically delete keyspaces in Serverless (Vector) databases. 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.

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

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

Keyspaces for tables

In a Serverless (Non-Vector) database, a keyspace is a container for tables, similar to a schema in a relational database. Keyspaces help you organize related tables. For example, you can have different data models for each keyspace or store unique data in unique keyspaces.

Using multiple keyspaces within a single region allows you to build applications on a per-keyspace data model.

Add a keyspace

  • Astra Portal

  • API/CLI

  1. In the Astra Portal, go to Databases, and then select your Serverless (Non-Vector) database.

  2. Click Add Keyspace.

  3. Enter a keyspace name that meets the following requirements:

    • Only alphanumeric characters and underscores

    • No more than 48 characters

    • Isn’t dse or system

  4. Click Add Keyspace.

You can use CQL, the DevOps API, the Data API clients, and the Astra CLI to create keyspaces programmatically.

For example, to create a keyspace in a Serverless (Non-Vector) database, you can use the following curl command:

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) quickstart.

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

Delete a keyspace

You can delete a keyspace if the database has more than one keyspace.

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

  • Astra Portal

  • API/CLI

  1. In the Astra Portal, go to Databases, and then select your Serverless (Non-Vector) database.

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

  3. In the Delete Keyspace dialog, enter the keyspace name, and then click Delete Keyspace.

You can use CQL, the DevOps API, the Data API clients, and the Astra CLI to delete keyspaces programmatically.

For example, to delete a keyspace in a Serverless (Non-Vector) database, you can use the following curl command:

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) quickstart.

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

The database enters Maintenance status while it deletes the keyspace, its tables, and any data within those tables.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2024 DataStax | Privacy policy | Terms of use

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