Insert a row (HTTP)
|
For details about additional languages, see: |
|
Tables with the Data API are currently in public preview. Development is ongoing, and the features and functionality are subject to change. Hyper-Converged Database (HCD), and the use of such, is subject to the DataStax Preview Terms. |
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 (HTTP).
For general information about working with tables and rows, see About tables with the Data API (HTTP).
|
Ready to write code? See the examples for this method to get started. |
Result
Inserts the specified row. In the JSON response, status.primaryKeySchema is an object that describes the table’s primary key definition, including column names and types. status.insertedIds is a nested array that contains the values inserted for each primary key column.
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.
Example response for a single-column primary key:
{
"status": {
"primaryKeySchema": {
"email": {
"type": "ascii"
}
},
"insertedIds": [
[
"tal@example.com"
]
]
}
}Example response for a multi-column primary key:
{
"status": {
"primaryKeySchema": {
"email": {
"type": "ascii"
},
"graduation_year": {
"type": "int"
}
},
"insertedIds": [
[
"tal@example.com",
2014
]
]
}
}Signature
Use the insertOne command.
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"insertOne": {
"document": ROW
}
}'Parameters
| Name | Type | Summary |
|---|---|---|
|
|
An object that defines the row to insert. 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 (HTTP). |
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.
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"insertOne": {
"document": {
"title": "Computed Wilderness",
"author" :"Ryan Eau",
"number_of_pages": 432,
"due_date": "2024-12-18",
"genres": ["History", "Biography"]
}
}
}'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 (HTTP). To add a vector column to an existing table, see Alter a table (HTTP).
All embeddings in the column should use the same provider, model, and dimensions. Mismatched embeddings can cause inaccurate vector searches.
You can provide the vector embeddings as an array of floats, or you can use $binary to provide the vector embeddings as a Base64-encoded string.
$binary can be more performant.
For more information about how to convert an array of floats to a Base64-encoded string, see BLOB type (HTTP).
- Array of floats
-
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \ --header "Token: APPLICATION_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "insertOne": { "document": { "title": "Computed Wilderness", "author" :"Ryan Eau", "summary_genres_vector": [0.08, -0.62, 0.39] } } }' - $binary
-
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \ --header "Token: APPLICATION_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "insertOne": { "document": { "title": "Computed Wilderness", "author" :"Ryan Eau", "summary_genres_vector": {"$binary": "PaPXCr8euFI+x64U"} } } }'
