Update 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. |
Updates a single row in a table.
If the row does not already exist and the update includes at least one non-null or non-empty value, creates a new row.
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
Updates the specified row.
If no row matches the specified primary key and the update includes at least one non-null or non-empty value, then a new row is created with the values specified $set values and primary key values.
Any omitted or $unset columns are set to null in the new row.
|
A rare edge case, related to underlying Apache Cassandra® functionality, can cause a row to disappear altogether when all of its columns are set to This happens if the row was previously created from an update operation that had no pre-existing row to modify. |
Always returns a status.matchedCount of 1, a status.modifiedCount of 1, and a status.upsertCount of 0, regardless of the outcome.
Example response:
{
"status": {
"matchedCount": 1,
"modifiedCount": 1,
"upsertCount": 0
}
}Signature
Use the updateOne 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 '{
"updateOne": {
"filter": FILTER,
"update": UPDATE
}
}'Parameters
| Name | Type | Summary |
|---|---|---|
|
|
Describes the full primary key of the row to update. For this method, the filter can only use the |
|
|
Defines the update using Data API operators. For a list of available operators and more examples, see Update operators for tables (HTTP). You cannot update primary key values. If you need to modify a row’s primary key, delete the row and then insert a new row with the desired primary key values. |
Examples
The following examples demonstrate how to update a row in a table.
Update multiple columns
You can combine multiple operators and properties in a single call. For the full list of operators, see Update operators for tables (HTTP).
If the row does not already exist and the update includes at least one non-null or non-empty value, creates a new row.
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"updateOne": {
"filter": {
"title": "Hidden Shadows of the Past",
"author": "John Anthony"
},
"update": {
"$set": {
"rating": 4.5,
"genres": ["Fiction", "Drama"]
},
"$unset": {
"borrower": ""
}
}
}
}'Unset columns
To unset a column, you can use the $unset operator, or you can use the $set operator and an empty value.
Either operation will delete the value in the specified column.
Unsetting a column produces a tombstone. Excessive tombstones can impact query performance.
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"updateOne": {
"filter": {
"title": "Hidden Shadows of the Past",
"author": "John Anthony"
},
"update": {
"$unset": {
"genres": ""
}
}
}
}'