Insert rows (Java)

Inserts multiple rows into a table.

This method can insert a row in an existing CQL table, but the Data API does not support all CQL data types or modifiers. For more information, see Data type compatibility in tables (Java).

For general information about working with tables and rows, see About tables with the Data API (Java).

Ready to write code? See the examples for this method to get started. If you are new to the Data API, check out the quickstart.

Result

Inserts the specified rows and returns a TableInsertManyResult instance that includes the primary keys of the inserted rows and the schema of the primary key.

If a row with the specified primary key already exists in the table, the row is overwritten with the specified column values. Unspecified columns remain unchanged.

If a row fails to insert and the insertions are sequential (the ordered property in TableInsertManyOptions is true), then that row and all subsequent rows are not inserted. The resulting error message indicates the first row that failed to insert.

If a row fails to insert and the insertions are not sequential (the ordered property in TableInsertManyOptions is false), the operation will try to insert the remaining rows and then throw an error. The error indicates which rows were successfully inserted and the problems with the failed rows.

Example response:

{
  "status": {
    "primaryKeySchema": {
      "match_id": {
        "type": "text"
      },
      "round": {
        "type": "int"
      }
    },
    "insertedIds": [
      ["fight4",1 ],
      ["fight5",1],
      ["fight5",2]
    ]
  }
}

Parameters

Use the insertMany method, which belongs to the com.datastax.astra.client.tables.Table class.

Method signature

TableInsertManyResult insertMany(
  List<? extends T> rows,
  TableInsertManyOptions options
)

TableInsertManyResult insertMany(
  List<? extends T> rows
)

Name Type Summary

Name	Type	Summary
`rows`	`List<Row>`	The list of `Rows` to insert, where each `Row` defines a row to insert. All primary key values are required. To reduce tombstones, you should not explicitly set a column to `null`. The table definition determines the columns in the row, the type for each column, and the primary key. To get this information, see List table metadata (Java).
`options`	`TableInsertManyOptions`	Optional. The options for this operation. See Methods of `TableInsertManyOptions` for more details.

rows

List<Row>

The list of Rows to insert, where each Row defines a row to insert.

All primary key values are required.

To reduce tombstones, you should not explicitly set a column to null.

The table definition determines the columns in the row, the type for each column, and the primary key. To get this information, see List table metadata (Java).

options

TableInsertManyOptions

Optional. The options for this operation. See Methods of TableInsertManyOptions for more details.

Methods of `TableInsertManyOptions`
Method	Parameters	Summary
`ordered()`	`bool`	Whether to insert the rows sequentially. If false, the rows are inserted in an arbitrary order with possible concurrency. This results in a much higher insert throughput than an equivalent ordered insertion. Default: false
`concurrency()`	`int`	The maximum number of concurrent requests to the API at a given time. For ordered insertions, must be 1 or unspecified.
`chunkSize()`	`int`	The number of rows to insert in a single API request. DataStax recommends that you leave this unspecified to use the system default.

Examples

The following examples demonstrate how to insert multiple rows into a table.

Insert rows

When you insert rows, you must specify a non-null value for each primary key column for each row. Non-primary key columns are optional. To reduce tombstones, you should not explicitly set a column to null.

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.results.TableInsertManyResult;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Calendar;
import java.util.Date;
import java.util.List;
import java.util.Set;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getTable("TABLE_NAME");

    // Insert rows into the table
    Calendar calendar = Calendar.getInstance();
    calendar.set(2024, Calendar.DECEMBER, 18);
    Date date = calendar.getTime();
    Row row1 =
        new Row()
            .addText("title", "Computed Wilderness")
            .addText("author", "Ryan Eau")
            .addInt("number_of_pages", 432)
            .addDate("due_date", date)
            .addSet("genres", Set.of("History", "Biography"));
    Row row2 =
        new Row()
            .addText("title", "Desert Peace")
            .addText("author", "Walter Dray")
            .addInt("number_of_pages", 355)
            .addFloat("rating", 4.5f);
    TableInsertManyResult result = table.insertMany(List.of(row1, row2));
    System.out.println(result.getInsertedIds());
  }
}

Insert rows with vector embeddings

You can only insert vector embeddings into vector columns.

To create a table with a vector column, see Create a table (Java). To add a vector column to an existing table, see Alter a table (Java).

All embeddings in the column should use the same provider, model, and dimensions. Mismatched embeddings can cause inaccurate vector searches.

You can use the DataAPIVector class to binary-encode your vector embeddings. DataStax recommends that you always use a DataAPIVector object instead of a list of floats to improve performance.

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.core.vector.DataAPIVector;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.results.TableInsertManyResult;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.List;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getTable("TABLE_NAME");

    // Insert rows into the table
    Row row1 =
        new Row()
            .addText("title", "Computed Wilderness")
            .addText("author", "Ryan Eau")
            .addVector(
                "summary_genres_vector", new DataAPIVector(new float[] {0.08f, -0.62f, 0.39f}));
    Row row2 =
        new Row()
            .addText("title", "Desert Peace")
            .addText("author", "Walter Dray")
            .addVector(
                "summary_genres_vector", new DataAPIVector(new float[] {0.12f, 0.53f, 0.32f}));
    TableInsertManyResult result = table.insertMany(List.of(row1, row2));
    System.out.println(result.getInsertedIds());
  }
}

Insert rows with a map column that uses non-string keys

The Java client supports insertion of rows with a map column that includes non-string keys. (You don’t need to use an array of key-value pairs to represent the map column.)

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.results.TableInsertManyResult;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.List;
import java.util.Map;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getTable("TABLE_NAME");

    // This map has non-string keys,
    // but the insertion can still be represented as a map
    // instead of an array of key-value pairs
    Map<Integer, String> mapColumn1 = Map.of(1, "value1", 2, "value2");

    // This map does not have non-string keys
    Map<String, String> mapColumn2 = Map.of("key1", "value1", "key2", "value2");

    Row row =
        new Row()
            .addMap("map_column_int_str", mapColumn1)
            .addMap("map_column_str_str", mapColumn2)
            .addText("title", "Once in a Living Memory")
            .addText("author", "Kayla McMaster");

    TableInsertManyResult result = table.insertMany(List.of(row));
  }
}

Insert rows and specify insertion behavior

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableInsertManyOptions;
import com.datastax.astra.client.tables.commands.results.TableInsertManyResult;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Calendar;
import java.util.Date;
import java.util.List;
import java.util.Set;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getTable("TABLE_NAME");

    // Define the insertion options
    TableInsertManyOptions options =
        new TableInsertManyOptions().chunkSize(20).concurrency(3).ordered(false);

    // Insert rows into the table
    Calendar calendar = Calendar.getInstance();
    calendar.set(2024, Calendar.DECEMBER, 18);
    Date date = calendar.getTime();
    Row row1 =
        new Row()
            .addText("title", "Computed Wilderness")
            .addText("author", "Ryan Eau")
            .addInt("number_of_pages", 432)
            .addDate("due_date", date)
            .addSet("genres", Set.of("History", "Biography"));
    Row row2 =
        new Row()
            .addText("title", "Desert Peace")
            .addText("author", "Walter Dray")
            .addInt("number_of_pages", 355)
            .addFloat("rating", 4.5f);
    TableInsertManyResult result = table.insertMany(List.of(row1, row2), options);
    System.out.println(result.getInsertedIds());
  }
}

Client reference

For more information, see the client reference.

Insert rows (Java)

Result

Parameters

Examples

Insert rows

Insert rows with vector embeddings

Insert rows with a map column that uses non-string keys

Insert rows and specify insertion behavior

Client reference

Was this helpful?

Give Feedback