Scan items in a DynamoDB table

DynamoDB query is fast but we can only query using the primary key or the indices. For the fields that do not have indices, we cannot. The option that we have here is to scan the DynamoDB table.

The scan option is used when we cannot query certain fields that we want to. Scan uses a lot of DynamoDB read capacity as it has to go through all the items in a table to find what you are looking for. By default, the scan returns you all the items in the table. We can apply filters to the scan to return only the data we want. We should be very careful while using scan operations. It can be slow based on the volume of data you have in the table.

The main difference between the DynamoDB scan and query:

  • The scan operation goes through all the items in the table whereas query only picks the items that you want in a smaller set within the table
  • The scan operation is slow whereas query operation is fast
  • The read capacity could be used at max when using scan operation whereas in the query operation it is optimal
  • You can scan any attribute in the table whereas you can only query primary key or indices.
  • You can only use equal(==) operator for the query operation on the partition key and can use other operators like(>, <=) in the sort key. For scan operation, you can use any operators.

A scan can be done using the following way:

  • AWS console UI

Scan the DynamoDB table using AWS UI console

login to AWS console(UI), and go to the services > DynamoDB > Tables. Choose the table you created. In the case of this tutorial, this will be the books table. In the books table

Scan the DynamoDB table
Scan the DynamoDB table

Select the scan and the table. In the filter Add Author as the key to filter. Since Author is a string type select string. We can choose any operator. In this example, we are using equal(=) and enter the artist’s name. You can also add multiple filters in the scan. If you do not specify any filters this will return all the items in the table.

AWS CLI for the scan

Another way to scan is by using the AWS CLI. Assuming the AWS CLI is set up on your computer. Let us look into how we can scan using the AWS CLI.

> aws dynamodb scan \
    --table-name books

The command above will return you all the items in the table.

To strip down the result you can either use filter or max-items argument to return fewer data. With max-items provided, you will be provided a token that you can use for the next scan. The scan will return data based on your last scan return items position.

Adding filters to scan

You can add filters to reduce the number of records you want to return. this can be done with the following command:

aws scan --table-name books \
    --filter-expression "Authro = :author" \
    --expression-attribute-values '{
         ":author": { "S": "Daniel Kahneman" }

This will scan the table but filter those data and only return the result where the author is Daniel Kahneman.

We can perform a parallel scan using the scan operator which we will talk about in the best practices section.

Some Arguments and options for Dynamodb scan operators:

  • –max-items – The max number of results you want to return. This will return a NextToken value
  • –starting-token – The NextToken can be used as a value for the argument.
  • –consistent-read – Provide true if you want to ensure read consistency. The default is false.
  • –filter-expression – The filter expression to filter the result of the scan
  • –select – Returns the specified attributes only. You can provide count, all_attributes, specified_attributes or projected attributes for the scan of an index.

AWS SDK for scan

We can also use the AWS SDK for the scan operation. In this tutorial, we will be using Golang SKD to scan the DyanmoDB table.

// scanItems.go

mySession := session.Must(session.NewSession())
// Create a DynamoDB client from just a session.
svc := dynamodb.New(mySession)
input := &dynamodb.ScanInput{
     TableName: "books",
     FilterExpression: map[string]*dynamodb.AttributeValue{
         ":Author": {
             S: aws.String("Daniel Kahneman"),
     KeyConditionExpression: aws.String("Author = :Author"),
 output, err := svc.Scan(input)
 if err != nil {
     return nil