Container for the parameters to the Scan operation.
The Scan operation returns one or more items and item attributes by accessing every item in the table. To have Amazon 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.
Inheritance Hierarchy
Namespace: Amazon.DynamoDBv2.Model
Assembly: AWSSDK.dll
Version: 2.0.0.3
Syntax
public class ScanRequest : AmazonWebServiceRequest IRequestEvents
The ScanRequest type exposes the following members
Constructors
| Name | Description | |
|---|---|---|
|
ScanRequest() |
Properties
| Name | Description | |
|---|---|---|
|
|
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.
Constraints: |
|
|
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. |
|
|
Limit |
The maximum number of items to evaluate (not necessarily the number of matching items). If Amazon 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 Amazon 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 Constraints: |
|
|
ScanFilter |
Evaluates the scan results and returns only the desired values. Multiple conditions are treated as "AND" operations: all conditions must be
met to be included in the results. Each ScanConditions 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, the count of matching items, or
in the case of an index, some or all of the attributes projected into the index.
Constraints: |
|
|
TableName |
The name of the table containing the requested items.
Constraints: |
|
|
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: |
Examples
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".
Scan sample
// 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.ComparisonOperator = ComparisonOperator.CONTAINS;
titleCondition.AttributeValueList.Add(new AttributeValue { S = "Adventures" });
conditions["Title"] = titleCondition;
// Pages attributes must be greater-than the numeric value "200"
Condition pagesCondition = new Condition();
pagesCondition.ComparisonOperator = ComparisonOperator.GT;;
pagesCondition.AttributeValueList.Add(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.
Parallel scan sample
// 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.ComparisonOperator = ComparisonOperator.GT;
pagesCondition.AttributeValueList.Add(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);
});
Version Information
.NET Framework:
Supported in: 4.5, 4.0, 3.5
.NET for Windows Store apps:
Supported in: Windows 8
.NET for Windows Phone:
Supported in: Window Phone 8
