Create a keyspace

Serverless (Vector) databases have an initial keyspace named default_keyspace. You can override the initial keyspace name when you create the database, if desired.

You can create more keyspaces as needed, such as for better application structure.

You need an application token with permission to interact with the target database, such as the Database Administrator role.

For more information, see Get endpoint and token.

Result

Python
TypeScript
Java
curl

The method returns None upon successful database deletion.

Returns:

Promise<void> - A promise that resolves when the keyspace is created (or when the initial request completes if not blocking).

The createKeyspace method blocks until the database is active, by default. This entails polling the database status until it is ACTIVE. You can disable this behavior by passing { blocking: false } to the options parameter.

Returns:

None.

Returns:

A successful request returns 201 Created.

Parameters

Python
TypeScript
Java
curl

db_admin.create_keyspace("KEYSPACE_NAME")

Parameters:

Name Type Summary

Name	Type	Summary
`name`	`str`	The keyspace name. 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 If supplying a keyspace that exists already, the method call proceeds as usual, no errors are raised, and the whole invocation is a no-op.
`wait_until_active`	`bool`	If True (default), the method returns only after the target database is in ACTIVE state again (a few seconds, usually). If False, it will return right after issuing the creation request to the DevOps API, and it will be responsibility of the caller to check the database status/keyspace availability before working with it.
`update_db_keyspace`	`bool`	Use this parameter to create a keyspace and immediately start using it. If True, the new keyspace becomes the working keyspace for the `Database` or `AsyncDatabase` object. For example, the following code creates a keyspace, and then modifies the `database` instance to work in the `"new_keyspace"`: `database = ... database.get_database_admin(...).create_keyspace( "new_keyspace", update_db_keyspace=True, )`
`keyspace_admin_timeout_ms`	`int`	A timeout, in milliseconds, for the whole requested operation to complete. This is relevant only if `wait_until_active` is true, i.e. if the method call must wait and keep querying the DevOps API for the status of the database being altered. Note that a timeout event is no guarantee that the keyspace creation request has not reached the API server and is not going to be, in fact, honored. If omitted, the corresponding setting from the Database Admin’s API Options is used.
`request_timeout_ms`	`int`	A timeout, in milliseconds, for each underlying DevOps API HTTP request. If omitted, the corresponding setting from the Database Admin’s API Options is used.
`timeout_ms`	`int`	An alias for both the `request_timeout_ms` and `keyspace_admin_timeout_ms` timeout parameters. In practice, regardless of `wait_until_active`, this parameter dictates an overall timeout on this method call. If omitted, the corresponding setting from the Database Admin’s API Options is used.

name

str

The keyspace name.

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

If supplying a keyspace that exists already, the method call proceeds as usual, no errors are raised, and the whole invocation is a no-op.

wait_until_active

bool

If True (default), the method returns only after the target database is in ACTIVE state again (a few seconds, usually). If False, it will return right after issuing the creation request to the DevOps API, and it will be responsibility of the caller to check the database status/keyspace availability before working with it.

update_db_keyspace

bool

Use this parameter to create a keyspace and immediately start using it. If True, the new keyspace becomes the working keyspace for the Database or AsyncDatabase object. For example, the following code creates a keyspace, and then modifies the database instance to work in the "new_keyspace":

database = ...
database.get_database_admin(...).create_keyspace(
    "new_keyspace",
    update_db_keyspace=True,
)

keyspace_admin_timeout_ms

int

A timeout, in milliseconds, for the whole requested operation to complete. This is relevant only if wait_until_active is true, i.e. if the method call must wait and keep querying the DevOps API for the status of the database being altered.

Note that a timeout event is no guarantee that the keyspace creation request has not reached the API server and is not going to be, in fact, honored.

If omitted, the corresponding setting from the Database Admin’s API Options is used.

request_timeout_ms

int

A timeout, in milliseconds, for each underlying DevOps API HTTP request.

If omitted, the corresponding setting from the Database Admin’s API Options is used.

timeout_ms

int

An alias for both the request_timeout_ms and keyspace_admin_timeout_ms timeout parameters. In practice, regardless of wait_until_active, this parameter dictates an overall timeout on this method call.

If omitted, the corresponding setting from the Database Admin’s API Options is used.

await dbAdmin.createKeyspace('KEYSPACE_NAME');

Parameters:

Name Type Summary

Name	Type	Summary
`name`	`string`	The name of the keyspace to create. 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
`options?`	`CreateAstraKeyspaceOptions`	Options regarding the creation of the keyspace. Use `updateDbKeyspace` to create a keyspace and immediately start using it. If true, the new keyspace becomes the working keyspace for the `Db` object. For example, the following code creates a keyspace and modifies the `db` instance to work in the `'new_keyspace'`: `const db = client.db('ENDPOINT'); console.log(db.keyspace); await db.admin().createKeyspace('new_keyspace', { updateDbKeyspace: true, }); console.log(db.keyspace);`

name

string

The name of the keyspace to create.

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

options?

CreateAstraKeyspaceOptions

Options regarding the creation of the keyspace.

Use updateDbKeyspace to create a keyspace and immediately start using it. If true, the new keyspace becomes the working keyspace for the Db object. For example, the following code creates a keyspace and modifies the db instance to work in the 'new_keyspace':

const db = client.db('ENDPOINT');

console.log(db.keyspace);

await db.admin().createKeyspace('new_keyspace', {
  updateDbKeyspace: true,
});

console.log(db.keyspace);

// Given 'dbAdmin', a DatabaseAdmin object
void dbAdmin.createKeyspace("new_keyspace");

// Given 'dbAdmin', also change the associated `database` object
void dbAdmin.createKeyspace("new_keyspace", true);

Parameters:

Name Type Summary

Name	Type	Summary
`keyspace`	`String`	The unique name for the keyspace 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
`updateDbKeyspace` (optional)	`boolean`	Use this parameter to create a keyspace and immediately start using it. If True, the new keyspace becomes the working keyspace for the `Database` object. For example, the following pattern creates a keyspace, and then modifies the `db` object to work in the `"new_keyspace"`: `db .getDatabaseAdmin() .createKeyspace("new_keyspace", true);`

keyspace

String

The unique name for the keyspace

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

updateDbKeyspace (optional)

boolean

Use this parameter to create a keyspace and immediately start using it. If True, the new keyspace becomes the working keyspace for the Database object. For example, the following pattern creates a keyspace, and then modifies the db object to work in the "new_keyspace":

db
  .getDatabaseAdmin()
  .createKeyspace("new_keyspace", true);

Use the DevOps API to create keyspaces programmatically. This operation is a POST request that includes the new keyspace name as a path parameter.

The application token must have sufficient permissions to perform the requested operations, such as the Organization Administrator role.

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

Examples

The following examples demonstrate how to create a keyspace.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
db_admin = client.get_admin().get_database_admin("https://01234567-...")

db_admin.list_keyspaces()
# ['default_keyspace']
db_admin.create_keyspace("that_other_one")
# this 'create_keyspace' method call takes a few seconds ...
db_admin.list_keyspaces()
# ['default_keyspace', 'that_other_one']

import { DataAPIClient } from '@datastax/astra-db-ts'

// Spawn an AstraDbAdmin instance
const admin = new DataAPIClient('TOKEN').admin();
const dbAdmin = admin.dbAdmin('ENDPOINT');

(async function () {
  // ['default_keyspace']
  console.log(await dbAdmin.listKeyspaces());

  await dbAdmin.createKeyspace('that_other_one');

  // ['default_keyspace', 'that_other_one']
  console.log(await dbAdmin.listKeyspaces());
})();

package com.datastax.astra.client.database_admin;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.databases.commands.options.CreateKeyspaceOptions;
import com.datastax.astra.client.databases.definition.keyspaces.KeyspaceDefinition;

public class CreateKeyspace {
  public static void main(String[] args) {
    // Default initialization
    Database db = new DataAPIClient("TOKEN").getDatabase("API_ENDPOINT");

    // Create a new keyspace
    db.getDatabaseAdmin().createKeyspace("<keyspace_name>");

    // The database can be mutate on keyspace creation
    db.getDatabaseAdmin().createKeyspace(
            new KeyspaceDefinition().name("<keyspace2_name>"),
            new CreateKeyspaceOptions().updateDBKeyspace(true));
  }
}

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

Client reference

Python
TypeScript
Java
curl

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

Create a keyspace

Result

Parameters

Examples

Client reference

Was this helpful?

Give Feedback