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 need the appropriate permissions, such as the Organization Administrator or Database Administrator role.

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

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.

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
DevOps API

In the Astra Portal, go to Databases, and then select your Serverless (Vector) database.
Click Data Explorer.
Click the Namespace dropdown menu and select Create Namespace.
In the Create Namespace dialog, enter a namespace name that meets the following requirements:
- Only alphanumeric characters and underscores
- No more than 48 characters
Click Create Namespace.

For instructions on creating namespaces programmatically, 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
DevOps API

In the Astra Portal, go to Databases, and then select your Serverless (Vector) database.
Click Data Explorer.
In the Namespace menu, locate the namespace that you want to delete, and then click delete Delete.
In the Delete Namespace dialog, enter the namespace name, and then click Delete Namespace.

For instructions on deleting namespaces programmatically, 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

You can create a keyspace in the Astra Portal or with CQL.

In the Astra Portal, go to Databases, and then select your Serverless (Non-Vector) database.
Click Add Keyspace.
Enter a keyspace name that meets the following requirements:
- Only alphanumeric characters and underscores
- No more than 48 characters
- Isn’t dse or system
Click Add Keyspace.

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.

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_vert More, and then click Delete.
In the Delete Keyspace dialog, enter the keyspace name, and then click Delete Keyspace.

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