Package com.datastax.astra.client.admin
Interface DatabaseAdmin
- All Known Implementing Classes:
AstraDBDatabaseAdmin
,DataAPIDatabaseAdmin
public interface DatabaseAdmin
Defines the core client interface for interacting with the Data API, focusing on CRUD (Create, Read, Update, Delete)
operations for namespaces. This interface extends the
CommandRunner
, incorporating methods that
allow for the execution of various data manipulation and query commands within the scope of a namespace.
Implementations of this interface should provide concrete methods for namespace management, including the creation, retrieval, updating, and deletion of namespaces. By leveraging the extended command runner capabilities, it facilitates a streamlined and efficient approach to data management within the specified context.
Example usage:
// Initialization of the client
DataApiClient client1 = DataApiClients.create("http://<>endpoint>", "<token>", new HttpClientOptions());
// Example operation: Create a new namespace
DataApiNamespace newNamespace = client.createNamespace("exampleNamespace");
// Example operation: Fetch a namespace
DataApiNamespace fetchedNamespace = client.getNamespace("exampleNamespace");
// Example operation: Delete a namespace
client.deleteNamespace("exampleNamespace");
-
Method Summary
Modifier and TypeMethodDescriptiondefault void
createNamespace
(String namespace) Syntax Sugar, retro compatible.void
createNamespace
(String namespace, boolean updateDbNamespace) Create a Namespace providing a name.default CompletableFuture
<Void> createNamespaceAsync
(String namespace) Create a Namespace providing a name.void
dropNamespace
(String namespace) Drops (deletes) the specified namespace from the database.default void
dropNamespaceAsync
(String namespace) Asynchronously drops (deletes) the specified namespace from the database.Retrieve the list of embedding providers available in the current database.Access the Database associated with this admin class.getDatabase
(String namespaceName) Retrieves aDatabase
instance that represents a specific database (or namespace) based on the provided namespace name.getDatabase
(String namespaceName, String userToken) Access the Database associated with this admin class.Retrieves a stream of namespace names available in the current database.default CompletableFuture
<Set<String>> Asynchronously retrieves a stream of namespace names available in the current database.default boolean
namespaceExists
(String namespace) Evaluate if a namespace exists.
-
Method Details
-
listNamespaceNames
Retrieves a stream of namespace names available in the current database. This method is essential for applications that need to enumerate all namespaces to perform operations such as displaying available namespaces to users, managing namespaces programmatically, or executing specific tasks within each namespace. The returned Stream facilitates efficient processing of namespace names, enabling operations like filtering, sorting, and mapping without the need for preloading all names into memory.Example usage:
// Assuming 'client' is an instance of DataApiClient Stream<String> namespaceNames = client.listNamespaceNames()); // Display names in the console namespaceNames.forEach(System.out::println);
- Returns:
- A
Set
containing the names of all namespaces within the current database. The stream provides a flexible and efficient means to process the namespace names according to the application's needs.
-
findEmbeddingProviders
FindEmbeddingProvidersResult findEmbeddingProviders()Retrieve the list of embedding providers available in the current database. Embedding providers are services that provide embeddings for text, images, or other data types. This method returns a map of provider names toEmbeddingProvider
instances, allowing applications to access and utilize the embedding services.Example usage:
// Assuming 'client' is an instance of DataApiClient Map<String, EmbeddingProvider> providers = client.findEmbeddingProvidersAsMap());
- Returns:
- list of available providers
-
listNamespaceNamesAsync
Asynchronously retrieves a stream of namespace names available in the current database. This method facilitates non-blocking operations by allowing the application to continue executing other tasks while the list of namespace names is being fetched. The method returns a CompletableFuture that, upon completion, provides a Stream of namespace names, enabling efficient and flexible processing through stream operations.Example usage:
// Assuming 'client' is an instance of DataApiClient CompletableFuture<Stream<String>> futureNamespaces = client.listNamespaceNamesAsync(); // Process the stream of names asynchronously once it's available futureNamespaces.thenAccept(streamOfNames -> { Stream<String> namespaceNames = streamOfNames); namespaceNames.forEach(System.out::println); }).exceptionally(ex -> { System.out.println("An error occurred: " + ex.getMessage()); return null; });
- Returns:
- A CompletableFuture that, when completed, provides a stream containing the names of all namespaces within the current database. This allows for the asynchronous processing of namespace names with the flexibility and efficiency benefits of using a stream.
-
getDatabase
Retrieves aDatabase
instance that represents a specific database (or namespace) based on the provided namespace name.Example usage:
// Assume 'client' is an instance of your data API client String namespaceName = "exampleNamespace"; // Retrieve the namespace instance DataApiNamespace namespace = client.getNamespace(namespaceName); // Now, 'namespace' can be used to perform operations within 'exampleNamespace'
DataApiNamespace
instance for a specified namespace name, which then enables the execution of various database operations within that namespace. It highlights the method's role in facilitating direct interaction with different parts of the database.- Parameters:
namespaceName
- The name of the namespace (or keyspace) to retrieve. This parameter should match the exact name of the namespace as it exists in the database.- Returns:
- A
DataApiNamespace
instance that encapsulates the operations and information specific to the given namespace.
-
getDatabase
Access the Database associated with this admin class.- Parameters:
namespaceName
- the destination namespace for this databaseuserToken
- the user token with DML access if different from admin.- Returns:
- instance of the database
-
getDatabase
Database getDatabase()Access the Database associated with this admin class.- Returns:
- associated database
-
dropNamespace
Drops (deletes) the specified namespace from the database. This operation is idempotent; it will not produce an error if the namespace does not exist. This method is useful for cleaning up data or removing entire keyspaces as part of database maintenance or restructuring. Caution should be exercised when using this method, as dropping a namespace will remove all the data, collections, or tables contained within it, and this action cannot be undone.Example usage:
// Assume 'client' is an instance of your data API client String namespace = "targetNamespace"; // Drop the namespace client.dropNamespace(namespace); // The namespace 'targetNamespace' is now deleted, along with all its contained data
- Parameters:
namespace
- The name of the namespace to be dropped. This parameter specifies the target namespace that should be deleted. The operation will proceed silently and without error even if the namespace does not exist, ensuring consistent behavior.
-
dropNamespaceAsync
Asynchronously drops (deletes) the specified namespace from the database. This operation is idempotent, meaning it will not produce an error if the namespace does not exist. Performing this operation asynchronously ensures that the calling thread remains responsive, and can be particularly useful for applications that require high availability and cannot afford to block on potentially long-running operations. Just like its synchronous counterpart, this method should be used with caution as dropping a namespace will remove all associated data, collections, or tables, and this action is irreversible.Example usage:
// Assume 'client' is an instance of your data API client String namespace = "asyncTargetNamespace"; // Asynchronously drop the namespace client.dropNamespaceAsync(namespace); // The namespace 'asyncTargetNamespace' is now being deleted in the background, along with all its contained data
- Parameters:
namespace
- The name of the namespace to be dropped. This is the target namespace that will be deleted. The asynchronous nature of this method means that it will execute without blocking the calling thread, regardless of whether the namespace exists or not, ensuring a consistent and responsive application behavior.
-
createNamespace
Create a Namespace providing a name.- Parameters:
namespace
- current namespace.updateDbNamespace
- if the namespace should be updated in the database.
-
createNamespace
Syntax Sugar, retro compatible.- Parameters:
namespace
- current namespace.
-
createNamespaceAsync
Create a Namespace providing a name.- Parameters:
namespace
- current namespace.- Returns:
- client for namespace
-
namespaceExists
Evaluate if a namespace exists.- Parameters:
namespace
- namespace name.- Returns:
- if namespace exists
-