DynamoDB Scan vs Query - Everything You Need To Know

Difference Between Query and Scan in DynamoDB

Query and Scan are two operations available in DynamoDB SDK and CLI for fetching a collection of items. While they might seem to serve a similar purpose, the difference between them is vital. While Scan is "scanning" through the whole table looking for elements matching criteria, Query is performing a direct lookup to a selected partition based on primary or secondary partition/hash key.

You will also see the difference in speed. While Query usually returns results within 100ms, Scan might even take a few hours to find the relevant piece of data.

When querying DynamoDB, When You Should Use Scan vs Query

Generally speaking, you should always favor Query over Scan. When it's not possible (for example, when you're looking for piece of data with a key that is unknown to you), and if it's a frequently used pattern, consider adding a GSI (Global Secondary Index) to index that attribute and enable Query. In the last resort, use Scan.

Scan is also useful when you need to retrieve all the table data.

DynamoDB Scan vs Query - Syntax Differences

Request parameters for both Query and Scan are almost identical. The only difference is KeyConditionExpression parameter which is required in Query operation. It specifies the condition that the key values for items to be retrieved by this action. Moreover, the descripted condition must perform an equality check on a partition key value. Optionally, you can use various other operators like Equals, GreaterThan, BeginsWith on range/sort key.

For rest of the parameters, it's pretty much the same. In both cases, FilterExpression can be used to narrow down the results.

Frequently Asked Questions

When getting data from DynamoDB, when you should use Scan and when Query?

You should always favor Query over Scan. When it's not possible (for example, when you're looking for piece of data with a key that is unknown to you), and if it's a frequently used pattern, consider adding a GSI to index that attribute and enable Query. In the last resort, use Scan.

Is DynamoDB query cheaper than scan?

Generally speaking - yes, because it accesses the data in the desired partition directly. Scan, because it goes through the whole table space, is billed not on the data returned basis, but data scanned, hence it's costs can be higher.

What is the DynamoDB scan vs query performance difference?

If you need to access data identified by known keys, query is much faster because of the direct access method.

I need to use scan. Can I make it faster?

You can consider using DynamoDB Parallel Scan. It uses multiple threads to run multiple scans at once scanning multiple parts of your table space simultaneously.

I've ran a Scan but it is not returning any results

It is possible that the Scan you're running is simply not returning any results relevant to your FilterExpressions on first page. Items you are looking for might be on next pages. More info on how to use pagination in DynamoDB