Add maxItems to QueryEnhancedRequest to simplify pagination

[iulianbudau]

Describe the feature

Add a direct method (e.g., maxItems() or limit()) to the QueryEnhancedRequest.Builder class in AWS SDK for Java v2 to control the maximum number of items returned in query results.

Use Case

Currently, developers must implement complex pagination logic using iterators and page size controls to limit result sets, which adds unnecessary complexity to simple use cases. This feature would provide functionality similar to the --max-items parameter available in the AWS CLI for DynamoDB queries.

Proposed Solution

No response

Other Information

No response

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

AWS Java SDK version used

2.41.34

JDK version used

21

Operating System and version

Windows 11 Enterprise

[debora-ito]

Hi @iulianbudau,

There is already a QueryEnhancedRequest limit() that is passed on to the low-level query request, and the query returns a PageIterable so the page limit can also be controlled.

Can you give more details about this new feature you're suggesting, maybe with a code sample?

[iulianbudau]

Hi @debora-ito,

We’re aware of QueryEnhancedRequest.limit(), but it serves a different purpose than what we’re requesting.

limit() controls how many items DynamoDB evaluates per service call (server-side behavior). It does not guarantee how many items are returned to the caller. The returned count can be lower than the limit due to:

• filter expressions (filtering happens after evaluation)
• the 1 MB per-request response size constraint.

What we’re proposing with maxItems is closer to CLI --max-items: a client-side cap on the total number of items returned across pages, regardless of how many service calls are required.

So the distinction would be:

• limit → server-side control (items evaluated per request, subject to filtering and 1MB cap)
• maxItems → client-side control (total items returned to the user)

This would provide more intuitive “return up to N results” semantics, prevent accidental over-fetching with auto-pagination, improve behavior clarity when filters are involved, and align better with the CLI mental model.

We see this as complementary to limit(), not a replacement. Happy to provide a solution design proposal if needed.

[debora-ito]

This max items control can be obtained by using items Stream#limit:

        myTable.query(queryRequest)
                .items()
                .stream()
                .limit(1230)
                .forEach(b -> System.out.println(b.getRank()));

In this example, if a query response count is 1225, the SDK will send a query and get the first response with 1225 items; the 1230 limit was not reached so the SDK will send another query, get the second page with 1225 items, and will print only 5 items more. The SDK still paginates automatically so this should be transparent, and the stream limit is regardless of page size.

Does using the stream limit works in your case?