Package com.datastax.astra.client

Class Database

java.lang.Object
com.datastax.astra.internal.command.AbstractCommandRunner
com.datastax.astra.client.Database
All Implemented Interfaces:
CommandRunner
public class Database extends AbstractCommandRunner
A Data API database. This is the entry-point object for doing database-level DML, such as creating/deleting collections, and for obtaining Collection objects themselves. This class has a synchronous interface.

A Database comes with an "API Endpoint", which implies a Database object instance reaches a specific region (relevant point in case of multi-region databases).

  • Constructor Details

    • Database

      public Database(String apiEndpoint, String token)
      Initialization with endpoint and apikey.
      Parameters:
      apiEndpoint - api endpoint
      token - api token

    • Database

      public Database(String apiEndpoint, String token, String namespace)
      Initialization with endpoint and apikey.
      Parameters:
      apiEndpoint - api endpoint
      token - api token
      namespace - namespace

    • Database

      public Database(String apiEndpoint, String token, String namespace, DataAPIOptions options)
      Initialization with endpoint and apikey.
      Parameters:
      apiEndpoint - api endpoint
      token - api token
      namespace - namespace
      options - setup of the clients with options

  • Method Details

    • useNamespace

      public Database useNamespace(String namespace)
      This mutates the namespace to be used.
      Parameters:
      namespace - current namespace
      Returns:
      the database

    • getDatabaseAdmin

      public DatabaseAdmin getDatabaseAdmin()
      Access a database Admin client from the database
      Returns:
      database admin

    • getDatabaseAdmin

      public DatabaseAdmin getDatabaseAdmin(String superUserToken)
      Gets the name of the database.
      Parameters:
      superUserToken - provide a token with a super-user role
      Returns:
      the database name

    • listCollectionNames

      public Stream<String> listCollectionNames()
      Gets the names of all the collections in this database.
      Returns:
      a stream containing all the names of all the collections in this database

    • listCollections

      public Stream<CollectionInfo> listCollections()
      Finds all the collections in this database.
      Returns:
      list of collection definitions

    • collectionExists

      public boolean collectionExists(String collection)
      Evaluate if a collection exists.
      Parameters:
      collection - namespace name.
      Returns:
      if namespace exists

    • getCollection

      public Collection<Document> getCollection(String collectionName)
      Gets a collection.
      Parameters:
      collectionName - the name of the collection to return
      Returns:
      the collection
      Throws:
      IllegalArgumentException - if collectionName is invalid

    • getCollection

      public <T> Collection<T> getCollection(String collectionName, @NonNull @NonNull Class<T> documentClass)
      Gets a collection, with a specific default document class.
      Type Parameters:
      T - the type of the class to use instead of Document.
      Parameters:
      collectionName - the name of the collection to return
      documentClass - the default class to cast any documents returned from the database into.
      Returns:
      the collection

    • getCollection

      public <T> Collection<T> getCollection(String collectionName, CommandOptions<?> commandOptions, @NonNull @NonNull Class<T> documentClass)
      Gets a collection, with a specific default document class.
      Type Parameters:
      T - the type of the class to use instead of Document.
      Parameters:
      collectionName - the name of the collection to return
      commandOptions - options to use when using this collection
      documentClass - the default class to cast any documents returned from the database into.
      Returns:
      the collection

    • drop

      public void drop()
      Drops this namespace

    • createCollection

      public Collection<Document> createCollection(String collectionName)
      Create a new collection with the given name.
      Parameters:
      collectionName - the name for the new collection to create
      Returns:
      the instance of collection

    • createCollection

      public Collection<Document> createCollection(String collectionName, int dimension, SimilarityMetric metric)
      Create a default new collection for vector.
      Parameters:
      collectionName - collection name
      dimension - vector dimension
      metric - vector metric
      Returns:
      the instance of collection

    • createCollection

      public <T> Collection<T> createCollection(String collectionName, int dimension, SimilarityMetric metric, Class<T> documentClass)
      Create a default new collection for vector.
      Type Parameters:
      T - working class for the document
      Parameters:
      collectionName - collection name
      dimension - vector dimension
      metric - vector metric
      documentClass - class of document to return
      Returns:
      the instance of collection

    • createCollection

      public <T> Collection<T> createCollection(String collectionName, Class<T> documentClass)
      Create a new collection with the given name.
      Type Parameters:
      T - working class for the document
      Parameters:
      collectionName - the name for the new collection to create
      documentClass - class of document to return
      Returns:
      the collection

    • createCollection

      public Collection<Document> createCollection(String collectionName, CollectionOptions collectionOptions)
      Create a new collection with the given name.
      Parameters:
      collectionName - the name for the new collection to create
      collectionOptions - various options for creating the collection
      Returns:
      the collection

    • createCollection

      public <T> Collection<T> createCollection(String collectionName, CollectionOptions collectionOptions, Class<T> documentClass)
      Create a new collection with the given name.
      Type Parameters:
      T - working object for the document
      Parameters:
      collectionName - collection name
      collectionOptions - collection options
      documentClass - document class
      Returns:
      the collection created

    • createCollection

      public Collection<Document> createCollection(String collectionName, CollectionOptions collectionOptions, CommandOptions<?> commandOptions)
      Create a new collection with the given name.
      Parameters:
      collectionName - the name for the new collection to create
      collectionOptions - various options for creating the collection
      commandOptions - options to use when using this collection
      Returns:
      the collection

    • createCollection

      public <T> Collection<T> createCollection(String collectionName, CollectionOptions collectionOptions, CommandOptions<?> commandOptions, Class<T> documentClass)
      Create a new collection with the selected options
      Type Parameters:
      T - working class for the document
      Parameters:
      collectionName - the name for the new collection to create
      collectionOptions - various options for creating the collection
      commandOptions - options to use when using this collection
      documentClass - the default class to cast any documents returned from the database into.
      Returns:
      the collection

    • dropCollection

      public void dropCollection(String collectionName)
      Delete a collection.
      Parameters:
      collectionName - collection name

    • getApiEndpoint

      protected String getApiEndpoint()
      The subclass should provide the endpoint, url to post request.
      Specified by:
      getApiEndpoint in class AbstractCommandRunner
      Returns:
      url on which to post the request

    • registerListener

      public void registerListener(String logger, CommandObserver commandObserver)
      Register a listener to execute commands on the collection. Please now use CommandOptions.
      Parameters:
      logger - name for the logger
      commandObserver - class for the logger

    • deleteListener

      public void deleteListener(String name)
      Register a listener to execute commands on the collection. Please now use CommandOptions.
      Parameters:
      name - name for the observer