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

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

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 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: 'hcd' });

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

Parameters:

Name Type Summary

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

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

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

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

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

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

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 ");

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