Update a row (HTTP)
|
For details about additional languages, see: |
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": ""
}
}
}
}'Update a map column
If the updated map includes non-string keys, you must use an array of key-value pairs to update the map column.
Otherwise, you can use an array of key-value pairs or a normal map.
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": {
"map_column_int_str": [
[1, "value1"],
[2, "value2"]
],
"map_column_str_str": {
"key1": "value1",
"key2": "value2"
}
}
}
}
}'Append to a list or set column
Use $push to append a single element to a list or set.
Use $push with $each to append multiple elements.
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": {
"$push": {
"genres": "SciFi",
"topics": {
"$each": ["robots", "AI"]
}
}
}
}
}'Append to a map column
Use $push to append a single key-value pair to a map.
Use $push with $each to append multiple key-value pairs.
If the appended key-value pair has a non-string key, you must represent the key-value pair as an array. Otherwise, you can either use an array or a normal map.
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": {
"$push": {
"map_column_int_str": [
1, "value1"
],
"map_column_str_str": {
"key1": "value1"
},
"map_column_int_str_2": {
"$each": [
[1, "value1"],
[2, "value2"]
]
},
"map_column_str_str_2": {
"$each": [
{"key1": "value1"},
["key2", "value2"]
]
}
}
}
}
}'Remove matches from a list or set column
Use $pullAll to remove the specified elements from a list or set.
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": {
"$pullAll": {
"genres": ["SciFi", "Romance"]
}
}
}
}'Remove matches from map column
Use $pullAll to remove entries that match the specified keys from a map column.
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": {
"$pullAll": {
"metadata": ["language", "edition"]
}
}
}
}'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": ""
}
}
}
}'Update a user-defined type column
If a column is a user-defined type, you must update the whole value.
You can’t update a partial value.
In the example below, president and vice_president both use the same user-defined type, which consists of an email and user_name field.
If the value type of a map, list, or set column is a user-defined type, you can only update the whole value, not a partial value, for each entry.
The $push, $each, and $pullAll operators work on map, list, and set columns that have a user-defined type as their value type.
For examples, see Update a map column, Append to a list or set column, Append to a map column, Remove matches from a list or set column, and Remove matches from map column.
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": "Chemistry Club"
},
"update": {
"$set": {
"president": {
"email": "lisa@example.com",
"user_name": "lisa_m"
},
"vice_president": {
"email": "tanya@example.com",
"user_name": "tanya_o"
}
}
}
}
}'