DynamodbHow-ToBeginner · 3 min read

How to Use Limit in DynamoDB Query for Controlled Results

In DynamoDB, use the Limit parameter in your Query operation to restrict the number of items returned. This helps control data size and improves performance by fetching only the specified maximum number of items.

📐

Syntax

The Limit parameter is used inside the Query request to specify the maximum number of items to return. It is an integer value.

Basic syntax in AWS SDK (JavaScript example):

TableName: The name of your DynamoDB table.
KeyConditionExpression: The condition to select items.
Limit: Maximum number of items to return.

javascript

const params = {
  TableName: 'YourTableName',
  KeyConditionExpression: '#pk = :pkval',
  ExpressionAttributeNames: { '#pk': 'PartitionKey' },
  ExpressionAttributeValues: { ':pkval': 'someKeyValue' },
  Limit: 5
};

💻

Example

This example demonstrates querying a DynamoDB table named Books to get up to 3 items with a specific Author as the partition key.

javascript

import { DynamoDBClient, QueryCommand } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient({ region: "us-east-1" });

async function queryWithLimit() {
  const params = {
    TableName: "Books",
    KeyConditionExpression: "Author = :author",
    ExpressionAttributeValues: {
      ":author": { S: "John Doe" }
    },
    Limit: 3
  };

  try {
    const data = await client.send(new QueryCommand(params));
    console.log("Items returned:", data.Items);
  } catch (err) {
    console.error(err);
  }
}

queryWithLimit();

Output

Items returned: [ { Author: { S: 'John Doe' }, Title: { S: 'Book 1' } }, { Author: { S: 'John Doe' }, Title: { S: 'Book 2' } }, { Author: { S: 'John Doe' }, Title: { S: 'Book 3' } } ]

⚠️

Common Pitfalls

One common mistake is expecting Limit to return exactly that many items every time. DynamoDB may return fewer items if fewer match the query or if the result is paginated.

Another pitfall is confusing Limit with filtering. Limit restricts the number of items read, not filtered. Use FilterExpression to filter results after reading.

javascript

/* Wrong: Using Limit to filter items */
const paramsWrong = {
  TableName: 'Books',
  KeyConditionExpression: 'Author = :author',
  ExpressionAttributeValues: { ':author': { S: 'John Doe' }, ':keyword': { S: 'Science' } },
  Limit: 5,
  FilterExpression: 'contains(Title, :keyword)'
};

/* Right: Understand Limit limits items read, FilterExpression filters after read */

📊

Quick Reference

Parameter	Description	Type
TableName	Name of the DynamoDB table	String
KeyConditionExpression	Condition to select partition key items	String
ExpressionAttributeValues	Values for placeholders in expressions	Map
Limit	Maximum number of items to return	Number
FilterExpression	Filters results after reading	String (optional)

✅

Key Takeaways

Use the Limit parameter in Query to control how many items DynamoDB returns.

Limit restricts the number of items read, not filtered; use FilterExpression to filter results.

DynamoDB may return fewer items than Limit if fewer match or due to pagination.

Always check for LastEvaluatedKey to handle pagination when using Limit.

Limit helps improve performance by reducing data transfer and processing.