Namespaces

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

Create a namespace

Namespaces are the main database objects used to store collections in Hyper-Converged Database (HCD). It’s a good practice to create a namespace for each application.

Python
TypeScript
Java

View this topic in more detail on the API Reference.

Create a new namespace in the database:

database = DataAPIClient(
    token=token_provider, environment=Environment.HCD,
).get_database(DB_API_ENDPOINT)
database.get_database_admin().create_namespace(DB_NAMESPACE)

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

database = DataAPIClient(
    token=token_provider, environment=Environment.HCD,
).get_database(DB_API_ENDPOINT)
database.get_database_admin().create_namespace(
    DB_NAMESPACE,
    update_db_namespace=True,
)

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

database = DataAPIClient(
    token=token_provider, environment=Environment.HCD,
).get_database(DB_API_ENDPOINT)
database.get_database_admin().create_namespace(
    DB_NAMESPACE,
    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_namespace:

Name Type Summary

Name	Type	Summary
name	`str`	The namespace name. If supplying a namespace 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 Create a keyspace.
update_db_namespace	`Optional[bool]`	if True, the Database or AsyncDatabase class that created this DatabaseAdmin is updated to work on the newly-created namespace when this method returns.

name

str

The namespace name. If supplying a namespace 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 Create a keyspace.

update_db_namespace

Optional[bool]

if True, the Database or AsyncDatabase class that created this DatabaseAdmin is updated to work on the newly-created namespace 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:

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_NAMESPACE = "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 namespace; also set it as the working namespace for the database
database.get_database_admin().create_namespace(
    DB_NAMESPACE,
    update_db_namespace=True,
)

print(database.namespace == DB_NAMESPACE)  # True

The get_database_admin method of Database (or AsyncDatabase) always returns a subclass of DatabaseAdmin. For Hyper-Converged Database (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.

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

(async () => {
  await dbAdmin.createNamespace(DB_NAMESPACE);
  console.log(await dbAdmin.listNamespaces());
})();

Parameters:

Name Type Summary

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

name

string

The name of the namespace to create.

options?

AdminBlockingOptions

Blocking options regarding the creation of the namespace.

Returns:

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

Example:

(async () => {
  await dbAdmin.createNamespace(DB_NAMESPACE);
  console.log(await dbAdmin.listNamespaces());
})();

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

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

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

Returns:

None.

Parameters:

Name Type Summary

Name	Type	Summary
keyspaceName	`String`	The unique name for the namespace
NamespaceOptions	`NamespaceOptions`	The replication class and replication factor for the namespace

keyspaceName

String

The unique name for the namespace

NamespaceOptions

NamespaceOptions

The replication class and replication factor for the namespace

Example:

        // Create a default keyspace
        ((DataAPIDatabaseAdmin) client
                .getDatabase(dataApiUrl)
                .getDatabaseAdmin()).createNamespace(keyspaceName, NamespaceOptions.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 namespaces

Get a list of the namespaces found in a database.

Python
TypeScript
Java

View this topic in more detail on the API Reference.

namespaces = database.get_database_admin().list_namespaces()

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 namespaces with their names appearing in no particular order.

Example response

['cycling', 'food']

Example:

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 namespaces in the database
namespaces = database.get_database_admin().list_namespaces()

View this topic in more detail on the API Reference.

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

Returns:

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

Example:

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

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

Parameters:

None.

Returns:

Name Type Summary

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

namespaces

Set<String>

The list of available namespaces in current database.

Example:

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

Drop a namespace

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

Python
TypeScript
Java

View this topic in more detail on the API Reference.

database.get_database_admin().drop_namespace(DB_NAMESPACE)

Parameters:

Name Type Summary

Name	Type	Summary
name	`str`	The namespace 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 namespace 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:

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_NAMESPACE = "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 namespace from the database
drop_response = database.get_database_admin().drop_namespace(OLD_DB_NAMESPACE)

View this topic in more detail on the API Reference.

await dbAdmin.dropNamespace(DB_NAMESPACE);
console.log('* Namespace dropped.');
await client.close();

Parameters:

Name Type Summary

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

name

string

The name of the namespace to drop.

options?

AdminBlockingOptions

Blocking options regarding the deletion of the namespace.

Returns:

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

Example:

  // Drop the namespace
  await dbAdmin.dropNamespace(DB_NAMESPACE);
  console.log('* Namespace dropped.');
  await client.close();

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

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

Parameters:

Name Type Summary

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

namespace

String

The name of the namespace to delete.

Example:

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

Namespaces

Create a namespace

List namespaces

Drop a namespace

Was this helpful?

Give Feedback