Keyspaces

Keyspaces are used to store collections in Hyper-Converged Database (HCD). To manage keyspaces, you must first get a database admin object.

HCD APIs use the term keyspace to refer to both namespaces and keyspaces.

Keyspaces are the main database objects used to store collections in HCD. It’s a good practice to create a keyspace for each application.

Python
TypeScript
Java

View this topic in more detail on the API Reference.

Create a new keyspace in the database:

python

database = DataAPIClient(
    token=token_provider, environment=Environment.HCD,
).get_database(DB_API_ENDPOINT)
database.get_database_admin().create_keyspace(DB_KEYSPACE)

Create a new keyspace in the database, while setting it as the new working keyspace for the database:

python

database = DataAPIClient(
    token=token_provider, environment=Environment.HCD,
).get_database(DB_API_ENDPOINT)
database.get_database_admin().create_keyspace(
    DB_KEYSPACE,
    update_db_keyspace=True,
)

Create a new keyspace in the database, explicitly setting its replication options:

python

database = DataAPIClient(
    token=token_provider, environment=Environment.HCD,
).get_database(DB_API_ENDPOINT)
database.get_database_admin().create_keyspace(
    DB_KEYSPACE,
    replication_options={"class": "SimpleStrategy", "replication_factor": 3},
)

Parameters for get_database_admin:

Name Type Summary

Name	Type	Summary
token	`Optional[Union[TokenProvider, str]]`	The authentication token. It can be a string or an instance of an `astrapy.authentication.TokenProvider`. If provided, overrides the token configured for the `Database` object.

token

Optional[Union[TokenProvider, str]]

The authentication token. It can be a string or an instance of an astrapy.authentication.TokenProvider. If provided, overrides the token configured for the Database object.

Parameters for create_keyspace:

Name Type Summary

Name	Type	Summary
name	`str`	The keyspace name. 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.
replication_options	`Optional[Dict[str, Any]]`	This dictionary can specify the options for namespace replication across database nodes. If provided, it must have a structure similar to: `{"class": "SimpleStrategy", "replication_factor": 1}`. See also hcd@cql:get-started:cql-quickstart.adoc#create-a-keyspace.
update_db_keyspace	`Optional[bool]`	if True, the Database or AsyncDatabase class that created this DatabaseAdmin is updated to work on the newly-created keyspace when this method returns.

name

str

The keyspace name. 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.

replication_options

Optional[Dict[str, Any]]

This dictionary can specify the options for namespace replication across database nodes. If provided, it must have a structure similar to: {"class": "SimpleStrategy", "replication_factor": 1}. See also hcd@cql:get-started:cql-quickstart.adoc#create-a-keyspace.

update_db_keyspace

Optional[bool]

if True, the Database or AsyncDatabase class that created this DatabaseAdmin is updated to work on the newly-created keyspace when this method returns.

Returns:

Dict - A dictionary of the form {"ok": 1} if the operation succeeds. Otherwise, an exception is raised.

Example response

{"ok": 1}

Example:

python

import os

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Database settings
DB_USERNAME = "cassandra"
DB_PASSWORD = "cassandra"
DB_API_ENDPOINT = "http://localhost:8181"
DB_KEYSPACE = "cycling"

# Prepare a token provider
token_provider = UsernamePasswordTokenProvider(DB_USERNAME, DB_PASSWORD)

# Initialize the client and get a "Database" object
client = DataAPIClient(token=token_provider, environment=Environment.HCD)
database = client.get_database(DB_API_ENDPOINT)

# Create the keyspace; also set it as the working keyspace for the database
database.get_database_admin().create_keyspace(
    DB_KEYSPACE,
    update_db_keyspace=True,
)

print(database.keyspace == DB_KEYSPACE)  # True

The get_database_admin method of Database (or AsyncDatabase) always returns a subclass of DatabaseAdmin. For HCD, you will get a DataAPIDatabaseAdmin.

If you were working in a cloud environment such as Astra DB—for example environment=Environment.PROD, this method would return an AstraDBDatabaseAdmin, reflecting the differences between the underlying infrastructure. In that case, there would be no support for the replication settings.

View this topic in more detail on the API Reference.

typescript

const dbAdmin = db.admin({ environment: 'hcd' });

(async () => {
  await dbAdmin.createKeyspace(DB_KEYSPACE);
  console.log(await dbAdmin.listKeyspaces());
})();

Parameters:

Name Type Summary

Name	Type	Summary
name	`string`	The name of the keyspace to create.
options?	`AdminBlockingOptions`	Blocking options regarding the creation of the keyspace.

name

string

The name of the keyspace to create.

options?

AdminBlockingOptions

Blocking options regarding the creation of the keyspace.

Returns:

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

Example:

typescript

(async () => {
  await dbAdmin.createKeyspace(DB_KEYSPACE);
  console.log(await dbAdmin.listKeyspaces());
})();

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.

java

// Create a default keyspace
((DataAPIDatabaseAdmin) client
        .getDatabase(dataApiUrl)
        .getDatabaseAdmin()).createKeyspace(keyspaceName, KeyspaceOptions.simpleStrategy(1));

Database db = client.getDatabase(dataApiUrl, keyspaceName);

Returns:

None.

Parameters:

Name Type Summary

Name	Type	Summary
keyspaceName	`String`	The unique name for the keyspace
KeyspaceOptions	`KeyspaceOptions`	The replication class and replication factor for the keyspace

keyspaceName

String

The unique name for the keyspace

KeyspaceOptions

KeyspaceOptions

The replication class and replication factor for the keyspace

Example:

java

        // Create a default keyspace
        ((DataAPIDatabaseAdmin) client
                .getDatabase(dataApiUrl)
                .getDatabaseAdmin()).createKeyspace(keyspaceName, KeyspaceOptions.simpleStrategy(1));
        System.out.println("3/7 - Keyspace '" + keyspaceName + "'created ");

        Database db = client.getDatabase(dataApiUrl, keyspaceName);
        System.out.println("4/7 - Connected to Database");

List keyspaces

Get a list of the keyspace found in a database.

Python
TypeScript
Java

View this topic in more detail on the API Reference.

python

keyspace = database.get_database_admin().list_keyspaces()

Parameters:

Name Type Summary

Name	Type	Summary
max_time_ms	`Optional[int]`	A timeout, in milliseconds, for the whole requested operation to complete.

max_time_ms

Optional[int]

A timeout, in milliseconds, for the whole requested operation to complete.

Returns:

List[str] - A list of the keyspaces with their names appearing in no particular order.

Example response

['cycling', 'food']

Example:

python

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Database settings
DB_USERNAME = "cassandra"
DB_PASSWORD = "cassandra"
DB_API_ENDPOINT = "http://localhost:8181"

# Prepare a token provider
token_provider = UsernamePasswordTokenProvider(DB_USERNAME, DB_PASSWORD)

# Initialize the client and get a "Database" object
database = DataAPIClient(
    token=token_provider, environment=Environment.HCD,
).get_database(DB_API_ENDPOINT)

# Get a list of the keyspaces in the database
keyspaces = database.get_database_admin().list_keyspaces()

View this topic in more detail on the API Reference.

typescript

(async () => {
  console.log(await dbAdmin.listKeyspaces());
})();

Returns:

Promise<string[]> - A list of the keyspaces, with the first keyspace being the default one.

Example:

typescript

(async () => {
  console.log(await dbAdmin.listKeyspaces());
})();

java

// List all keyspaces
client.getDatabase(dataApiUrl).getDatabaseAdmin().listKeyspaces().forEach(System.out::println);

Parameters:

None.

Returns:

Name Type Summary

Name	Type	Summary
keyspaces	`Set<String>`	The list of available keyspaces in current database.

keyspaces

Set<String>

The list of available keyspaces in current database.

Example:

java

        // List all keyspaces
        client.getDatabase(dataApiUrl).getDatabaseAdmin().listKeyspaces().forEach(System.out::println);

Drop a keyspace

Drop (delete) a keyspace in a database, erasing all data stored in it as well.

Python
TypeScript
Java

View this topic in more detail on the API Reference.

python

database.get_database_admin().drop_keyspace(DB_KEYSPACE)

Parameters:

Name Type Summary

Name	Type	Summary
name	`str`	The keyspace to delete. If it does not exist in this database, an error is raised.
max_time_ms	`Optional[int]`	A timeout, in milliseconds, for the whole requested operation to complete. Note that a timeout is no guarantee that the deletion request has not reached the API server.

name

str

The keyspace to delete. If it does not exist in this database, an error is raised.

max_time_ms

Optional[int]

A timeout, in milliseconds, for the whole requested operation to complete. Note that a timeout is no guarantee that the deletion request has not reached the API server.

Returns:

Dict - A dictionary of the form {"ok": 1} if the operation succeeds. Otherwise, an exception is raised.

Example response

{"ok": 1}

Example:

python

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Database settings
DB_USERNAME = "cassandra"
DB_PASSWORD = "cassandra"
DB_API_ENDPOINT = "http://localhost:8181"
OLD_DB_KEYSPACE = "cycling_legacy"

# Prepare a token provider
token_provider = UsernamePasswordTokenProvider(DB_USERNAME, DB_PASSWORD)

# Initialize the client and get a "Database" object
database = DataAPIClient(
    token=token_provider, environment=Environment.HCD,
).get_database(DB_API_ENDPOINT)

# Drop a keyspace from the database
drop_response = database.get_database_admin().drop_keyspace(OLD_DB_KEYSPACE)

View this topic in more detail on the API Reference.

typescript

await dbAdmin.dropKeyspace(DB_KEYSPACE);
console.log('* Keyspace dropped.');
await client.close();

Parameters:

Name Type Summary

Name	Type	Summary
name	`string`	The name of the keyspace to drop.
options?	`AdminBlockingOptions`	Blocking options regarding the deletion of the keyspace.

name

string

The name of the keyspace to drop.

options?

AdminBlockingOptions

Blocking options regarding the deletion of the keyspace.

Returns:

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

Example:

typescript

  // Drop the keyspace
  await dbAdmin.dropKeyspace(DB_KEYSPACE);
  console.log('* Keyspace dropped.');
  await client.close();

The dropKeyspace 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.

java

((DataAPIDatabaseAdmin) client
      .getDatabase(dataApiUrl)
      .getDatabaseAdmin()).dropKeyspace(keyspaceName);

Parameters:

Name Type Summary

Name	Type	Summary
keyspace	`String`	The name of the keyspace to delete.

keyspace

String

The name of the keyspace to delete.

Example:

java

    // Drop the keyspace
    ((DataAPIDatabaseAdmin) client
            .getDatabase(dataApiUrl)
            .getDatabaseAdmin()).dropKeyspace(keyspaceName);
    System.out.println("8/7 - Keyspace '" + keyspaceName + "' dropped ");

Keyspaces

List keyspaces

Drop a keyspace

Was this helpful?

Give Feedback