Update a row (TypeScript)
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 (TypeScript).
|
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.
Returns a promise that resolves once the operation completes.
|
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 updateOne method, which belongs to the Table class.
Method signature
async updateOne(
filter: TableFilter<Schema>,
update: TableUpdateFilter<Schema>,
options?: {
timeout?: number | TimeoutDescriptor,
},
): void| 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 (TypeScript). 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. A timeout to impose on the underlying API request. |
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 (TypeScript).
If the row does not already exist and the update includes at least one non-null or non-empty value, creates a new row.
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace: "KEYSPACE_NAME",
});
const table = database.table("TABLE_NAME");
// Update a row
(async function () {
await table.updateOne(
{
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.
Otherwise, you can use an array of key-value pairs or a normal map.
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace: "KEYSPACE_NAME",
});
const table = database.table("TABLE_NAME");
// Update a row
(async function () {
await table.updateOne(
{
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"],
],
// 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.
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace: "KEYSPACE_NAME",
});
const table = database.table("TABLE_NAME");
// Update a row
(async function () {
await table.updateOne(
{
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.
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace: "KEYSPACE_NAME",
});
const table = database.table("TABLE_NAME");
// Update a row
(async function () {
await table.updateOne(
{
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.
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace: "KEYSPACE_NAME",
});
const table = database.table("TABLE_NAME");
// Update a row
(async function () {
await table.updateOne(
{
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.
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace: "KEYSPACE_NAME",
});
const table = database.table("TABLE_NAME");
// Update a row
(async function () {
await table.updateOne(
{
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.
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace: "KEYSPACE_NAME",
});
const table = database.table("TABLE_NAME");
// Update a row
(async function () {
await table.updateOne(
{
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.
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
keyspace: "KEYSPACE_NAME",
});
const table = database.table("TABLE_NAME");
// Update a row
(async function () {
await table.updateOne(
{
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.
