Update a row

This Astra DB Serverless feature is currently in public preview. Development is ongoing, and the features and functionality are subject to change. Astra DB Serverless, and the use of such, is subject to the DataStax Preview Terms.

The Data API tables commands are available through HTTP and the clients.

If you use a client, tables commands are available only in client versions 2.0-preview or later. For more information, see Data API client upgrade guide.

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.

Method signature

Python
TypeScript
Java
curl

The following method belongs to the astrapy.Table class.

update_one(
  filter: Dict[str, Any],
  update: Dict[str, Any],
  *,
  general_method_timeout_ms: int,
  request_timeout_ms: int,
  timeout_ms: int,
) -> None

The following method belongs to the Table class.

async updateOne(
  filter: TableFilter<WSchema>,
  update: TableUpdateFilter<WSchema>,
  timeout?: number | TimeoutDescriptor,
): void

The following methods belong to the com.datastax.astra.client.tables.Table class.

void updateOne(
  Filter filter,
  TableUpdateOperation update
)

void updateOne(
  Filter filter,
  TableUpdateOperation update,
  TableUpdateOneOptions options
)

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/TABLE_NAME" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "updateOne": {
    "filter": FILTER,
    "update": UPDATE
  }
}'

Result

Python
TypeScript
Java
curl

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 rows to disappear altogether when all of its columns are set to null.

This happens if the row was previously created from an update operation that had no pre-existing row to modify.

Updates the specified row.

Returns a promise that resolves once the operation completes.

A rare edge case, related to underlying Apache Cassandra® functionality, can cause rows to disappear altogether when all of its columns are set to null.

This happens if the row was previously created from an update operation that had no pre-existing row to modify.

Updates the specified row.

Does not return anything.

A rare edge case, related to underlying Apache Cassandra® functionality, can cause rows to disappear altogether when all of its columns are set to null.

This happens if the row was previously created from an update operation that had no pre-existing row to modify.

Updates the specified row.

A rare edge case, related to underlying Apache Cassandra® functionality, can cause rows to disappear altogether when all of its columns are set to null.

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
  }
}

Parameters

Python
TypeScript
Java
curl

Name Type Summary

Name	Type	Summary
`filter`	`dict`	Describes the row to update (or upsert) by its primary key values. You cannot filter on non-primary keys. Only the the `$eq` operator is allowed.
`update`	`dict`	The update prescription to apply to the row. Use the `$set` and `$unset` operators to change or remove values from specified columns. For example: `{ "$set": { "COLUMN": "NEW_VALUE" } }` `{ "$unset": { "COLUMN": "" } }` The target value of `$unset` doesn’t matter; use of the `$unset` operator changes the given columns to `null` or the equivalent empty form, such as `[]` or `{}` for `map`, `list`, and `set` types. You can’t use `updateOne` to modify primary key values. If you need to modify a row’s primary key, you must delete the row and then insert a new row with the desired primary key values.
`general_method_timeout_ms`	`int \| None`	A timeout, in milliseconds, to impose on the underlying API request. If not provided, the Table defaults apply. This parameter is aliased as `request_timeout_ms` and `timeout_ms` for convenience.

filter

dict

Describes the row to update (or upsert) by its primary key values.

You cannot filter on non-primary keys.

Only the the $eq operator is allowed.

update

dict

The update prescription to apply to the row. Use the $set and $unset operators to change or remove values from specified columns. For example:

{ "$set": { "COLUMN": "NEW_VALUE" } }
{ "$unset": { "COLUMN": "" } }

The target value of $unset doesn’t matter; use of the $unset operator changes the given columns to null or the equivalent empty form, such as [] or {} for map, list, and set types.

You can’t use updateOne to modify primary key values. If you need to modify a row’s primary key, you must delete the row and then insert a new row with the desired primary key values.

general_method_timeout_ms

int | None

A timeout, in milliseconds, to impose on the underlying API request. If not provided, the Table defaults apply. This parameter is aliased as request_timeout_ms and timeout_ms for convenience.

Name Type Summary

Name	Type	Summary
`filter`	`TableFilter`	Describes the row to update (or upsert) by its primary key values. You cannot filter on non-primary keys. Only the the `$eq` operator is allowed.
`update`	`TableUpdateFilter`	The update prescription to apply to the row. Use the `$set` and `$unset` operators to change or remove values from specified columns. The target value of `$unset` doesn’t matter; use of the `$unset` operator changes the given columns to `null` or the equivalent empty form, such as `[]` or `{}` for `map`, `list`, and `set` types. You can’t use `updateOne` to modify primary key values. If you need to modify a row’s primary key, you must delete the row and then insert a new row with the desired primary key values.
`timeout?`	`WithTimeout`	The client-side timeout for this operation.

filter

TableFilter

Describes the row to update (or upsert) by its primary key values.

You cannot filter on non-primary keys.

Only the the $eq operator is allowed.

update

TableUpdateFilter

The update prescription to apply to the row. Use the $set and $unset operators to change or remove values from specified columns.

The target value of $unset doesn’t matter; use of the $unset operator changes the given columns to null or the equivalent empty form, such as [] or {} for map, list, and set types.

You can’t use updateOne to modify primary key values. If you need to modify a row’s primary key, you must delete the row and then insert a new row with the desired primary key values.

timeout?

WithTimeout

The client-side timeout for this operation.

Name Type Summary

Name	Type	Summary
`filter`	`Filter`	Describes the row to update (or upsert) by its primary key values. You cannot filter on non-primary keys. Only the the `$eq` operator is allowed. Filters can be instantiated with its constructor and specialized with method `where(..)` or leverage the class `Filters`
`operation`	`TableUpdateOperation`	A wrapper for the different options and specialization of this search.
`options`	`TableUpdateOneOptions`	Operations to be applied to the update operation. It could be `set` or `unset` operations.

filter

Filter

Describes the row to update (or upsert) by its primary key values.

You cannot filter on non-primary keys.

Only the the $eq operator is allowed.

Filters can be instantiated with its constructor and specialized with method where(..) or leverage the class Filters

operation

TableUpdateOperation

A wrapper for the different options and specialization of this search.

options

TableUpdateOneOptions

Operations to be applied to the update operation. It could be set or unset operations.

TableUpdateOperation

Method Summary

Method	Summary
`set(String column, Object value)`	Set a column to a new value.
`unset(String column, Object value)`	Unset a column, setting it to a provided empty value, `""`, `null`, `Set.of()`, etc.
`unset(String… column)`	Unset a list of columns.

set(String column, Object value)

Set a column to a new value.

unset(String column, Object value)

Unset a column, setting it to a provided empty value, "", null, Set.of(), etc.

unset(String… column)

Unset a list of columns.

TableUpdateOneOptions

Name Type Summary

Name	Type	Summary
`timeout`	`long` or `Duration`	Overrides the client-side timeout for this operation. If not provided, the `Table` defaults apply.

timeout

long or Duration

Overrides the client-side timeout for this operation. If not provided, the Table defaults apply.

Name Type Summary

Name	Type	Summary
`updateOne`	`command`	Data API command to update one row in a table.
`filter`	`object`	Describes the row to update (or upsert) by its primary key values. You cannot filter on non-primary keys. Only the the `$eq` operator is allowed.
`update`	`object`	The update prescription to apply to the row. Use the `$set` and `$unset` operators to change or remove values from specified columns. For example: `{ "$set": { "COLUMN": "NEW_VALUE" } }` `{ "$unset": { "COLUMN": "" } }` The target value of `$unset` doesn’t matter; use of the `$unset` operator changes the given columns to `null` or the equivalent empty form, such as `[]` or `{}` for `map`, `list`, and `set` types. You can’t use `updateOne` to modify primary key values. If you need to modify a row’s primary key, you must delete the row and then insert a new row with the desired primary key values.

updateOne

command

Data API command to update one row in a table.

filter

object

Describes the row to update (or upsert) by its primary key values.

You cannot filter on non-primary keys.

Only the the $eq operator is allowed.

update

object

The update prescription to apply to the row. Use the $set and $unset operators to change or remove values from specified columns. For example:

{ "$set": { "COLUMN": "NEW_VALUE" } }
{ "$unset": { "COLUMN": "" } }

The target value of $unset doesn’t matter; use of the $unset operator changes the given columns to null or the equivalent empty form, such as [] or {} for map, list, and set types.

You can’t use updateOne to modify primary key values. If you need to modify a row’s primary key, you must 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.

If the row does not already exist and the update includes at least one non-null or non-empty value, creates a new row.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient

# Get an existing table
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
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": ""
        }
    }
)

import { DataAPIClient } from '@datastax/astra-db-ts';

// Get an existing table
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
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: ""
      },
    }
  );
})();

package com.example;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.TableUpdateOperation;

import java.util.Arrays;
import java.util.Map;
import java.util.Optional;

public class UpdateOne {

    public static void main(String[] args) {
        // Get an existing table
        Table<Row> table = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_API_ENDPOINT")
            .getTable("TABLE_NAME");

        // Update a row
        Filter filter = new Filter(Map.of(
          "title", "Hidden Shadows of the Past",
          "author", "John Anthony"
        ));
        TableUpdateOperation update = new TableUpdateOperation()
            .set("rating", 4.5)
            .set("genres", Arrays.asList("Fiction", "Drama"))
            .unset("borrower");
        table.updateOne(filter, update);
    }
}

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_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 will produce a tombstone. Excessive tombstones can impact query performance. For more information see, What are tombstones.

Python
TypeScript
Java
curl

table.update_one(
    {
      "id": "1013dr3"
    },
    {
        "$unset": {
            "genres": ""
        }
    }
)

(async function () {
  await table.updateOne(
    {
      id: "1013dr3"
    },
    {
      $unset: {
        genres: ""
      },
    }
  );
})();

Update update = Updates
  .unset("genres");

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "updateOne": {
    "filter": {
      "id": "1013dr3"
    },
    "update": {
        "$unset": {
            "genres": ""
        }
    }
  }
}'

Client reference

Python
TypeScript
Java
curl

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

Update a row

Method signature

Result

Parameters

Examples

Update multiple columns

Unset columns

Client reference

Was this helpful?

Give Feedback