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.

  • Method Details

    • listKeyspaceNames

      Set<String> listKeyspaceNames()
      Retrieves a stream of keyspaces 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 keyspaces programmatically, or executing specific tasks within each keyspace. The returned Stream facilitates efficient processing of keyspace 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> keyspacesNames = client.listKeyspacesNames());
 // Display names in the console
 keyspacesNames.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 to EmbeddingProvider 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

    • listKeyspacesNamesAsync

      default CompletableFuture<Set<String>> listKeyspacesNamesAsync()
      Asynchronously retrieves a stream of keyspaces 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 keyspace names is being fetched. The method returns a CompletableFuture that, upon completion, provides a Stream of keyspace names, enabling efficient and flexible processing through stream operations.

      Example usage:

       
 // Assuming 'client' is an instance of DataApiClient
 CompletableFuture<Stream<String>> futureKeyspaces= client.listKeyspacesNames();
 // Process the stream of names asynchronously once it's available
 futureKeyspaces.thenAccept(streamOfNames -> {
   Stream<String> keyspaceNames = streamOfNames);
   keyspaceNames.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 keyspaces within the current database. This allows for the asynchronous processing of keyspace names with the flexibility and efficiency benefits of using a stream.

    • getDatabase

      Database getDatabase(String keyspace)
      Retrieves a Database 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 keyspace = "exampleNamespace";

 // Retrieve the namespace instance
 DataApiNamespace namespace = client.getNamespace(keyspace);

 // Now, 'namespace' can be used to perform operations within 'exampleNamespace'
      This example illustrates how to obtain a 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:
      keyspace - The name of the 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 keyspace.

    • getDatabase

      Database getDatabase(String keyspace, String userToken)
      Access the Database associated with this admin class.
      Parameters:
      keyspace - the destination keyspace for this database
      userToken - 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

    • dropKeyspace

      default void dropKeyspace(String keyspace)
      Drops (deletes) the specified keyspace from the database. This operation is idempotent; it will not produce an error if the keyspace 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 keyspace 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 keyspace = "targetKeyspace";

 // Drop the keyspace
 client.dropKeyspace(keyspace);

 // The keyspace 'targetKeyspace' is now deleted, along with all its contained data
      This example demonstrates how to safely drop a keyspace by name. The operation ensures that even if the keyspace does not exist, the method call will not interrupt the flow of the application, thereby allowing for flexible and error-tolerant code design.
      Parameters:
      keyspace - The name of the keyspace to be dropped. This parameter specifies the target keyspace that should be deleted. The operation will proceed silently and without error even if the keyspace does not exist, ensuring consistent behavior.

    • dropKeyspace

      void dropKeyspace(String keyspace, BaseOptions<?> options)
      Drops (deletes) the specified keyspace from the database. This operation is idempotent; it will not produce an error if the keyspace 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 keyspace 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 keyspace = "targetKeyspace";

 // Drop the keyspace
 client.dropKeyspace(keyspace);

 // The keyspace 'targetKeyspace' is now deleted, along with all its contained data
      This example demonstrates how to safely drop a keyspace by name. The operation ensures that even if the keyspace does not exist, the method call will not interrupt the flow of the application, thereby allowing for flexible and error-tolerant code design.
      Parameters:
      keyspace - The name of the keyspace to be dropped. This parameter specifies the target keyspace that should be deleted. The operation will proceed silently and without error even if the keyspace does not exist, ensuring consistent behavior.
      options - The options to use for the operation.

    • dropKeyspaceAsync

      default void dropKeyspaceAsync(String keyspace)
      Asynchronously drops (deletes) the specified keyspace from the database. This operation is idempotent, meaning it will not produce an error if the keyspace 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 keyspace will remove all associated data, collections, or tables, and this action is irreversible. This example illustrates the non-blocking nature of dropping a keyspace. It demonstrates the method's utility in maintaining application responsiveness, even when performing potentially long-running database operations.
      Parameters:
      keyspace - The name of the keyspace to be dropped. This is the target keyspace that will be deleted. The asynchronous nature of this method means that it will execute without blocking the calling thread, regardless of whether the keyspace exists or not, ensuring a consistent and responsive application behavior.

    • createKeyspace

      void createKeyspace(String keyspace, boolean updateDBKeyspace)
      Create a Keyspace providing a name.
      Parameters:
      keyspace - current keyspace.
      updateDBKeyspace - if the keyspace should be updated in the database.

    • createKeyspace

      default void createKeyspace(String keyspace)
      Syntax Sugar, retro compatible.
      Parameters:
      keyspace - current namespace.

    • createKeyspaceAsync

      default CompletableFuture<Void> createKeyspaceAsync(String keyspace)
      Create a keyspace providing a name.
      Parameters:
      keyspace - current keyspace.
      Returns:
      client for namespace

    • keyspaceExists

      default boolean keyspaceExists(String keyspace)
      Evaluate if a keyspace exists.
      Parameters:
      keyspace - keyspace name.
      Returns:
      if keyspace exists