AWS SDK for .NET Documentation
ScanRequest Class
AmazonAmazon.DynamoDBv2.ModelScanRequest Did this page help you?   Yes   No    Tell us about it...
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 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.

Declaration Syntax
C#
public class ScanRequest : AmazonWebServiceRequest
Members
All MembersConstructorsMethodsProperties



IconMemberDescription
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:

Length
1 -


ConditionalOperator
A logical operator to apply to the conditions in the ScanFilter map:
  • AND - If all of the conditions evaluate to true, then the entire map evaluates to true.
  • OR - If at least one of the conditions evaluate to true, then the entire map evaluates to true.
If you omit ConditionalOperator, then AND is used as the default. The operation will succeed only if the entire map evaluates to true.

Constraints:

Allowed Values
AND, OR


Equals(Object)
Determines whether the specified Object is equal to the current 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:

Range
1 -


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:

Allowed Values
INDEXES, TOTAL, NONE


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:
  • AttributeValueList - One or more values to evaluate against the supplied attribute. The number of values in the list depends on the ComparisonOperator being used. For type Number, value comparisons are numeric. String value comparisons for greater than, equals, or less than are based on ASCII character code values. For example, a is greater than A, and aa is greater than B. For a list of code values, see http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters. For Binary, DynamoDB treats each byte of the binary data as unsigned when it compares binary values, for example when evaluating query expressions. For information on specifying data types in JSON, see JSON Data Format in the Amazon DynamoDB Developer Guide.
  • ComparisonOperator - A comparator for evaluating attributes. For example, equals, greater than, less than, etc. The following comparison operators are available: EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN For complete descriptions of all comparison operators, see API_Condition.html.

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:

Range
0 - 999999


Select
The attributes to be returned in the result. You can retrieve all item attributes, specific item attributes, or the count of matching items.
  • ALL_ATTRIBUTES: Returns all of the item attributes.
  • COUNT: Returns the number of matching items, rather than the matching items themselves.
  • SPECIFIC_ATTRIBUTES : Returns only the attributes listed in AttributesToGet. This is equivalent to specifying AttributesToGet without specifying any value for Select.
If neither Select nor AttributesToGet are specified, DynamoDB defaults to ALL_ATTRIBUTES. You cannot use both Select and AttributesToGet together in a single request, unless the value for Select is SPECIFIC_ATTRIBUTES. (This usage is equivalent to specifying AttributesToGet without any value for Select.)

Constraints:

Allowed Values
ALL_ATTRIBUTES, ALL_PROJECTED_ATTRIBUTES, SPECIFIC_ATTRIBUTES, COUNT


TableName
The name of the table containing the requested items.

Constraints:

Length
3 - 255
Pattern
[a-zA-Z0-9_.-]+


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:

Range
1 - 1000000


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

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".

CopyScan 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.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.

CopyParallel 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.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);
});

Inheritance Hierarchy
See Also

Assembly: AWSSDK (Module: AWSSDK) Version: 1.5.60.0 (1.5.60.0)