Skip to content

Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.

fix(dynamodb): return LastEvaluatedKey when Query/Scan results end exactly at Limit (#1068)

Futa4c577fa343ec
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cd10f2bd..03c4d18f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,11 @@ All notable changes to MiniStack will be documented here.
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
Versioning follows [Semantic Versioning](https://semver.org/).
+## [Unreleased]
+
+### Fixed
+- **DynamoDB — `Query`/`Scan` return `LastEvaluatedKey` when results end exactly at `Limit`** — real DynamoDB doesn't look ahead: whenever it stops because of the limit it returns a `LastEvaluatedKey`, even if nothing remains, and the follow-up page comes back empty with no key. MiniStack only returned the key when strictly more items remained, so SDK pagination helpers that rely on the exact-limit page (e.g. "has more pages" checks) diverged from AWS. Verified against DynamoDB Local. Contributed by @ifutivic.
+
## [1.4.1] — 2026-07-09
### Added
diff --git a/ministack/services/dynamodb.py b/ministack/services/dynamodb.py
index 2730675f..fa568660 100644
--- a/ministack/services/dynamodb.py
+++ b/ministack/services/dynamodb.py
@@ -1884,9 +1884,12 @@ def _query(data):
if esk:
candidates = _apply_exclusive_start_key(candidates, esk, pk_name, sk_name, scan_forward, table=table)
+ # AWS returns a LastEvaluatedKey whenever it stopped *because of* the
+ # limit — including when the results end exactly at the limit, since it
+ # doesn't look ahead. The follow-up page then returns 0 items and no key.
has_more = False
- if limit is not None and len(candidates) > limit:
- has_more = True
+ if limit is not None and len(candidates) >= limit:
+ has_more = len(candidates) > 0
candidates = candidates[:limit]
scanned_count = len(candidates)
@@ -2080,9 +2083,11 @@ def _scan(data):
"The provided starting key is invalid: The provided key element does not match the schema", 400)
all_items = _apply_exclusive_start_key_scan(all_items, esk, table)
+ # Same LastEvaluatedKey semantics as Query: stopping exactly at the limit
+ # still yields a key, because AWS doesn't look ahead.
has_more = False
- if limit is not None and len(all_items) > limit:
- has_more = True
+ if limit is not None and len(all_items) >= limit:
+ has_more = len(all_items) > 0
all_items = all_items[:limit]
scanned_count = len(all_items)
diff --git a/tests/test_dynamodb.py b/tests/test_dynamodb.py
index 44d61679..abf49163 100644
--- a/tests/test_dynamodb.py
+++ b/tests/test_dynamodb.py
@@ -6139,3 +6139,116 @@ def test_dynamodb_update_item_valid_update_still_succeeds(ddb):
finally:
ddb.delete_table(TableName=name)
+
+
+# ---------------------------------------------------------------------------
+# LastEvaluatedKey when the results end exactly at Limit (AWS doesn't look
+# ahead: stopping at the limit always yields a key; the next page is empty).
+# ---------------------------------------------------------------------------
+
+def _create_paging_table(ddb, name):
+ try:
+ ddb.delete_table(TableName=name)
+ except Exception:
+ pass
+ ddb.create_table(
+ TableName=name,
+ KeySchema=[
+ {"AttributeName": "pk", "KeyType": "HASH"},
+ {"AttributeName": "sk", "KeyType": "RANGE"},
+ ],
+ AttributeDefinitions=[
+ {"AttributeName": "pk", "AttributeType": "S"},
+ {"AttributeName": "sk", "AttributeType": "S"},
+ ],
+ BillingMode="PAY_PER_REQUEST",
+ )
+ for i in range(1, 4):
+ ddb.put_item(TableName=name, Item={"pk": {"S": "a"}, "sk": {"S": str(i)}})
+
+
+def test_dynamodb_query_lek_present_when_limit_equals_count(ddb):
+ name = "lek-query-exact"
+ _create_paging_table(ddb, name)
+ try:
+ page1 = ddb.query(
+ TableName=name,
+ KeyConditionExpression="pk = :p",
+ ExpressionAttributeValues={":p": {"S": "a"}},
+ Limit=3,
+ )
+ assert page1["Count"] == 3
+ assert "LastEvaluatedKey" in page1, "stopping exactly at Limit must yield a LastEvaluatedKey"
+
+ page2 = ddb.query(
+ TableName=name,
+ KeyConditionExpression="pk = :p",
+ ExpressionAttributeValues={":p": {"S": "a"}},
+ Limit=3,
+ ExclusiveStartKey=page1["LastEvaluatedKey"],
+ )
+ assert page2["Count"] == 0
+ assert "LastEvaluatedKey" not in page2
+ finally:
+ ddb.delete_table(TableName=name)
+
+
+def test_dynamodb_query_no_lek_when_limit_exceeds_count(ddb):
+ name = "lek-query-over"
+ _create_paging_table(ddb, name)
+ try:
+ resp = ddb.query(
+ TableName=name,
+ KeyConditionExpression="pk = :p",
+ ExpressionAttributeValues={":p": {"S": "a"}},
+ Limit=4,
+ )
+ assert resp["Count"] == 3
+ assert "LastEvaluatedKey" not in resp
+ finally:
+ ddb.delete_table(TableName=name)
+
+
+def test_dynamodb_scan_lek_present_when_limit_equals_count(ddb):
+ name = "lek-scan-exact"
+ _create_paging_table(ddb, name)
+ try:
+ page1 = ddb.scan(TableName=name, Limit=3)
+ assert page1["Count"] == 3
+ assert "LastEvaluatedKey" in page1, "stopping exactly at Limit must yield a LastEvaluatedKey"
+
+ page2 = ddb.scan(TableName=name, Limit=3, ExclusiveStartKey=page1["LastEvaluatedKey"])
+ assert page2["Count"] == 0
+ assert "LastEvaluatedKey" not in page2
+
+ over = ddb.scan(TableName=name, Limit=4)
+ assert over["Count"] == 3
+ assert "LastEvaluatedKey" not in over
+ finally:
+ ddb.delete_table(TableName=name)
+
+
+def test_dynamodb_query_lek_full_pagination_still_terminates(ddb):
+ """Paging with Limit=1 visits every item exactly once and terminates."""
+ name = "lek-query-walk"
+ _create_paging_table(ddb, name)
+ try:
+ seen = []
+ esk = None
+ for _ in range(10):
+ kwargs = {
+ "TableName": name,
+ "KeyConditionExpression": "pk = :p",
+ "ExpressionAttributeValues": {":p": {"S": "a"}},
+ "Limit": 1,
+ }
+ if esk:
+ kwargs["ExclusiveStartKey"] = esk
+ page = ddb.query(**kwargs)
+ seen.extend(it["sk"]["S"] for it in page["Items"])
+ esk = page.get("LastEvaluatedKey")
+ if not esk:
+ break
+ assert seen == ["1", "2", "3"]
+ finally:
+ ddb.delete_table(TableName=name)