Update a row (Python)
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 (Python).
|
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
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.
Does not return anything.
|
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. |
Parameters
Use the update_one method, which belongs to the astrapy.Table class.
Method signature
update_one(
filter: Dict[str, Any],
update: Dict[str, Any],
*,
general_method_timeout_ms: int,
request_timeout_ms: int,
timeout_ms: int,
) -> None| 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 (Python). 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. |
|
|
Optional. The maximum time, in milliseconds, that the client should wait for the underlying HTTP request. This parameter is aliased as Default: The default value for the table. This default is 30 seconds unless you specified a different default when you initialized the |
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 (Python).
If the row does not already exist and the update includes at least one non-null or non-empty value, creates a new row.
The following example uses untyped documents or rows, but you can define a client-side type for your collection to help statically catch errors. For examples, see Typing support.
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace="KEYSPACE_NAME",
)
table = database.get_table("TABLE_NAME")
# Update a row
table.update_one(
{"title": "Hidden Shadows of the Past", "author": "John Anthony"},
{
"$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.
With the Python client, you can also use DataAPIMap to encode maps that use non-string keys.
Otherwise, you can use an array of key-value pairs or a normal map.
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.data_types import DataAPIMap
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace="KEYSPACE_NAME",
)
table = database.get_table("TABLE_NAME")
# Update a row
table.update_one(
{"title": "Hidden Shadows of the Past", "author": "John Anthony"},
{
"$set": {
# This map has non-string keys,
# so the update is an array of key-value pairs
"map_column_int_str": [[1, "value1"], [2, "value2"]],
# Alternatively, use DataAPIMap to encode maps with non-string keys
"map_column_int_str_2": DataAPIMap(
{1: "value1", 2: "value2"}
),
# This map does not have non-string keys,
# so the update does not need to be an array of key-value pairs
"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.
The following example uses untyped documents or rows, but you can define a client-side type for your collection to help statically catch errors. For examples, see Typing support.
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace="KEYSPACE_NAME",
)
table = database.get_table("TABLE_NAME")
# Update a row
table.update_one(
{"title": "Hidden Shadows of the Past", "author": "John Anthony"},
{
"$push": {
# Appends a single element to the "genres" list
"genres": "SciFi",
# Appends two elements to the "topics" list
"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.
The following example uses untyped documents or rows, but you can define a client-side type for your collection to help statically catch errors. For examples, see Typing support.
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.data_types import DataAPIMap
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace="KEYSPACE_NAME",
)
table = database.get_table("TABLE_NAME")
# Update a row
table.update_one(
{"title": "Hidden Shadows of the Past", "author": "John Anthony"},
{
"$push": {
# This update includes non-string keys,
# so the update is a key-value pair represented as an array
"map_column_int_str": [1, "value1"],
# This update does not include non-string keys,
# so the update can be a key-value pair represented as an array or a map
"map_column_str_str": {"key1": "value1"},
# When using $each, use an array of key-value pairs for non-string keys
"map_column_int_str_2": {
"$each": [[1, "value1"], [2, "value2"]]
},
# When using $each, use an array of key-value pairs or maps for string keys
"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.
The following example uses untyped documents or rows, but you can define a client-side type for your collection to help statically catch errors. For examples, see Typing support.
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace="KEYSPACE_NAME",
)
table = database.get_table("TABLE_NAME")
# Update a row
table.update_one(
{"title": "Hidden Shadows of the Past", "author": "John Anthony"},
{
"$pullAll": {
"genres": ["SciFi", "Romance"],
}
},
)Remove matches from map column
Use $pullAll to remove entries that match the specified keys from a map column.
The following example uses untyped documents or rows, but you can define a client-side type for your collection to help statically catch errors. For examples, see Typing support.
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace="KEYSPACE_NAME",
)
table = database.get_table("TABLE_NAME")
# Update a row
table.update_one(
{"title": "Hidden Shadows of the Past", "author": "John Anthony"},
{
"$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.
The following example uses untyped documents or rows, but you can define a client-side type for your collection to help statically catch errors. For examples, see Typing support.
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace="KEYSPACE_NAME",
)
table = database.get_table("TABLE_NAME")
# Update a row
table.update_one(
{"title": "Hidden Shadows of the Past", "author": "John Anthony"},
{"$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.
The following example uses untyped documents or rows, but you can define a client-side type for your collection to help statically catch errors. For examples, see Typing support.
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace="KEYSPACE_NAME",
)
table = database.get_table("TABLE_NAME")
# Update a row
table.update_one(
{"title": "Chemistry Club"},
{
"$set": {
"president": {
"email": "lisa@example.com",
"user_name": "lisa_m",
},
"vice_president": {
"email": "tanya@example.com",
"user_name": "tanya_o",
},
},
},
)Client reference
For more information, see the client reference.
