Scan method

Written by

Updated at February 10, 2023

Request
- Parameters
Response
- Parameters
Errors

Returns items and attributes from the specified table.

By default, all items are returned, but no more than 1 MB at a time or up to 100 entries. If there is more data in the table, the LastEvaluatedKey parameter returns the last primary key evaluated by the scan operation. You can use it to continue scanning.

Filters specified in the FilterExpression parameter only apply after the main selection.

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.

{
   "ConditionalOperator": "string",
   "ConsistentRead": boolean,
   "ExclusiveStartKey": {
      "string" : {
         "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" ]
      }
   },
   "FilterExpression": "string",
   "IndexName": "string",
   "Limit": number,
   "ProjectionExpression": "string",
   "ReturnConsumedCapacity": "string",
   "ScanFilter": {
      "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"
      }
   },
   "Select": "string",
   "TableName": "string"
}

Parameters

Parameter	Description
`TableName`	Name of the table with data. 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. This parameter isn't supported for global secondary indexes. If you try to scan a secondary index set to `true`, the method returns the `ValidationException`. Type: Boolean Required: No
`ExclusiveStartKey`	Primary key of the item that the method starts searching from. If the method returned `LastEvaluatedKey` in response to the previous request, use this value to continue the search from the place where the method stopped last time. Type: Object of the `AttributeValue` type Key length: Up to 65535 characters. 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
`ExpressionAttributeValues`	Placeholder that can be used in an expression instead of an attribute value, similar to `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"} }`. After that, you can use them in the expression: `ProductStatus IN (:avail, :back, :disc)` Type: String of the `AttributeValue` type Required: No
`FilterExpression`	Conditions to apply after the initial data selection. Items that don't meet this condition won't be included in the final response. Type: String Required: No
`IndexName`	The name of the global secondary index to scan. Note that if you use this parameter, you must also specify `TableName`. Type: String Length: 3 - 255 characters Template: [a-zA-Z0-9_.-]+ Required: No
`Limit`	The maximum number of items to be evaluated for the selection. As soon as the method processes the specified number of items, it stops and returns the result to where it stopped. In this case, the `LastEvaluatedKey` parameter contains the last key that the method evaluated. You can use it to continue scanning from where the method stopped. Type: Integer Range: 1 is the minimum value. 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
`Select`	Attributes to return. Possible values: `ALL_ATTRIBUTES` (default): Returns all attributes of an item from a table or index. `COUNT`: returns only the number of matching attributes. Type: String Acceptable values: `ALL_ATTRIBUTES` \| `COUNT` 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
   },
   "Count": number,
   "Items": [
      {
         "string" : {
            "B": blob,
            "BOOL": boolean,
            "BS": [ blob ],
            "L": [
               "AttributeValue"
            ],
            "M": {
               "string" : "AttributeValue"
            },
            "N": "string",
            "NS": [ "string" ],
            "NULL": boolean,
            "S": "string",
            "SS": [ "string" ]
         }
      }
   ],
   "LastEvaluatedKey": {
      "string" : {
         "B": blob,
         "BOOL": boolean,
         "BS": [ blob ],
         "L": [
            "AttributeValue"
         ],
         "M": {
            "string" : "AttributeValue"
         },
         "N": "string",
         "NS": [ "string" ],
         "NULL": boolean,
         "S": "string",
         "SS": [ "string" ]
      }
   },
   "ScannedCount": number
}

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.
`Count`	Count of items in a response. If you used `FilterExpression`, then it's equal to the number of items returned after applying the filter. Type: Integer
`Items`	Array of attributes that match the scan criteria. Each item in the array consists of the name and value of this attribute. Type: Array of objects of the `AttributeValue` type Key length: 1 - 65535 characters.
`LastEvaluatedKey`	Primary key of the item where the scan stopped. Use this value to continue from where you stopped. If the `LastEvaluatedKey` is empty, it means that the method processed all items and there is nothing more to return. Type: Associative array of the `AttributeValue` type Key length: 1 - 65535 characters.
`ScannedCount`	Count of items found before using the `FilterExpression` filters. Type: Integer

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.

Scan method

RequestRequest

ParametersParameters

ResponseResponse

ParametersParameters

ErrorsErrors

Was the article helpful?

Request

Parameters

Response

Parameters

Errors