Contact UsTry it for free
© 2026 Direct Cursus Technology L.L.C.

DeleteItem method

Written by
Updated at April 24, 2026

Deletes a table item by the specified primary key.

You can set a condition. An item will then be deleted only if the condition is met.

The method may return the attribute values as they were before the item was deleted.

Request

The request contains data in JSON format.

{
   "ConditionalOperator": "string",
   "ConditionExpression": "string",
   "Expected": {
      "string" : {
         "AttributeValueList": [
            {
               "B": blob,
               "BOOL": boolean,
               "BS": [ blob ],
               "L": [
                  "AttributeValue"
               ],
               "M": {
                  "string" : "AttributeValue"
               },
               "N": "string",
               "NS": [ "string" ],
               "NULL": boolean,
               "S": "string",
               "SS": [ "string" ]
            }
         ],
         "ComparisonOperator": "string",
         "Exists": boolean,
         "Value": {
            "B": blob,
            "BOOL": boolean,
            "BS": [ blob ],
            "L": [
               "AttributeValue"
            ],
            "M": {
               "string" : "AttributeValue"
            },
            "N": "string",
            "NS": [ "string" ],
            "NULL": boolean,
            "S": "string",
            "SS": [ "string" ]
         }
      }
   },
   "ExpressionAttributeNames": {
      "string" : "string"
   },
   "ExpressionAttributeValues": {
      "string" : {
         "B": blob,
         "BOOL": boolean,
         "BS": [ blob ],
         "L": [
            "AttributeValue"
         ],
         "M": {
            "string" : "AttributeValue"
         },
         "N": "string",
         "NS": [ "string" ],
         "NULL": boolean,
         "S": "string",
         "SS": [ "string" ]
      }
   },
   "Key": {
      "string" : {
         "B": blob,
         "BOOL": boolean,
         "BS": [ blob ],
         "L": [
            "AttributeValue"
         ],
         "M": {
            "string" : "AttributeValue"
         },
         "N": "string",
         "NS": [ "string" ],
         "NULL": boolean,
         "S": "string",
         "SS": [ "string" ]
      }
   },
   "ReturnConsumedCapacity": "string"
   "ReturnValues": "string",
   "TableName": "string"
}

Parameters

Parameter Description
Key Associative array of attribute names for AttributeValue objects that serves as a primary key of the item to delete.
For a simple primary key, you only need to specify its value.
For a composite primary key, specify the value of a partition key and a sort key.

Type: String
Length: 1 to 65,535 characters.
Required: Yes
TableName Name of the table containing the item to delete.
It may contain a path in the hierarchical directory structure in path/to/table format.

Type: String
Length: 3 to 255 characters.
Template: [a-zA-Z0-9_.-]+
Required: Yes
ConditionExpression Condition for deleting the item. The record will be deleted only if the condition is met.
The condition consists of:
  • Functions: attribute_exists | attribute_not_exists | attribute_type | contains | begins_with | size. Names are case-sensitive.
  • Comparison operators: = | <> | < | > | <= | >= | BETWEEN | IN
  • Logical operators: AND | OR | NOT

Type: String
Required: No
ExpressionAttributeNames Placeholder for an attribute name in an expression. The placeholder must start with the hash character, #.
You can use it in the following cases:
  • To specify an attribute whose name conflicts with a reserved word.
  • As a variable, if the attribute name is used multiple times in an expression.
  • To prevent incorrect interpretation of special characters in the attribute name.
For example, the Percentile attribute name conflicts with the reserved word, so you cannot use it explicitly in an expression. To fix this issue, specify the {"#P":"Percentile"} placeholder in the ExpressionAttributeNames parameter, and then, further on, use #P instead of the real attribute name.

Type: String
Length: 1 to 65,535 characters.
Required: No
ExpressionAttributeValues Placeholder for an attribute name in an expression, same as ExpressionAttributeNames. The placeholder must start with a colon, :.
For example, you need to check whether the value of the ProductStatus attribute was one of the following: Available | Backordered | Discontinued. To do this, first declare placeholders: { ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, ":disc":{"S":"Discontinued"} }. Now you can use them in the expression: ProductStatus IN (:avail, :back, :disc)

Type: String of the AttributeValue type
Required: No
ReturnConsumedCapacity Sets whether to return information about the consumed capacity.
  • TOTAL: Return.
  • NONE: Do not return.

Type: String
Possible values: TOTAL | NONE
Required: No
ReturnValues Use it if you need to get attributes of an item to delete.
Possible values:
  • ALL_OLD: Return the contents of the deleted item.
  • NONE (default): Do not return the contents of the deleted item.

Type: String
Required: No

Response

If successful, HTTP code 200 is returned.
You will get data in JSON format.

{
   "Attributes": {
      "string" : {
         "B": blob,
         "BOOL": boolean,
         "BS": [ blob ],
         "L": [
            "AttributeValue"
         ],
         "M": {
            "string" : "AttributeValue"
         },
         "N": "string",
         "NS": [ "string" ],
         "NULL": boolean,
         "S": "string",
         "SS": [ "string" ]
      }
   },
   "ConsumedCapacity": {
      "CapacityUnits": number,
      "GlobalSecondaryIndexes": {
         "string" : {
            "CapacityUnits": number,
            "ReadCapacityUnits": number,
            "WriteCapacityUnits": number
         }
      },
      "LocalSecondaryIndexes": {
         "string" : {
            "CapacityUnits": number,
            "ReadCapacityUnits": number,
            "WriteCapacityUnits": number
         }
      },
      "ReadCapacityUnits": number,
      "Table": {
         "CapacityUnits": number,
         "ReadCapacityUnits": number,
         "WriteCapacityUnits": number
      },
      "TableName": "string",
      "WriteCapacityUnits": number
   }
}

Parameters

Parameter Description
Attributes Associative array of the AttributeValue type containing the item representation before it was deleted.
It is returned only if you provide ReturnValues set to ALL_OLD in the request.

Type: Associative array of the AttributeValue type.
Length: 1 to 65,535 characters.
ConsumedCapacity Capacity units consumed by a delete operation.
It is returned only if you provide ReturnConsumedCapacity set to TOTAL in the request.

Type: Object of the ConsumedCapacity type.

Errors

Parameter Description
ConditionalCheckFailedException Failed to evaluate the condition specified in the operation.

HTTP status code: 400
InternalServerError An internal error occurred on the server side.

HTTP status code: 500
ItemCollectionSizeLimitExceededException Item collection size limit exceeded. This exception is only returned for tables with one or more local secondary indexes.

HTTP status code: 400
ProvisionedThroughputExceededException Your request rate is too high. Try to reduce the frequency of requests.
If their number is not too large, Managed Service for YDB will try to process them all.

HTTP status code: 400
RequestLimitExceeded The throughput capacity exceeds the set quota.

HTTP status code: 400
ResourceNotFoundException The requested table does not exist.

HTTP status code: 400
TransactionConflictException The operation is rejected because there is an ongoing transaction for the item.

HTTP status code: 400

There may be some common errors as well shared by all methods.

Previous
CreateTable
Next
DeleteTable