Contact UsGet started

GetItem method

Written by
Updated at February 10, 2023

Returns a set of attributes for the item with the specified primary key.

If the desired item is not found, nothing is returned.

By default, the method returns potentially consistent data from the table. To get strongly consistent data, set ConsistentRead=true.

Request

The request contains data in JSON format.

{
   "AttributesToGet": [ "string" ],
   "ConsistentRead": boolean,
   "ExpressionAttributeNames": {
      "string" : "string"
   },
   "Key": {
      "string" : {
         "B": blob,
         "BOOL": boolean,
         "BS": [ blob ],
         "L": [
            "AttributeValue"
         ],
         "M": {
            "string" : "AttributeValue"
         },
         "N": "string",
         "NS": [ "string" ],
         "NULL": boolean,
         "S": "string",
         "SS": [ "string" ]
      }
   },
   "ProjectionExpression": "string",
   "ReturnConsumedCapacity": "string",
   "TableName": "string"
}

Parameters

Parameter Description
Key An associative array of attributes of the key/value type that represent the primary key of the extracted item.
For a primary key, specify all its key attributes. For a simple key, you only need to specify its value. For a composite primary key, specify the partition key and sort key values.

Type: AttributeValue object
Length: 1 - 65535 characters
Required: Yes
TableName Name of the table with the item to extract.
May contain a path in the directory hierarchy like path/to/table.

Type: String
Length: 3 - 255 characters.
Pattern: [a-zA-Z0-9_.-]+
Required: Yes
ConsistentRead Defines the read consistency model.
If true, strongly consistent reads are used. If false (default), sequential reads are used.

Type: Boolean
Required: No
ExpressionAttributeNames Placeholder that can be used in an expression instead of an attribute name. The placeholder must start with the hash character #.
Possible use cases:
  • If you need to specify an attribute whose name conflicts with the word reserved.
  • As a variable if the attribute name is used several times in an expression.
  • To prevent incorrect interpretation of special characters in the attribute name.
For example, the name of the Percentile attribute is in conflict with a reserved word and cannot be explicitly used in an expression. To get around this problem, in the ExpressionAttributeNames parameter, specify the placeholder: {"#P":"Percentile"}. Then, instead of the real attribute name, use #P.

Type: String
Length: 1 - 65535 characters.
Required: No
ProjectionExpression Expression that defines attributes to retrieve. The attributes must be comma-separated.
If the attribute names aren't specified explicitly, all item attributes are returned.

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

Type: String
Possible values: TOTAL | NONE
Required: No

Response

If successful, HTTP code 200 is returned.
The response is returned in JSON format.

{
   "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
   },
   "Item": {
      "string" : {
         "B": blob,
         "BOOL": boolean,
         "BS": [ blob ],
         "L": [
            "AttributeValue"
         ],
         "M": {
            "string" : "AttributeValue"
         },
         "N": "string",
         "NS": [ "string" ],
         "NULL": boolean,
         "S": "string",
         "SS": [ "string" ]
      }
   }
}

Parameters

Parameter Description
ConsumedCapacity Capacity units consumed by a delete operation.
Returned only if the ReturnConsumedCapacity parameter set to TOTAL is specified in the request.

Type: Object of the ConsumedCapacity type.
Item A set of attributes of the requested item.

Type: Associative array of the AttributeValue type.
Length: 1 - 65535 characters

Errors

Parameter Description
InternalServerError An internal error occurred on the server side.

HTTP status code: 500
ProvisionedThroughputExceededException You're sending requests too often. Try to increase the interval between requests.
If their number is not too large, Managed Service for YDB tries to process them all.

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

HTTP status code: 400
ResourceNotFoundException The specified table doesn't exist.

HTTP status code: 400

There may be common errors as well. These are errors that are common to all methods.

Previous
DescribeTimeToLive
Next
ListTables