Insert a row (Java)
Inserts a single row 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 row and returns a TableInsertOneResult instance that includes the primary key of the inserted row and the schema of the primary key.
If a row with the specified primary key already exists in the table, the row will be overwritten with the specified column values. Unspecified columns will remain unchanged.
If any of the inserted columns use the wrong datatype or improper encoding, then the entire insert fails.
Parameters
Use the insertOne method, which belongs to the com.datastax.astra.client.tables.Table class.
Method signature
TableInsertOneResult insertOne(T row)TableInsertOneResult insertOne(
T row,
TableInsertOneOptions insertOneOptions
)| Name | Type | Summary |
|---|---|---|
|
|
An object that defines the row to insert.
The All primary key values are required. To reduce tombstones, you should not explicitly set a column to 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). |
|
Optional. The options for this operation, including the timeout. |
Examples
The following examples demonstrate how to insert a row into a table.
Insert a row
When you insert a row, you must specify a non-null value for each primary key column.
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.TableInsertOneResult;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Calendar;
import java.util.Date;
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 a row into the table
Calendar calendar = Calendar.getInstance();
calendar.set(2024, Calendar.DECEMBER, 18);
Date date = calendar.getTime();
Row row =
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"));
TableInsertOneResult result = table.insertOne(row);
System.out.println(result.getInsertedId());
}
}Insert a row 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.TableInsertOneResult;
import com.datastax.astra.client.tables.definition.rows.Row;
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 a row into the table
Row row =
new Row()
.addText("title", "Computed Wilderness")
.addText("author", "Ryan Eau")
.addVector(
"summary_genres_vector", new DataAPIVector(new float[] {0.08f, -0.62f, 0.39f}));
TableInsertOneResult result = table.insertOne(row);
System.out.println(result.getInsertedId());
}
}Insert a row with a map column that uses non-string keys
The Java client supports insertion of a row 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.TableInsertOneResult;
import com.datastax.astra.client.tables.definition.rows.Row;
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");
TableInsertOneResult result = table.insertOne(row);
System.out.println(result.getInsertedId());
}
}Client reference
For more information, see the client reference.
