Package com.datastax.astra.client.tables

Class Table<T>

java.lang.Object
com.datastax.astra.internal.command.AbstractCommandRunner<TableOptions>
com.datastax.astra.client.tables.Table<T>
Type Parameters:
T - the type of the table entity, representing the data model or schema
All Implemented Interfaces:
CommandRunner
public class Table<T> extends AbstractCommandRunner<TableOptions>
Executes commands and operations on tables.

The Table class is designed to work with table entities of type T, where T represents the data model or schema associated with the table.

  • Field Details

    • DEFAULT_TABLE_SERIALIZER

      public static final DataAPISerializer DEFAULT_TABLE_SERIALIZER
      Avoid duplicating for each operation if not override.

    • rowClass

      protected final Class<T> rowClass
      Working class representing rows of the table. The default value is Row.

  • Constructor Details

    • Table

      public Table(Database db, String tableName, TableOptions tableOptions, Class<T> rowClass)
      Constructs an instance of a table within the specified database. This constructor initializes the table with a given name and associates it with a specific class type that represents the schema of rows within the table. This setup is designed for CRUD (Create, Read, Update, Delete) operations.
      Parameters:
      db - The Database instance representing the client's keyspace for HTTP communication with the database. It encapsulates the configuration and management of the database connection, ensuring that operations on this table are executed within the context of this database.
      tableName - A String that uniquely identifies the table within the database. This name is used to route operations to the correct table and should adhere to the database's naming conventions.
      tableOptions - the options to apply to the command operation. If left blank the default table

      Example usage:

       
 // Given a client
 DataAPIClient client = new DataAPIClient("token");
 // Given a database
 Database myDb = client.getDatabase("myDb");
 // Initialize a table with a working class
 Table<MyRowClass> myTable = new Table<>(myDb, "myTableName", MyRowClass.class);
      rowClass - The Class<DOC> object that represents the model for rows within this table. This class is used for serialization and deserialization of rows to and from the database. It ensures type safety and facilitates the mapping of database rows to Java objects.

  • Method Details

    • getKeyspaceName

      public String getKeyspaceName()
      Retrieves the name of the parent keyspace associated with this table. A keyspace in this context typically refers to a higher-level categorization or grouping mechanism within the database that encompasses one or more tables. This method allows for identifying the broader context in which this table exists, which can be useful for operations requiring knowledge of the database structure or for dynamic database interaction patterns.
      Returns:
      A String representing the name of the parent keyspace of the current table. This name serves as an identifier for the keyspace and can be used to navigate or query the database structure.

      Example usage:

       
 Table myTable = ... // assume myTable is already initialized
 String keyspaceName = myTable.getKeyspaceName();
 System.out.println("The table belongs to the keyspace: " + keyspaceName);

    • getDefinition

      public TableDefinition getDefinition()
      Retrieves the full definition of the table, encompassing both its name and its configuration options. This comprehensive information is encapsulated in a TableDefinition object, providing access to the table's metadata and settings.

      The returned TableDefinition includes details such as the table's name, which serves as its unique identifier within the database, and a set of options that describe its configuration. These options may cover aspects like indexing preferences, read/write permissions, and other customizable settings that were specified at the time of table creation.

      Example usage:

       
 // Given a table
 Table<Row> table;
 // Access its Definition
 TableDefinition definition = table.getDefinition();
 System.out.println("Name=" + definition.getName());
 if (options != null) {
   // Operations based on table options
 }
      Returns:
      A TableDefinition object containing the full definition of the table, including its name and configuration options. This object provides a comprehensive view of the table's settings and identity within the database.

    • getName

      public String getName()
      Retrieves the name of the table. This name serves as a unique identifier within the database and is used to reference the table in database operations such as queries, updates, and deletions. The table name is defined at the time of table creation and is immutable.
      Returns:
      A String representing the name of the table. This is the same name that was specified when the table was created or initialized.

    • alter

      public final Table<T> alter(AlterTableOperation operation)
      Performs an alteration operation on the table with default options.

      This method delegates to alter(AlterTableOperation, AlterTableOptions) with options set to null.

      Parameters:
      operation - the alteration operation to be performed; must not be null.
      Returns:
      a new Table instance representing the altered table.

    • alter

      public final Table<T> alter(AlterTableOperation operation, AlterTableOptions options)
      Performs an alteration operation on the table with the specified options.

      This method delegates to alter(AlterTableOperation, AlterTableOptions, Class) using the row class of the current table.

      Parameters:
      operation - the alteration operation to be performed; must not be null.
      options - the options for the alteration operation; may be null.
      Returns:
      a new Table instance representing the altered table.

    • alter

      public final <R> Table<R> alter(AlterTableOperation operation, AlterTableOptions options, Class<R> clazz)
      Performs an alteration operation on the table with the specified options and row class.

      This is the most granular method for altering a table. It builds and executes the command to perform the specified alteration operation, with optional parameters and custom row class.

      Type Parameters:
      R - the type of the rows in the altered table.
      Parameters:
      operation - the alteration operation to be performed; must not be null.
      options - the options for the alteration operation; may be null.
      clazz - the class representing the row type for the altered table; must not be null.
      Returns:
      a new Table instance of the specified row class representing the altered table.
      Throws:
      NullPointerException - if operation or clazz is null.

    • createIndex

      public void createIndex(String idxName, String columnName)
      Create a simple index on the given column with no special options
      Parameters:
      idxName - name of the index
      columnName - column on which is the index

    • createIndex

      public void createIndex(String idxName, String columnName, CreateIndexOptions idxOptions)
      Create a simple index on the given column with no special options
      Parameters:
      idxName - name of the index
      columnName - column on which is the index
      idxOptions - index options

    • createIndex

      public void createIndex(String idxName, TableIndexDefinition idxDefinition, CreateIndexOptions idxOptions)
      Create a new index with the given description.
      Parameters:
      idxName - name of the index
      idxDefinition - definition of the index
      idxOptions - index options

    • createVectorIndex

      public void createVectorIndex(String idxName, String columnName)
      Create a new index with the given description.
      Parameters:
      idxName - name of the index
      columnName - name of the column

    • createVectorIndex

      public void createVectorIndex(String idxName, TableVectorIndexDefinition idxDefinition)
      Create a new index with the given description.
      Parameters:
      idxName - name of the index
      idxDefinition - definition of the index

    • createVectorIndex

      public void createVectorIndex(String idxName, TableVectorIndexDefinition idxDefinition, CreateVectorIndexOptions idxOptions)
      Create a new index with the given description.
      Parameters:
      idxName - index name
      idxDefinition - definition of the index
      idxOptions - index options

    • insertOne

      public final TableInsertOneResult insertOne(T row)
      Inserts a single row into the table.
      Parameters:
      row - the row to be inserted; must not be null.
      Returns:
      a TableInsertOneResult object representing the result of the insertion operation.

    • insertOne

      public final TableInsertOneResult insertOne(T row, TableInsertOneOptions insertOneOptions)
      Inserts a single row into the table with the specified options.
      Parameters:
      row - the row to be inserted; must not be null.
      insertOneOptions - the options for the insertion operation; may be null.
      Returns:
      a TableInsertOneResult object representing the result of the insertion operation.

    • insertMany

      public TableInsertManyResult insertMany(List<? extends T> rows)
      Inserts multiple rows into the table.
      Parameters:
      rows - the list of rows to be inserted; must not be null or empty.
      Returns:
      a TableInsertManyResult object representing the result of the insertion operation.

    • insertMany

      public TableInsertManyResult insertMany(List<? extends T> rows, TableInsertManyOptions insertManyOptions)
      Inserts multiple rows into the table with the specified options.
      Parameters:
      rows - the list of rows to be inserted; must not be null or empty.
      insertManyOptions - the options for the insertion operation; must not be null.
      Returns:
      a TableInsertManyResult object representing the result of the insertion operation.

    • insertMany

      @SafeVarargs public final TableInsertManyResult insertMany(T... rows)
      Inserts multiple rows into the table.
      Parameters:
      rows - the list of rows to be inserted; must not be null or empty.
      Returns:
      a TableInsertManyResult object representing the result of the insertion operation.

    • findOne

      public <R> Optional<R> findOne(Filter filter, TableFindOneOptions findOneOptions, Class<R> newRowClass)
      Retrieves a single row from the table that matches the specified filter criteria.
      Type Parameters:
      R - the type of the row in the result.
      Parameters:
      filter - the filter criteria used to select the row; may be null.
      findOneOptions - options for the find one operation
      newRowClass - the class representing the row type for the result; must not be null.
      Returns:
      an Optional containing the row that matches the filter, or an empty Optional if no match is found.

    • findOne

      public <R> Optional<R> findOne(Filter filter, Class<R> newRowClass)
      Retrieves a single row from the table that matches the specified filter criteria.
      Type Parameters:
      R - the type of the row in the result.
      Parameters:
      filter - the filter criteria used to select the row; may be null.
      newRowClass - the class representing the row type for the result; must not be null.
      Returns:
      an Optional containing the row that matches the filter, or an empty Optional if no match is found.

    • findOne

      public Optional<T> findOne(Filter filter)
      Retrieves a single row from the table that matches the specified filter criteria.
      Parameters:
      filter - the filter criteria used to select the row; may be null.
      Returns:
      an Optional containing the row that matches the filter, or an empty Optional if no match is found.

    • findOne

      public Optional<T> findOne(Filter filter, TableFindOneOptions findOneOptions)
      Retrieves a single row from the table that matches the specified filter criteria.
      Parameters:
      filter - the filter criteria used to select the row; may be null.
      findOneOptions - options for the find one operation
      Returns:
      an Optional containing the row that matches the filter, or an empty Optional if no match is found.

    • findOne

      public Optional<T> findOne(TableFindOneOptions findOneOptions)
      Retrieves a single row from the table that matches the specified filter criteria.
      Parameters:
      findOneOptions - options for the find one operation
      Returns:
      an Optional containing the row or an empty Optional if no match is found.

    • find

      public TableCursor<T,T> find(Filter filter, TableFindOptions options)
      Finds all rows in the table.
      Parameters:
      filter - the query filter
      options - options of find one
      Returns:
      the Cursor to iterate over the results

    • find

      public <R> TableCursor<T,R> find(Filter filter, TableFindOptions options, Class<R> newRowType)
      Finds all rows in the table.
      Type Parameters:
      R - the type of the row in the result.
      Parameters:
      filter - the query filter
      options - options of find one
      newRowType - the class representing the row type for the result; must not be null.
      Returns:
      the Cursor to iterate over the results

    • find

      public TableCursor<T,T> find(Filter filter)
      Finds all rows in the table.
      Parameters:
      filter - the query filter
      Returns:
      the Cursor to iterate over the results

    • find

      public TableCursor<T,T> find(TableFindOptions options)
      Finds all rows in the table.
      Parameters:
      options - options of find one
      Returns:
      the Cursor to iterate over the results

    • findAll

      public TableCursor<T,T> findAll()
      Retrieves all rows in the table.

      This method returns an iterable interface that allows iterating over all rows in the table, without applying any filters. It leverages the default TableFindOptions for query execution.

      Returns:
      A TableCursor for iterating over all rows in the table.

    • findPage

      public Page<T> findPage(Filter filter, TableFindOptions options)
      Executes a paginated 'find' query on the table using the specified filter and find options.

      This method constructs and executes a command to fetch a specific page of rows from the table that match the provided filter criteria. It allows for detailed control over the query through FindOptions, such as sorting, projection, pagination, and more. The result is wrapped in a Page object, which includes the rows found, the page size, and the state for fetching subsequent pages.

      Pagination is facilitated by the skip, limit, and pageState parameters within FindOptions, enabling efficient data retrieval in scenarios where the total dataset is too large to be fetched in a single request. Optionally, similarity scoring can be included if includeSimilarity is set, which is useful for vector-based search queries.

      The method processes the command's response, mapping each rows to the specified row class and collecting them into a list. This list, along with the maximum page size and the next page state, is used to construct the Page object returned by the method.

      Parameters:
      filter - The filter criteria used to select rows from the table.
      options - The CollectionFindOptions providing additional query parameters, such as sorting and pagination.
      Returns:
      A Page object containing the rows that match the query, along with pagination information.

    • distinct

      public <R> List<R> distinct(String fieldName, Filter filter, Class<R> resultClass)
      Return a list of distinct values for the given field name.
      Type Parameters:
      R - type of the result
      Parameters:
      fieldName - name of the field
      filter - filter to apply
      resultClass - class of the result
      Returns:
      list of distinct values

    • distinct

      public <R> List<R> distinct(String fieldName, Filter filter, Class<R> resultClass, TableDistinctOptions options)
      Return a list of distinct values for the given field name.
      Type Parameters:
      R - type of the result
      Parameters:
      fieldName - name of the field
      filter - filter to apply
      resultClass - class of the result
      options - options to apply to the operation
      Returns:
      list of distinct values

    • updateOne

      public void updateOne(Filter filter, TableUpdateOperation update)
      Update a single row in the table according to the specified arguments.
      Parameters:
      filter - a row describing the query filter, which may not be null.
      update - a row describing the update, which may not be null. The update to apply must include at least one update operator.

    • updateOne

      public void updateOne(Filter filter, TableUpdateOperation update, TableUpdateOneOptions updateOptions)
      Update a single document in the collection according to the specified arguments.
      Parameters:
      filter - a document describing the query filter, which may not be null.
      update - a document describing the update, which may not be null. The update to apply must include at least one update operator.
      updateOptions - the options to apply to the update operation

    • deleteOne

      public void deleteOne(Filter filter)
      Removes at most one rows from the table that matches the given filter. If no rows match, the table is not modified.
      Parameters:
      filter - the query filter to apply the delete operation

    • deleteOne

      public void deleteOne(Filter filter, TableDeleteOneOptions deleteOneOptions)
      Removes at most one row from the table that matches the given filter. If no rows match, the table is not modified.
      Parameters:
      filter - the query filter to apply the delete operation
      deleteOneOptions - the option to driver the deletes (here sort)

    • deleteMany

      public void deleteMany(Filter filter, TableDeleteManyOptions options)
      Removes all rows from the tables that match the given query filter. If no rows match, the table is not modified.
      Parameters:
      filter - the query filter to apply the delete operation
      options - the options to apply to the operation

    • deleteMany

      public void deleteMany(Filter filter)
      Removes all rows from the table that match the given query filter. If no rows match, the table is not modified.
      Parameters:
      filter - the query filter to apply the delete operation

    • deleteAll

      public void deleteAll()
      Removes all rows from the table that match the given query filter. If no rows match, the table is not modified.

    • drop

      public void drop()
      Delete the current table

    • estimatedRowCount

      public long estimatedRowCount()
      Calling an estimatedRowCount with default options. @see estimatedRowCount(EstimatedCountRowsOptions)
      Returns:
      the estimated number of rows in the table.

    • estimatedRowCount

      public long estimatedRowCount(EstimatedCountRowsOptions options)
      Executes the "estimatedRowCount" command to estimate the number of rowse in a table.

      This method sends a command to estimate the row count and parses the count from the command's response. It handles the execution of the command and the extraction of the row count from the response.

      Parameters:
      options - the options to apply to the operation
      Returns:
      the estimated number of rows in the table.

    • countRows

      public int countRows(int upperBound) throws TooManyRowsToCountException
      Counts the number of rows in the table.

      Takes in a `upperBound` option which dictates the maximum number of rows that may be present before a TooManyRowsToCountException is thrown. If the limit is higher than the highest limit accepted by the Data API, a TooManyRowsToCountException will be thrown anyway (i.e. `1000`).

      Count operations are expensive: for this reason, the best practice is to provide a reasonable `upperBound` according to the caller expectations. Moreover, indiscriminate usage of count operations for sizeable amounts of rows (i.e. in the thousands and more) is discouraged in favor of alternative application-specific solutions. Keep in mind that the Data API has a hard upper limit on the amount of rows it will count, and that an exception will be thrown by this method if this limit is encountered.

      Parameters:
      upperBound - The maximum number of rows to count.
      Returns:
      The number of rows in the tables.
      Throws:
      TooManyRowsToCountException - If the number of rows counted exceeds the provided limit.

    • countRows

      public int countRows(Filter filter, int upperBound, CountRowsOptions options) throws TooManyRowsToCountException
      Counts the number of rows in the table with a filter.

      Takes in a `upperBound` option which dictates the maximum number of rows that may be present before a TooManyRowsToCountException is thrown. If the limit is higher than the highest limit accepted by the Data API, a TooManyRowsToCountException will be thrown anyway (i.e. `1000`).

      Count operations are expensive: for this reason, the best practice is to provide a reasonable `upperBound` according to the caller expectations. Moreover, indiscriminate usage of count operations for sizeable amounts of rows (i.e. in the thousands and more) is discouraged in favor of alternative application-specific solutions. Keep in mind that the Data API has a hard upper limit on the amount of rows it will count, and that an exception will be thrown by this method if this limit is encountered.

      Parameters:
      filter - A filter to select the row to count. If not provided, all rows will be counted.
      upperBound - The maximum number of rows to count.
      options - overriding options for the count operation.
      Returns:
      The number of rows in the table.
      Throws:
      TooManyRowsToCountException - If the number of rows counted exceeds the provided limit.

    • countRows

      public int countRows(Filter filter, int upperBound) throws TooManyRowsToCountException
      Implementation of the @see countRows(Filter, int, CountRowsOptions) method with default options.
      Parameters:
      filter - filter to count
      upperBound - The maximum number of rows to count. It must be lower than the maximum limit accepted by the Data API.
      Returns:
      The number of rows in the table.
      Throws:
      TooManyRowsToCountException - If the number of rows counted exceeds the provided limit.

    • listIndexesNames

      public List<String> listIndexesNames()
      Retrieves the names of all indices in the keyspace with default options.
      Returns:
      A list of all indices names in the database.

      Example usage:

       
 List<String> indicesNames = listIndexesNames();

    • listIndexesNames

      public List<String> listIndexesNames(ListIndexesOptions listIndexesOptions)
      Retrieves the names of all indices in the keyspace with default options.
      Parameters:
      listIndexesOptions - Options for filtering or configuring the indices listing operation.
      Returns:
      A list of all indices names in the database.

      Example usage:

       
 ListIndexesOptions options = new ListIndexesOptions();
 List<String> indicesNames = listIndexesNames(options);

    • listIndexes

      public List<TableIndexDescriptor> listIndexes()
      Finds all the indices in the selected keyspace.
      Returns:
      list of table definitions

    • listIndexes

      public List<TableIndexDescriptor> listIndexes(ListIndexesOptions listIndexesOptions)
      Finds all the indices in the selected keyspace.
      Parameters:
      listIndexesOptions - options for the list indexes operation
      Returns:
      list of table definitions

    • registerListener

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