Class Database
- All Implemented Interfaces:
CommandRunner
Collection
objects for further
operations on specific collections. It also provides access to operations for managing tables.
This class provides a synchronous interface, designed for straightforward and immediate execution of database commands. It is intended for use in scenarios where blocking calls are acceptable or desirable, such as in traditional server-side applications or command-line tools.
Each Database
instance is associated with an "API Endpoint," which defines the specific
region it connects to. This is particularly important for multi-region databases, where each
instance of Database
ensures connectivity to a specific regional endpoint for optimal
performance and consistency.
Key Features:
- Direct access to database-level operations, including collection management.
- Region-specific connectivity for multi-region database configurations.
- Built on
AbstractCommandRunner
, providing consistent command execution semantics.
Example usage:
// Initialize the database object with endpoint and options
DataAPIClient client = new DataAPIClient("token");
client.getDatabase("https://<id>-<region>.apps.astra.datastax.com");
// Perform database-level operations
database.createCollection("myCollection");
Collection collection = database.getCollection("myCollection");
collection.insert(new Document("field1", "value1"));
- See Also:
-
Field Summary
Fields inherited from class com.datastax.astra.internal.command.AbstractCommandRunner
apiEndpoint, ARG_CLAZZ, ARG_DATABASE, ARG_OPTIONS, ARG_UPDATE, httpClient, INPUT_INCLUDE_SIMILARITY, INPUT_INCLUDE_SORT_VECTOR, INPUT_ORDERED, INPUT_PAGE_STATE, INPUT_RETURN_DOCUMENT, INPUT_RETURN_DOCUMENT_RESPONSES, INPUT_UPSERT, options, RESULT_COUNT, RESULT_DELETED_COUNT, RESULT_INSERTED_IDS, RESULT_MATCHED_COUNT, RESULT_MODIFIED_COUNT, RESULT_MORE_DATA, RESULT_UPSERTED_ID
-
Constructor Summary
ConstructorDescriptionDatabase
(String rootEndpoint, DatabaseOptions options) Initializes aDatabase
instance with the specified API endpoint and connection options. -
Method Summary
Modifier and TypeMethodDescriptionboolean
collectionExists
(String collectionName) Checks if a specified collection exists in this database.createCollection
(String collectionName) Creates a new collection with the default document typeDocument
.createCollection
(String name, CollectionDefinition def) Creates a new collection with a specified definition and the default document typeDocument
.createCollection
(String collectionName, CollectionDefinition collectionDefinition, CreateCollectionOptions createCollectionOptions) Creates a new collection with a specified definition, options, and the default document typeDocument
.<T> Collection
<T> createCollection
(String name, CollectionDefinition def, Class<T> documentClass) Creates a new collection with a specified definition and the specified document class.<T> Collection
<T> createCollection
(String collectionName, CollectionDefinition collectionDefinition, Class<T> documentClass, CreateCollectionOptions createCollectionOptions) Creates a new collection in the database.<T> Collection
<T> createCollection
(String collectionName, Class<T> documentClass) Creates a new collection with the specified document class.<T> Table
<T> createTable
(Class<T> rowClass) Creates a table using default options and the inferred table name from the row class.<T> Table
<T> createTable
(Class<T> rowClass, CreateTableOptions createTableOptions) Creates a table using default options and the inferred table name from the row class.createTable
(String tableName, TableDefinition tableDefinition) Creates a table with a default row type ofRow
.createTable
(String tableName, TableDefinition tableDefinition, CreateTableOptions options) Creates a table using default options and runtime configurations.<T> Table
<T> createTable
(String tableName, TableDefinition tableDefinition, Class<T> rowClass) Creates a table using default options and runtime configurations.<T> Table
<T> createTable
(String tableName, TableDefinition tableDefinition, Class<T> rowClass, CreateTableOptions createTableOptions) Creates a table in the system with the specified parameters.<T> Table
<T> createTable
(String tableName, Class<T> rowClass, CreateTableOptions createTableOptions) Creates a table using default options and runtime configurations.void
dropCollection
(String collectionName) Deletes a collection from the database with default options.void
dropCollection
(String collectionName, DropCollectionOptions dropCollectionOptions) Deletes a collection from the database.void
Deletes a collection (table) from the database.void
dropTable
(String tableName, DropTableOptions dropTableOptions) Deletes a collection (table) from the database with specific options.void
dropTableIndex
(String indexName) Delete an index by name.void
dropTableIndex
(String indexName, DropTableIndexOptions dropIndexOptions) Delete an index by name.getAdmin()
Retrieves an administration client specifically for Astra deployments using the default authentication token.getAdmin
(AdminOptions adminOptions) Retrieves an administration client for Astra deployments using detailed administrative options.Retrieves an administration client specifically for Astra deployments using a provided super-user token.Gets apiEndpointgetCollection
(String collectionName) Retrieves aCollection
object for the specified collection name.getCollection
(String collectionName, CollectionOptions collectionOptions) Retrieves aCollection
object for the specified collection name with the ability to specify custom options.<T> Collection
<T> getCollection
(String collectionName, Class<T> documentClass) Retrieves aCollection
object for the specified collection name, with the ability to customize the collection behavior using the specifiedCollectionOptions
.<T> Collection
<T> getCollection
(String collectionName, Class<T> documentClass, CollectionOptions options) Retrieves aCollection
object for the specified collection name with custom options and document type.Retrieves a database administration client using the default authentication token.getDatabaseAdmin
(AdminOptions adminOptions) Retrieves a database administration client using detailed administrative options.getDatabaseAdmin
(String superUserToken) Retrieves a database administration client using a provided super-user token.getId()
Retrieves the unique database identifier (UUID) of the database if it is deployed in Astra.getInfo()
Retrieves information about the current database, including metadata and configuration details.Retrieves the name of the currently selected keyspace.getName()
Retrieves the name of the current database.Retrieves the region of the database if it is deployed in Astra.<T> Table
<T> Retrieves a table representation for a row class annotated withEntityTable
.Retrieves a table representation for the specified table name with defaultTableOptions
.getTable
(String tableName, TableOptions tableOptions) Retrieves a table representation for the specified table name andTableOptions
, defaulting toRow
type rows.<T> Table
<T> Retrieves a table representation for the specified table name and row class type with defaultTableOptions
.<T> Table
<T> getTable
(String tableName, Class<T> rowClass, TableOptions tableOptions) Retrieves a table representation for the specified table name, table options, and row class type.<T> String
getTableName
(Class<T> rowClass) Creates a table using default options and runtime configurations.Retrieves the names of all the collections present in this database.listCollectionNames
(ListCollectionOptions listCollectionOptions) Retrieves the names of all the collections present in this database, with the ability to customize the listing behavior using the specifiedListCollectionOptions
.Retrieves all collections in this database along with their definitions.listCollections
(ListCollectionOptions listCollectionOptions) Retrieves all collections in this database along with their definitions, customized by the specifiedListCollectionOptions
.Retrieves the names of all tables in the database with default options.listTableNames
(ListTablesOptions listTablesOptions) Retrieves the names of all tables in the database.Retrieves the details of all tables in the database with default options.listTables
(ListTablesOptions listTableOptions) Retrieves the details of all tables in the database.boolean
tableExists
(String tableName) Checks if a table exists in the database by its name.useKeyspace
(String keyspace) Sets the active keyspace for the database.Methods inherited from class com.datastax.astra.internal.command.AbstractCommandRunner
assertIsAstra, getOptions, getSerializer, runCommand, runCommand, unmarshall
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface com.datastax.astra.client.core.commands.CommandRunner
runCommand, runCommand
-
Constructor Details
-
Database
Initializes aDatabase
instance with the specified API endpoint and connection options. This constructor configures the database client to interact with the Data API at the provided root endpoint, setting up necessary parameters and constructing the API endpoint based on the deployment environment and options.The API endpoint is automatically adjusted for Astra deployments (e.g.,
ASTRA
,ASTRA_TEST
,ASTRA_DEV
), appending the required JSON API path if the root endpoint ends with".com"
. For local or on-premise deployments, no adjustments are made to the root endpoint.The constructed API endpoint includes:
- The specified
apiVersion
, retrieved fromDataAPIClientOptions
. - The
keyspace
, defined in the providedDatabaseOptions
.
- Parameters:
rootEndpoint
- The root API endpoint for connecting to the database. This is the base URL that determines the target deployment environment (e.g., Astra or local).options
- TheDatabaseOptions
containing all attributes required to connect to the database, including authentication details, keyspace configuration, and client options.
- The specified
-
-
Method Details
-
getKeyspace
Retrieves the name of the currently selected keyspace.- Returns:
- The name of the keyspace currently in use by this
Database
instance.
-
getRegion
Retrieves the region of the database if it is deployed in Astra. This method ensures that the database is an Astra deployment before returning the region. If the database is not deployed in Astra, an assertion error is raised.- Returns:
- The region where the Astra database is deployed.
- Throws:
IllegalStateException
- if the database is not deployed in Astra.
-
getId
Retrieves the unique database identifier (UUID) of the database if it is deployed in Astra. This method ensures that the database is an Astra deployment before returning the identifier. If the database is not deployed in Astra, an assertion error is raised.- Returns:
- The unique identifier (UUID) of the Astra database.
- Throws:
IllegalStateException
- if the database is not deployed in Astra.
-
getInfo
Retrieves information about the current database, including metadata and configuration details.This method interacts with the devops API to fetch database information. To optimize performance, the database information is cached after the first retrieval. Subsequent calls to this method return the cached
DatabaseInfo
object unless the cache is invalidated externally.Example usage:
DatabaseInfo info = database.getInfo(); System.out.println("Database Name: " + info.getName()); System.out.println("Database Version: " + info.getVersion());
- Returns:
- A
DatabaseInfo
object containing details about the current database. - Throws:
IllegalStateException
- if the database information cannot be retrieved or if the database is not properly configured for administration operations.
-
getName
Retrieves the name of the current database.This method provides a convenient way to access the database name from the
DatabaseInfo
object returned bygetInfo()
. It encapsulates the process of fetching and extracting the database name.Example usage:
String dbName = database.getName(); System.out.println("Database Name: " + dbName);
- Returns:
- The name of the current database as a
String
. - Throws:
IllegalStateException
- if the database information cannot be retrieved or is unavailable.
-
useKeyspace
Sets the active keyspace for the database. This method allows switching the current keyspace context used for database operations.- Parameters:
keyspace
- The name of the keyspace to set as the current keyspace. This must not be null or empty.- Returns:
- The database instance with the specified keyspace set as active, allowing for method chaining.
- Throws:
IllegalArgumentException
- If the provided keyspace is null or empty.Example usage:
Database database = new Database(); database.useKeyspace("my_keyspace");
-
getAdmin
Retrieves an administration client for Astra deployments using detailed administrative options.This method provides fine-grained control over the client configuration by allowing explicit specification of both the token and additional options.
- Parameters:
adminOptions
- TheAdminOptions
object containing authentication and configuration details.- Returns:
- An
AstraDBAdmin
instance configured with the provided administrative options. - Throws:
IllegalStateException
- if the database is not deployed in Astra.
-
getAdmin
Retrieves an administration client specifically for Astra deployments using the default authentication token.This client allows execution of administrative tasks such as creating databases and managing Astra configurations.
- Returns:
- An
AstraDBAdmin
instance configured with the default token for administrative operations. - Throws:
IllegalStateException
- if the database is not deployed in Astra.
-
getAdmin
Retrieves an administration client specifically for Astra deployments using a provided super-user token.This method allows overriding the default token with a custom super-user token for enhanced privileges.
- Parameters:
superUserToken
- A token with elevated privileges for administrative operations.- Returns:
- An
AstraDBAdmin
instance configured with the provided token. - Throws:
IllegalStateException
- if the database is not deployed in Astra.
-
getDatabaseAdmin
Retrieves a database administration client using detailed administrative options.Depending on the deployment type (Astra or non-Astra), this method returns an appropriate implementation of
DatabaseAdmin
, eitherAstraDBDatabaseAdmin
orDataAPIDatabaseAdmin
. The providedAdminOptions
object determines the authentication and configuration used for the client.Key behaviors:
- If no
adminOptions
are provided, a default configuration is derived from the current options. - If the deployment is Astra, an
AstraDBDatabaseAdmin
instance is returned. - For non-Astra deployments, a
DataAPIDatabaseAdmin
instance is returned.
- Parameters:
adminOptions
- TheAdminOptions
object containing authentication and configuration details.- Returns:
- A
DatabaseAdmin
instance tailored for the current deployment type and configured with the provided options.
- If no
-
getDatabaseAdmin
Retrieves a database administration client using the default authentication token.The client enables management of database-level configurations, such as keyspaces, collections, and other database settings.
- Returns:
- A
DatabaseAdmin
instance configured with the default token for database-level operations.
-
getDatabaseAdmin
Retrieves a database administration client using a provided super-user token.This method allows overriding the default token with a custom super-user token for privileged database management operations.
- Parameters:
superUserToken
- A token with elevated privileges for database administration tasks.- Returns:
- A
DatabaseAdmin
instance configured with the provided token.
-
listCollectionNames
Retrieves the names of all the collections present in this database.This method provides a list of collection names, allowing developers to explore or iterate over the available collections in the database. It is particularly useful for dynamic scenarios where the collections within a database might not be predetermined or when you need to inspect the database's current state programmatically.
Example usage:
Database database = new DataAPIClient("token").getDatabase("endpoint); List<String> collectionNames = database.listCollectionNames(); collectionNames.forEach(System.out::println);
- Returns:
- A
List
containing the names of all collections in this database. - Throws:
DataAPIException
- if an error occurs while retrieving the collection names.
-
listCollectionNames
Retrieves the names of all the collections present in this database, with the ability to customize the listing behavior using the specifiedListCollectionOptions
.This method provides a list of collection names, allowing developers to explore or iterate over the collections in the database. The behavior of this operation can be tailored by providing
ListCollectionOptions
, enabling filtering or additional configuration as needed.Parameters:
listCollectionOptions
- The options to customize the collection listing operation, such as filtering criteria or additional query parameters.
Example usage:
// Create list collection options ListCollectionOptions options = new ListCollectionOptions() .timeout(Duration.ofMillis(1000)); // Retrieve collection names based on options Database database = new DataAPIClient("token").getDatabase("endpoint); List<String> collectionNames = database.listCollectionNames(options); // Print the collection names collectionNames.forEach(System.out::println);
- Parameters:
listCollectionOptions
- TheListCollectionOptions
to customize the collection listing behavior.- Returns:
- A
List
containing the names of all collections in this database, filtered or modified according to the provided options.
-
listCollections
Retrieves all collections in this database along with their definitions.This method returns a list of
CollectionDescriptor
objects, providing detailed metadata about each collection, such as its name, schema, or other relevant attributes. It acts as a convenient entry point for obtaining all collection definitions without any filtering or additional options.Example usage:
Database database = new DataAPIClient("token").getDatabase("endpoint); List<CollectionDescriptor> collections = database.listCollections();
- Returns:
- A
List
ofCollectionDescriptor
objects representing all collections in this database.
-
listCollections
Retrieves all collections in this database along with their definitions, customized by the specifiedListCollectionOptions
.This method allows for more fine-grained control over the collection retrieval process, enabling options such as filtering, limiting the number of results, or specifying additional query parameters. The returned list includes
CollectionDescriptor
objects, which provide detailed metadata for each collection that matches the provided options.Parameters:
listCollectionOptions
- TheListCollectionOptions
to customize the listing behavior, such as filtering criteria or additional query parameters. Ifnull
, all collections are returned.
Example usage:
// Create options for listing collections with a specific prefix ListCollectionOptions options = new ListCollectionOptions() .timeout(Duration.ofMillis(1000)); // Retrieve matching collections Database database = new DataAPIClient("token").getDatabase("endpoint); List<CollectionDescriptor> collections = database.listCollections(options);
- Parameters:
listCollectionOptions
- TheListCollectionOptions
to customize the collection retrieval process. Ifnull
, no filtering or additional options are applied.- Returns:
- A
List
ofCollectionDescriptor
objects representing the collections that match the criteria.
-
collectionExists
Checks if a specified collection exists in this database.This method evaluates whether a collection with the given name is present in the database. It is useful for verifying the existence of a collection before performing operations such as querying, inserting, or updating data.
Example usage:
Database database = new DataAPIClient("token").getDatabase("endpoint"); boolean exists = database.collectionExists("my_collection"); if (exists) { System.out.println("Collection exists!"); } else { System.out.println("Collection does not exist."); }
- Parameters:
collectionName
- The name of the collection to check.- Returns:
true
if the collection exists,false
otherwise.- Throws:
IllegalArgumentException
- if the collection name isnull
or empty.
-
getCollection
Retrieves aCollection
object for the specified collection name.This method provides a convenient way to obtain a
Collection
instance for a specific collection in the database. The returned object allows for further operations on the collection, such as querying, inserting, or updating documents.Parameters:
collectionName
- The name of the collection to retrieve. This must not be null or empty.
Example usage:
Database database = new DataAPIClient("token").getDatabase("endpoint"); Collection collection = database.getCollection("my_collection");
- Parameters:
collectionName
- The name of the collection to retrieve.- Returns:
- A
Collection
object representing the specified collection. - Throws:
IllegalArgumentException
- if the collection name isnull
or empty.
-
getCollection
Retrieves aCollection
object for the specified collection name, with the ability to customize the collection behavior using the specifiedCollectionOptions
.This method provides a way to obtain a
Collection
instance for a specific collection in the database, with additional options for configuring the collection's behavior. The returned object allows for further operations on the collection, such as querying, inserting, or updating documents.Parameters:
collectionName
- The name of the collection to retrieve. This must not be null or empty.collectionOptions
- TheCollectionOptions
to customize the collection behavior, such as setting a custom serializer or specifying additional options. Ifnull
, default options are used.
Example usage:
// Create custom collection options CollectionOptions options = new CollectionOptions() .serializer(new MyCustomSerializer()); // Retrieve the collection with custom options Database database = new DataAPIClient("token").getDatabase("endpoint"); Collection collection = database.getCollection("my_collection", options);
- Type Parameters:
T
- The type of the documents stored in the collection.- Parameters:
collectionName
- The name of the collection to retrieve.documentClass
- The class type of the documents stored in the collection.- Returns:
- A
Collection
object representing the specified collection, configured with the provided options.
-
getCollection
public Collection<Document> getCollection(String collectionName, CollectionOptions collectionOptions) Retrieves aCollection
object for the specified collection name with the ability to specify custom options.This method provides a flexible way to obtain a
Collection
instance by allowing the caller to specifyCollectionOptions
to customize the behavior of the collection.Parameters:
collectionName
- The name of the collection to retrieve. This must not be null or empty.collectionOptions
- ACollectionOptions
object that specifies custom behaviors for the collection. Ifnull
, default options will be used.
Example usage:
CollectionOptions options = new CollectionOptions() .timeout(Duration.ofMillis(1000)) .dataAPIClientOptions(new DataAPIClientOptions()) .embeddingAuthProvider(new EmbeddingAPIKeyHeaderProvider("api-key")); Database database = new DataAPIClient("token").getDatabase("endpoint"); Collection collection = database.getCollection("my_collection", options);
- Parameters:
collectionName
- The name of the collection to retrieve.collectionOptions
- TheCollectionOptions
to customize the collection behavior.- Returns:
- A
Collection
object representing the specified collection. - Throws:
IllegalArgumentException
- ifcollectionName
isnull
or empty.
-
getCollection
public <T> Collection<T> getCollection(String collectionName, Class<T> documentClass, CollectionOptions options) Retrieves aCollection
object for the specified collection name with custom options and document type.This method provides the most flexible way to obtain a
Collection
instance, allowing clients to specify custom options and the type of documents in the collection.Parameters:
collectionName
- The name of the collection to retrieve. This must not be null or empty.options
- TheCollectionOptions
to customize the collection behavior. Must not be null.documentClass
- TheClass
type of the documents stored in the collection. This enables type safety when working with the collection's documents. Must not be null.
Example usage:
CollectionOptions options = new CollectionOptions() .timeout(Duration.ofMillis(1000)) .dataAPIClientOptions(new DataAPIClientOptions()) .embeddingAuthProvider(new EmbeddingAPIKeyHeaderProvider("api-key")); Collection<MyDocument> collection = database.getCollection("my_collection", options, MyDocument.class);
- Type Parameters:
T
- The type of the documents stored in the collection.- Parameters:
collectionName
- The name of the collection to retrieve.documentClass
- The class type of the documents in the collection.options
- TheCollectionOptions
for customizing the collection behavior.- Returns:
- A
Collection
object representing the specified collection. - Throws:
IllegalArgumentException
- ifcollectionName
,options
, ordocumentClass
isnull
.
-
createCollection
public <T> Collection<T> createCollection(String collectionName, CollectionDefinition collectionDefinition, Class<T> documentClass, CreateCollectionOptions createCollectionOptions) Creates a new collection in the database.- Type Parameters:
T
- The type of the documents stored in the collection.- Parameters:
collectionName
- The name of the collection to be created.collectionDefinition
- An optionalCollectionDefinition
object defining the schema and other properties of the collection.documentClass
- The class of the documents stored in the collection.createCollectionOptions
- Additional options for creating the collection, such as timeouts or retry policies.- Returns:
- The created collection as a
Collection
of the specified document type. - Throws:
IllegalArgumentException
- If any required argument is null or invalid.Example usage:
Collection<MyDocument> collection = db.createCollection( "myCollection", new CollectionDefinition(), new CollectionOptions(token, dataAPIClientOptions), new CreateCollectionOptions(), MyDocument.class );
-
createCollection
Creates a new collection with the default document typeDocument
.- Parameters:
collectionName
- The name of the collection to be created.- Returns:
- The created collection as a
Collection
ofDocument
.Example usage:
Collection<Document> collection = db.createCollection("myDefaultCollection");
-
createCollection
Creates a new collection with the specified document class.- Type Parameters:
T
- The type of the documents stored in the collection.- Parameters:
collectionName
- The name of the collection to be created.documentClass
- The class of the documents stored in the collection.- Returns:
- The created collection as a
Collection
of the specified document type.Example usage:
Collection<MyDocument> collection = db.createCollection("myTypedCollection", MyDocument.class);
-
createCollection
Creates a new collection with a specified definition and the default document typeDocument
.- Parameters:
name
- The name of the collection to be created.def
- TheCollectionDefinition
specifying the schema and other properties of the collection.- Returns:
- The created collection as a
Collection
ofDocument
.Example usage:
Collection<Document> collection = createCollection("myDefinedCollection", new CollectionDefinition());
-
createCollection
public <T> Collection<T> createCollection(String name, CollectionDefinition def, Class<T> documentClass) Creates a new collection with a specified definition and the specified document class.- Type Parameters:
T
- The type of the documents stored in the collection.- Parameters:
name
- The name of the collection to be created.def
- TheCollectionDefinition
specifying the schema and other properties of the collection.documentClass
- The class of the documents stored in the collection.- Returns:
- The created collection as a
Collection
of the specified document type.Example usage:
Collection<MyDocument> collection = createCollection("myDefinedCollection", new CollectionDefinition(), MyDocument.class);
-
createCollection
public Collection<Document> createCollection(String collectionName, CollectionDefinition collectionDefinition, CreateCollectionOptions createCollectionOptions) Creates a new collection with a specified definition, options, and the default document typeDocument
.- Parameters:
collectionName
- The name of the collection to be created.collectionDefinition
- TheCollectionDefinition
specifying the schema and other properties of the collection.createCollectionOptions
- Additional options for creating the collection, such as timeouts or retry policies.- Returns:
- The created collection as a
Collection
ofDocument
.Example usage:
Collection<Document> collection = createCollection( "myComplexCollection", new CollectionDefinition(), new CollectionOptions(token, dataAPIClientOptions), new CreateCollectionOptions() );
-
dropCollection
Deletes a collection from the database.- Parameters:
collectionName
- The name of the collection to be deleted. Must not be null or empty.dropCollectionOptions
- Additional options for dropping the collection, such as timeout or retry policies.Example usage:
db.dropCollection("myCollection", new DropCollectionOptions().timeout(Duration.ofMillis(1000)));
-
dropCollection
Deletes a collection from the database with default options.- Parameters:
collectionName
- The name of the collection to be deleted. Must not be null or empty.Example usage:
dropCollection("myCollection");
-
listTableNames
Retrieves the names of all tables in the database with default options.- Returns:
- A list of all table names in the database.
Example usage:
List<String> tableNames = listTableNames();
-
listTableNames
Retrieves the names of all tables in the database.- Parameters:
listTablesOptions
- Options for filtering or configuring the table listing operation.- Returns:
- A list of all table names in the database.
Example usage:
ListTablesOptions options = new ListTablesOptions(); List<String> tableNames = listTableNames(options);
-
listTables
Retrieves the details of all tables in the database with default options.- Returns:
- A list of
TableDescriptor
objects representing all tables in the database.Example usage:
List<TableDescriptor> tables = listTables();
-
listTables
Retrieves the details of all tables in the database.- Parameters:
listTableOptions
- Options for filtering or configuring the table listing operation.- Returns:
- A list of
TableDescriptor
objects representing all tables in the database.Example usage:
ListTablesOptions options = new ListTablesOptions(); List<TableDescriptor> tables = listTables(options);
-
tableExists
Checks if a table exists in the database by its name.- Parameters:
tableName
- The name of the table to check. Must not be null or empty.- Returns:
true
if the table exists,false
otherwise.- Throws:
IllegalArgumentException
- iftableName
is null or empty.Example usage:
boolean exists = tableExists("myTable"); if (exists) { System.out.println("The table exists."); } else { System.out.println("The table does not exist."); }
-
getTable
Retrieves a table representation for the specified table name, table options, and row class type. This is the primary method to obtain a typed table instance.- Type Parameters:
T
- the type of the row objects- Parameters:
tableName
- the name of the table (must not be null or empty)rowClass
- the class representing the type of rows in the table (must not be null)tableOptions
- options used to configure the table (e.g., connection options)- Returns:
- a
Table<T>
instance for the specified configurationExample usage:
Table<MyRowType> table = db.getTable("my_table", new TableOptions(...), MyRowType.class);
-
getTable
Retrieves a table representation for the specified table name with defaultTableOptions
.- Parameters:
tableName
- the name of the table (must not be null or empty)- Returns:
- a
Table<Row>
instance representing a generic table withRow
type rows - Throws:
IllegalArgumentException
- iftableName
is null or emptyExample usage:
Table<Row> table = db.getTable("my_table");
-
getTable
Retrieves a table representation for the specified table name and row class type with defaultTableOptions
.- Type Parameters:
T
- the type of the row objects- Parameters:
tableName
- the name of the table (must not be null or empty)rowClass
- the class representing the type of rows in the table (must not be null)- Returns:
- a
Table<T>
instance for the specified configuration - Throws:
IllegalArgumentException
- iftableName
is null or emptyNullPointerException
- ifrowClass
is nullExample usage:
Table<MyRowType> table = myFramework.getTable("my_table", MyRowType.class);
-
getTable
Retrieves a table representation for the specified table name andTableOptions
, defaulting toRow
type rows.- Parameters:
tableName
- the name of the table (must not be null or empty)tableOptions
- options used to configure the table (e.g., connection options)- Returns:
- a
Table<Row>
instance representing a generic table withRow
type rows - Throws:
IllegalArgumentException
- iftableName
is null or emptyNullPointerException
- iftableOptions
is nullExample usage:
Table<Row> table = myFramework.getTable("my_table", new TableOptions(...));
-
getTable
Retrieves a table representation for a row class annotated withEntityTable
. The table name is inferred from thevalue
attribute of theEntityTable
annotation.- Type Parameters:
T
- the type of the row objects- Parameters:
rowClass
- the class representing the type of rows in the table (must be annotated withEntityTable
)- Returns:
- a
Table<T>
instance for the inferred table name and row type - Throws:
InvalidConfigurationException
- if the provided class is not annotated withEntityTable
Example usage:
@EntityTable("my_table") public class MyRowType { ... } Table<MyRowType> table = myFramework.getTable(MyRowType.class);
-
createTable
public <T> Table<T> createTable(String tableName, TableDefinition tableDefinition, Class<T> rowClass, CreateTableOptions createTableOptions) Creates a table in the system with the specified parameters.- Type Parameters:
T
- the type of the row objects that the table will hold- Parameters:
tableName
- the name of the table to be created; must not be null or emptytableDefinition
- the schema definition of the table; must not be nullrowClass
- the class representing the row type; must not be nullcreateTableOptions
- additional options for creating the table; optional, can be null- Returns:
- the created table object
- Throws:
IllegalArgumentException
- if any mandatory argument is null or invalidExample usage:
TableDefinition tableDefinition = new TableDefinition() .addColumnText("match_id") .addColumnInt("round") .addColumnVector("m_vector", new ColumnDefinitionVector().dimension(3).metric(COSINE)) .addColumn("score", ColumnTypes.INT) .addColumn("when", ColumnTypes.TIMESTAMP) .addColumn("winner", ColumnTypes.TEXT) .addColumnSet("fighters", ColumnTypes.UUID) .addPartitionBy("match_id") .addPartitionSort(Sort.ascending("round")); // Optional CreateTableOptions createTableOptions = new CreateTableOptions().timeout(Duration.ofMillis(1000)); Table<Row> tableSimple2 = db.createTable("TABLE_SIMPLE", tableDefinition, Row.class, createTableOptions);
-
createTable
public <T> Table<T> createTable(String tableName, TableDefinition tableDefinition, Class<T> rowClass) Creates a table using default options and runtime configurations.- Type Parameters:
T
- the type of the row objects that the table will hold- Parameters:
tableName
- the name of the table to be created; must not be null or emptytableDefinition
- the schema definition of the table; must not be nullrowClass
- the class representing the row type; must not be null- Returns:
- the created table object
-
createTable
public Table<Row> createTable(String tableName, TableDefinition tableDefinition, CreateTableOptions options) Creates a table using default options and runtime configurations.- Parameters:
tableName
- the name of the table to be created; must not be null or emptytableDefinition
- the schema definition of the table; must not be nulloptions
- the option to initialize the class.- Returns:
- the created table object
-
createTable
Creates a table with a default row type ofRow
.- Parameters:
tableName
- the name of the table to be created; must not be null or emptytableDefinition
- the schema definition of the table; must not be null- Returns:
- the created table object with rows of type
Row
-
createTable
Creates a table using default options and the inferred table name from the row class.- Type Parameters:
T
- the type of the row objects that the table will hold- Parameters:
rowClass
- the class representing the row type; must not be null- Returns:
- the created table object
-
createTable
Creates a table using default options and the inferred table name from the row class.- Type Parameters:
T
- the type of the row objects that the table will hold- Parameters:
rowClass
- the class representing the row type; must not be nullcreateTableOptions
- additional options for creating the table; optional, can be null- Returns:
- the created table object
-
createTable
public <T> Table<T> createTable(String tableName, Class<T> rowClass, CreateTableOptions createTableOptions) Creates a table using default options and runtime configurations.- Type Parameters:
T
- the type of the row objects that the table will hold- Parameters:
tableName
- the name of the table to be created; must not be null or emptyrowClass
- the class representing the row type; must not be nullcreateTableOptions
- additional options for creating the table; optional, can be null- Returns:
- the created table object
-
getTableName
Creates a table using default options and runtime configurations.- Type Parameters:
T
- the type of the row objects that the table will hold- Parameters:
rowClass
- the class representing the row type; must not be null- Returns:
- the created table object
-
dropTable
Deletes a collection (table) from the database. This method delegates todropTable(String, DropTableOptions)
with default options.- Parameters:
tableName
- the name of the table to be deleted; must not be null or empty.- Throws:
IllegalArgumentException
- iftableName
is null or empty.Example usage:
database.dropTable("exampleTable");
-
dropTable
Deletes a collection (table) from the database with specific options.- Parameters:
tableName
- the name of the table to be deleted; must not be null or empty.dropTableOptions
- the options to configure the table deletion operation; can be null.- Throws:
IllegalArgumentException
- iftableName
is null or empty.Example usage:
DropTableOptions options = new DropTableOptions(); database.dropTable("exampleTable", options);
-
dropTableIndex
Delete an index by name.- Parameters:
indexName
- index name
-
dropTableIndex
Delete an index by name.- Parameters:
indexName
- index namedropIndexOptions
- flag to drop index
-
getApiEndpoint
Gets apiEndpoint- Overrides:
getApiEndpoint
in classAbstractCommandRunner<DatabaseOptions>
- Returns:
- value of apiEndpoint
-