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 |
---|---|---|
token |
|
The authentication token. It can be a string or an instance of an |
Parameters for create_namespace
:
Name | Type | Summary |
---|---|---|
name |
|
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 |
|
This dictionary can specify the options for namespace replication across database nodes. If provided, it must have a structure similar to: |
update_db_namespace |
|
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 If you were working in a cloud environment such as Astra DB—for example
|
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 |
|
The name of the namespace to create. |
options? |
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 |
// 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 |
|
The unique name for the namespace |
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 |
|
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 |
|
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 |
|
The namespace to delete. If it does not exist in this database, an error is raised. |
max_time_ms |
|
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 |
|
The name of the namespace to drop. |
options? |
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 |
((DataAPIDatabaseAdmin) client
.getDatabase(dataApiUrl)
.getDatabaseAdmin()).dropNamespace(keyspaceName);
Parameters:
Name | Type | Summary |
---|---|---|
namespace |
|
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 ");