Scan method
Written by
Updated at February 10, 2023
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 typeKey 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:
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 typeRequired: 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.
Type: String Possible values: TOTAL | NONE Required: No |
Select |
Attributes to return. Possible values:
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 typeKey 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 typeKey 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.