README.md

Batch statements

Quick overview

Group a set of statements into an atomic operation.

• create with BatchStatement.newInstance() or BatchStatement.builder().
• built-in implementation is immutable. Setters always return a new object, don't ignore the result.

---

Use BatchStatement to execute a set of queries as an atomic operation (refer to Batching inserts, updates and deletes to understand how to use batching effectively):

PreparedStatement preparedInsertExpense =
    session.prepare(
        "INSERT INTO cyclist_expenses (cyclist_name, expense_id, amount, description, paid) "
            + "VALUES (:name, :id, :amount, :description, :paid)");
SimpleStatement simpleInsertBalance =
    SimpleStatement.newInstance(
        "INSERT INTO cyclist_expenses (cyclist_name, balance) VALUES (?, 0) IF NOT EXISTS",
        "Vera ADRIAN");

BatchStatement batch =
  BatchStatement.newInstance(
      DefaultBatchType.LOGGED,
      simpleInsertBalance,
      preparedInsertExpense.bind("Vera ADRIAN", 1, 7.95f, "Breakfast", false));

session.execute(batch);

To create a new batch statement, use one of the static factory methods (as demonstrated above), or a builder:

BatchStatement batch =
    BatchStatement.builder(DefaultBatchType.LOGGED)
        .addStatement(simpleInsertBalance)
        .addStatement(preparedInsertExpense.bind("Vera ADRIAN", 1, 7.95f, "Breakfast", false))
        .build();

Keep in mind that batch statements are immutable, and every method returns a different instance:

// Won't work: the object is not modified in place:
batch.setExecutionProfileName("oltp");

// Instead, reassign the statement every time:
batch = batch.setExecutionProfileName("oltp");

As shown in the examples above, batches can contain any combination of simple statements and bound statements. A given batch can contain at most 65536 statements. Past this limit, addition methods throw an IllegalStateException.

In addition, simple statements with named parameters are currently not supported in batches (this is due to a protocol limitation that will be fixed in a future version). If you try to execute such a batch, an IllegalArgumentException is thrown.