The Scan operation returns one or more items and item attributes by accessing every item in the table. To have DynamoDB return fewer items, you can provide a ScanFilter .
If the total number of scanned items exceeds the maximum data set size limit of 1 MB, the scan stops and results are returned to the user with a LastEvaluatedKey to continue the scan in a subsequent operation. The results also include the number of items exceeding the limit. A scan can result in no table data meeting the filter criteria.
The result set is eventually consistent.
By default, Scan operations proceed sequentially; however, for faster performance on large tables, applications can request a parallel Scan by specifying the Segment and TotalSegments parameters. For more information, see Parallel Scan in the Amazon DynamoDB Developer Guide.
C# |
public class ScanRequest : AmazonWebServiceRequest
All Members | Constructors | Methods | Properties | ||
Icon | Member | Description |
---|---|---|
ScanRequest()()()() | Initializes a new instance of the ScanRequest class | |
AttributesToGet |
The names of one or more attributes to retrieve. If no attribute names are specified, then all attributes will be returned. If any of the
requested attributes are not found, they will not appear in the result. Note that AttributesToGet has no effect on provisioned
throughput consumption. DynamoDB determines capacity units consumed based on item size, not on the amount of data that is returned to an
application.
Constraints: | |
ConditionalOperator |
A logical operator to apply to the conditions in the ScanFilter map:
Constraints: | |
Equals(Object) | (Inherited from Object.) | |
ExclusiveStartKey |
The primary key of the first item that this operation will evaluate. Use the value that was returned for LastEvaluatedKey in the
previous operation. The data type for ExclusiveStartKey must be String, Number or Binary. No set data types are allowed. In a
parallel scan, a Scan request that includes ExclusiveStartKey must specify the same segment whose previous Scan
returned the corresponding value of LastEvaluatedKey.
| |
GetHashCode()()()() | Serves as a hash function for a particular type. (Inherited from Object.) | |
GetType()()()() | Gets the type of the current instance. (Inherited from Object.) | |
Limit |
The maximum number of items to evaluate (not necessarily the number of matching items). If DynamoDB processes the number of items up to the
limit while processing the results, it stops the operation and returns the matching values up to that point, and a LastEvaluatedKey
to apply in a subsequent operation, so that you can pick up where you left off. Also, if the processed data set size exceeds 1 MB before
DynamoDB reaches this limit, it stops the operation and returns the matching values up to the limit, and a LastEvaluatedKey to apply
in a subsequent operation to continue the operation. For more information see Query and Scan in the Amazon DynamoDB Developer
Guide.
Constraints: | |
ReturnConsumedCapacity |
If set to TOTAL, the response includes ConsumedCapacity data for tables and indexes. If set to INDEXES, the response
includes ConsumedCapacity for indexes. If set to NONE (the default), ConsumedCapacity is not included in the response.
Constraints: | |
ScanFilter |
Evaluates the scan results and returns only the desired values. If you specify more than one condition in the ScanFilter map, then by
default all of the conditions must evaluate to true. In other words, the conditions are ANDed together. (You can use the
ConditionalOperator parameter to OR the conditions instead. If you do this, then at least one of the conditions must evaluate to
true, rather than all of them.) Each ScanFilter element consists of an attribute name to compare, along with the following:
| |
Segment |
For a parallel Scan request, Segment identifies an individual segment to be scanned by an application worker. Segment IDs are
zero-based, so the first segment is always 0. For example, if you want to scan a table using four application threads, the first thread
would specify a Segment value of 0, the second thread would specify 1, and so on. The value of LastEvaluatedKey returned from
a parallel Scan request must be used as ExclusiveStartKey with the same Segment ID in a subsequent Scan operation. The
value for Segment must be greater than or equal to 0, and less than the value provided for TotalSegments. If you specify
Segment, you must also specify TotalSegments.
Constraints: | |
Select |
The attributes to be returned in the result. You can retrieve all item attributes, specific item attributes, or the count of matching items.
Constraints: | |
TableName |
The name of the table containing the requested items.
Constraints: | |
ToString()()()() | Returns a string that represents the current object. (Inherited from Object.) | |
TotalSegments |
For a parallel Scan request, TotalSegments represents the total number of segments into which the Scan operation will
be divided. The value of TotalSegments corresponds to the number of application workers that will perform the parallel scan. For
example, if you want to scan a table using four application threads, you would specify a TotalSegments value of 4. The value for
TotalSegments must be greater than or equal to 1, and less than or equal to 4096. If you specify a TotalSegments value of 1,
the Scan will be sequential rather than parallel. If you specify TotalSegments, you must also specify Segment.
Constraints: | |
WithAttributesToGet(array<String>[]()[][]) | Obsolete.
Adds elements to the AttributesToGet collection
| |
WithAttributesToGet(IEnumerable<(Of <<'(String>)>>)) | Obsolete.
Adds elements to the AttributesToGet collection
| |
WithConditionalOperator(String) | Obsolete.
Sets the ConditionalOperator property
| |
WithExclusiveStartKey(array<KeyValuePair<(Of <<'(String, AttributeValue>)>>)>[]()[][]) | Obsolete.
Adds the KeyValuePairs to the ExclusiveStartKey dictionary.
| |
WithLimit(Int32) | Obsolete.
Sets the Limit property
| |
WithReturnConsumedCapacity(String) | Obsolete.
Sets the ReturnConsumedCapacity property
| |
WithScanFilter(array<KeyValuePair<(Of <<'(String, Condition>)>>)>[]()[][]) | Obsolete.
Adds the KeyValuePairs to the ScanFilter dictionary.
| |
WithSegment(Int32) | Obsolete.
Sets the Segment property
| |
WithSelect(String) | Obsolete.
Sets the Select property
| |
WithTableName(String) | Obsolete.
Sets the TableName property
| |
WithTotalSegments(Int32) | Obsolete.
Sets the TotalSegments property
|
The following example shows how to scan items in a table.
Note: the Scan operation goes through every item in the table
to check if the item matches all the scan conditions. This makes
the Scan operation particularly slow and expensive (in terms of provisioned throughput).
We will now retrieve all items where the Pages attribute is greater
than the numerical value "200" and where the Title attribute contains
the string "Adventures".
// Create a client AmazonDynamoDBClient client = new AmazonDynamoDBClient(); // Define scan conditions Dictionary<string, Condition> conditions = new Dictionary<string, Condition>(); // Title attribute should contain the string "Adventures" Condition titleCondition = new Condition(); titleCondition.WithComparisonOperator("CONTAINS"); titleCondition.WithAttributeValueList(new AttributeValue { S = "Adventures" }); conditions["Title"] = titleCondition; // Pages attributes must be greater-than the numeric value "200" Condition pagesCondition = new Condition(); pagesCondition.WithComparisonOperator("GT"); pagesCondition.WithAttributeValueList(new AttributeValue { N = "200" }); conditions["Pages"] = pagesCondition; // Define marker variable Dictionary<string, AttributeValue> startKey = null; do { // Create Scan request ScanRequest request = new ScanRequest { TableName = "SampleTable", ExclusiveStartKey = startKey, ScanFilter = conditions }; // Issue request ScanResult result = client.Scan(request).ScanResult; // View all returned items List<Dictionary<string, AttributeValue>> items = result.Items; foreach (Dictionary<string, AttributeValue> item in items) { Console.WriteLine("Item:"); foreach (var keyValuePair in item) { Console.WriteLine("{0} : S={1}, N={2}, SS=[{3}], NS=[{4}]", keyValuePair.Key, keyValuePair.Value.S, keyValuePair.Value.N, string.Join(", ", keyValuePair.Value.SS ?? new List<string>()), string.Join(", ", keyValuePair.Value.NS ?? new List<string>())); } } // Set marker variable startKey = result.LastEvaluatedKey; } while (startKey != null);
The following example shows how we can utilize parallel scan to partition a table into
10 segments and scan each segment in a separate thread.
To avoid resource contention between threads, the results will be written into 10 separate
files. Each segment will have a file of its own.
// Create a client
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
// Define scan conditions
Dictionary<string, Condition> conditions = new Dictionary<string, Condition>();
// Pages attributes must be greater-than the numeric value "200"
Condition pagesCondition = new Condition();
pagesCondition.WithComparisonOperator("GT");
pagesCondition.WithAttributeValueList(new AttributeValue { N = "200" });
conditions["Pages"] = pagesCondition;
// Setup 10 simultaneous threads, each thread calling Scan operation
// with its own segment value.
int totalSegments = 10;
Parallel.For(0, totalSegments, segment =>
{
// Define marker variable
Dictionary<string, AttributeValue> startKey = null;
do
{
// Create Scan request
ScanRequest request = new ScanRequest
{
TableName = "SampleTable",
ExclusiveStartKey = startKey,
ScanFilter = conditions,
// Total segments to split the table into
TotalSegments = totalSegments,
// Current segment to scan
Segment = segment
};
// Issue request
ScanResult result = client.Scan(request).ScanResult;
// Write returned items to file
string path = string.Format("ParallelScan-{0}-of-{1}.txt", totalSegments, segment);
List<Dictionary<string, AttributeValue>> items = result.Items;
using (Stream stream = File.OpenWrite(path))
using (StreamWriter writer = new StreamWriter(stream))
{
foreach (Dictionary<string, AttributeValue> item in items)
{
writer.WriteLine("Item:");
foreach (var keyValuePair in item)
{
writer.WriteLine("{0} : S={1}, N={2}, SS=[{3}], NS=[{4}]",
keyValuePair.Key,
keyValuePair.Value.S,
keyValuePair.Value.N,
string.Join(", ", keyValuePair.Value.SS ?? new List<string>()),
string.Join(", ", keyValuePair.Value.NS ?? new List<string>()));
}
}
}
// Set marker variable
startKey = result.LastEvaluatedKey;
} while (startKey != null);
});
Object | ||
AmazonWebServiceRequest | ||
ScanRequest |