Manage namespaces and keyspaces

Astra DB Serverless databases store data in collections and tables. Collections must exist inside a namespace, and tables must exist inside a keyspace:

  • Namespaces contain collections in a Serverless (Vector) database.

  • Keyspaces contain tables in a Serverless (Non-Vector) database.

Each Astra DB database must have at least one namespace or 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 namespaces and keyspaces, you must have the appropriate permissions, such as the Organization Administrator or Database Administrator role. To programmatically manage namespaces and 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

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

The Astra Portal 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.

The Data API and clients for Astra DB Serverless use namespace. You can’t use the Data API to manage Serverless (Non-Vector) databases. For more information, see API reference overview and Databases reference.

Collection

Table

A container for data within a database.

The Astra Portal uses collection in Serverless (Vector) databases and table in Serverless (Non-Vector) databases.

The Data API and clients for Astra DB Serverless use collection.

Although you can store non-vector data, including CQL table data, in a collection, the Astra Portal and Data API still use the terms collection and namespace.

If you use CQL to CREATE TABLE in a namespace 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.

Namespaces

You use namespaces to organize related collections within a Serverless (Vector) database. A collection can contain vector or non-vector data.

Every Serverless (Vector) database has a default namespace, which is named default_keyspace, and you can create additional namespaces.

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 dropdown menu and select Create Namespace.

  4. In the Create Namespace dialog, enter a namespace name that meets the following requirements:

    • Only alphanumeric characters and underscores

    • No more than 48 characters

  5. Click Create Namespace.

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

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

curl -sS --location -X POST "https://api.astra.datastax.com/v2/databases/DB_ID/keyspaces/NAMESPACE_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 namespace. When the database returns to Active status, you can use the new namespace. For example, you can create a collection in the namespace.

Delete a namespace

Deleting a namespace permanently deletes all collections and data in the 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. 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 delete namespaces programmatically.

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

curl -sS --location -X DELETE "https://api.astra.datastax.com/v2/databases/DB_ID/keyspaces/NAMESPACE_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 namespace, its collections, and any data within those collections.

Keyspaces

A keyspace is a container for tables, similar to a schema in a relational database.

Keyspaces help you organize related tables within your Serverless (Non-Vector) databases. 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.

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