SAP CAP Java pagination: Why rows can repeat or disappear between pages
A manufacturer's integration reads an order collection in pages and finds that some intended identities are missing or repeated.
START HERE · NO PRIOR TOPIC KNOWLEDGE NEEDED
What it is. Why it matters.
Pagination returns a large dataset in smaller pages. SAP CAP Java services and their clients must follow the relevant paging contract so the first page is not mistaken for the complete result.
Completely new to SAP?
Manufacturers use SAP to connect work such as buying components, recording inventory, planning production, shipping equipment and accounting for costs. SAP S/4HANA is an enterprise resource planning system: it connects these activities through shared business data.
ABAP is SAP’s programming language for business applications. A program reads data, applies rules and produces a result. Start with the objects involved before investigating code.
A transaction code, or t-code, is a shortcut to a task in classic SAP GUI. Fiori apps provide another way to work. Names and screens depend on the product and release; you do not need a live system to learn the concepts in this guide.

Scope and source-review notes
Scope and evidence
Source review by FAST SAP SOLUTIONS® editorial. This badge describes our editorial review; it does not represent SAP certification or independent endorsement.
CAP Java CQL limit/order and current generic OData paging; reliable pagination is documented for OData V4 with query-shape constraints.
Primary documentation reviewed on 14 November 2026 using readable full text. Relevant full-text CAP Java order/paging and generic-service pagination sections reviewed. Java snippet and changing-data experiments were not executed; deployed SDK/configuration must be checked.
A MANUFACTURING EXAMPLE
Read every page of a factory worklist
One page is not the full dataset
Read the example values
- Available records
- 250
- First page
- 100 records
- Continuation
- Relevant next-page link
- Client result
- Must follow paging contract
Words you’ll meet in this guide
- Program
- A set of instructions executed by a computer.
- Class
- A reusable unit that groups data with operations called methods.
- Database
- Organized information kept beyond one program execution.
- Internal table
- A list of rows held temporarily in an ABAP program’s memory.
- Key
- One or more fields used to identify or find a record.
- OData
- A standard for reading and updating data through a web API.
- API
- A defined interface through which programs exchange data or request actions.
Preview the practical steps
SEE THE CONNECTION
See it in a simple example.
A small example to make the idea concrete.
Read every page of a factory worklist
A manufacturer's integration reads an order collection in pages and finds that some intended identities are missing or repeated.
Stable ordering and a continuation contract are separate from a frozen dataset
CAP Java pagination can return repeated or apparently missing rows when an offset-based client reads a dataset that changes between requests.
Scope and prerequisites
The examples use the CAP Java CQL query builder and current generic OData paging documentation.
Understand row count, offset and effective query order
CAP Java's limit(rows, offset) requests up to a number of rows after skipping the stated number in the current query result.
Read every page of a factory worklist
A manufacturer's integration reads an order collection in pages and finds that some intended identities are missing or repeated.
Trace stable ordering and the supported continuation contract before treating the first page as the complete worklist.
| Reader | Business question | Evidence to carry forward |
|---|---|---|
| SAP developers and application teams supporting manufacturers | Read every page of a factory worklist | Trace stable ordering and the supported continuation contract before treating the first page as the complete worklist. |
01 Stable ordering and a continuation contract are separate from a frozen dataset
CAP Java pagination can return repeated or apparently missing rows when an offset-based client reads a dataset that changes between requests. A non-unique sort order adds another source of ambiguity. Capture the actual filters, ordering and continuation from both requests before assuming records were deleted or the database is corrupt. [1] [2]
Use a complete stable ordering for deterministic pages, follow server-provided continuation links where applicable and choose the supported paging strategy for the requirement. This tutorial demonstrates insertion and deletion with five rows, then explains what reliable pagination improves and why it is not a universal snapshot guarantee.
02 Scope and prerequisites
The examples use the CAP Java CQL query builder and current generic OData paging documentation. Custom handlers, remote services and OData V2/V4 adapters can have different behavior. Record Java SDK, compiler, database adapter and protocol versions, plus any query-limit/reliable-paging configuration in the deployed application.
You should understand sorting, row identity and an offset. The dataset and Java query are illustrative and unexecuted. The current CAP guide restricts its reliable-pagination feature to OData V4 and lists query-shape limitations. Do not copy an old release-note setting into another runtime without checking its current configuration contract and actual generated continuation behavior. [2]
03 Understand row count, offset and effective query order
CAP Java's limit(rows, offset) requests up to a number of rows after skipping the stated number in the current query result. The builder documentation says Select has no particular order by default. A generic service can add implicit ordering for its paging contract, but a custom CQL query should not assume that unrelated provider behavior supplies its intended business order. [1]
Order by the business sort criterion and a unique tie-breaker. If several records share createdAt, append ID or another appropriate unique identity. Keep locale, null ordering and ascending/descending direction consistent. A page boundary is meaningful only in the same ordered, filtered population. [2]
04 Worked case: two-row pages over five identities
Start with fictional rows A,B,C,D,E ordered by immutable sequence 10,20,30,40,50. Page size is 2. The first request returns A,B. With no change, the next offset 2 request returns C,D, and offset 4 returns E. These are the expected stable-fixture pages.
Now insert X with sequence 15 after page 1. The current order becomes A,X,B,C,D,E. Offset 2 skips A and X, then returns B,C. B repeats because positions moved. In a separate reset fixture, delete A after page 1: current order B,C,D,E, and offset 2 returns D,E. C was skipped because the earlier deletion shifted it before the offset boundary.
| Intervening change | Current ordered set | Next offset 2 page | Effect |
|---|---|---|---|
| None | A,B,C,D,E | C,D | Expected continuation |
| Insert X at 15 | A,X,B,C,D,E | B,C | B repeated |
| Delete A in reset fixture | B,C,D,E | D,E | C skipped |
05 Make an explicit ordered Java query
The snippet requests the second two-row page under sequence/ID ordering. It assumes an entity demo.Records with fields ID and sequence and a compatible installed query API. Add the actual business filters and authorization-safe service path required by the application; a raw persistence query is not a complete endpoint implementation.
This fixes ordering ambiguity for a static population, but it retains offset sensitivity to changes. That is an intentional distinction. Do not promise that adding orderBy alone prevents the insertion/deletion behavior demonstrated above. It makes the chosen order explicit so the remaining concurrency effect can be understood and tested.
import com.sap.cds.ql.Select;
import com.sap.cds.ql.cqn.CqnSelect;
CqnSelect secondPage = Select.from("demo.Records")
.columns("ID", "sequence")
.orderBy(r -> r.get("sequence").asc(),
r -> r.get("ID").asc())
.limit(2, 2);
// Execute through the appropriate configured CAP service.
// Same filters, identity context and ordering must apply to every page.06 Follow the server next link without reconstructing it
For server-driven OData paging, inspect the returned nextLink and request it as the continuation contract specifies. CAP's guide says clients must not interpret or modify the returned link. A token may be opaque and can encode more than a row offset. Do not increment a visible number or rebuild a URL that loses filters and ordering. [2]
Resolve relative links against the correct service context and preserve authenticated/tenant context. If the user changes a filter or sort, start a new query sequence rather than reusing the old continuation. Keep the original query and next link together in sanitized diagnostics; remove credentials and sensitive token contents from public reports.
07 What reliable pagination changes
Current CAP reliable pagination uses values from the last row of a page rather than a simple numeric position. Conceptually, after B at sequence 20, the next page asks for rows beyond that boundary under the same complete ordering. Inserting X at 15 does not shift B's boundary, and deleting A does not move C behind an arbitrary numeric skip. [2]
The documented OData V4 feature has restrictions: order elements must be simple types, expression/function orderings are not supported, ordered fields must be selected when select is specified, and certain complex result concatenations are unsupported. Review current configuration such as the Java reliablePaging enabled option and validate the actual service response. Avoid exposing sensitive sort values through continuation tokens. [2]
Last row on page 1: sequence 20, ID B
Next boundary in ascending order:
sequence >20
OR (sequence =20 AND ID >B)
Then apply the same filters and order, limit 2.
Treat an actual CAP nextLink/token as opaque.08 Key-based continuation is still not a historical snapshot
Rows inserted after the boundary can appear on later pages. Rows deleted before they are read will be absent. If a sort field changes, a row can move across the boundary. Reliable continuation reduces positional anomalies; it does not automatically freeze every value and membership as of the first request.
If the business needs a consistent export or audit population, define that requirement separately. A server-side job, a stable materialized identity set or a documented snapshot strategy may be appropriate under the actual service and database capabilities. Do not hold a long interactive database transaction open merely because the UI shows page numbers. Choose a supported architecture for the required consistency and volume.
09 Troubleshoot page requests before changing limits
Compare complete request contracts and returned identities. Raising page size can hide an anomaly in a small test while leaving the underlying continuation logic incorrect.
| Observation | Question | Next evidence |
|---|---|---|
| Same row on two pages | Offset shifted by insertion or unstable ties? | Ordered identities and intervening writes |
| One row skipped | Deletion/filter/authorization changed? | Population at both request times |
| Duplicates without any writes | Non-unique sort or client append bug? | Tie-breaker and response-versus-model identities |
| Server returns nextLink; client stops | Continuation ignored? | Client paging loop |
| Reliable mode rejected/ineffective | Unsupported protocol/query shape? | V4 metadata, order/select and config |
| Different user sees different pages | Authorization/tenant/locale differs? | Same verified context |
| Only export misses rows | Export assumed first page complete? | Follow-up requests and export contract |
10 Verify static, changing and final-page fixtures
For the positive static fixture, retrieve A,B then C,D then E and compare the union of identities with the expected five-row set. Confirm no duplicate identity and no extra request loop after the documented end. A negative client test intentionally ignores nextLink and demonstrates why a first page is incomplete.
Run the insertion and deletion experiments independently from a reset fixture. Then test duplicate sequence values with a unique ID tie-breaker, an empty result, one row, an exact page-size multiple and a final partial page. Test the required reliable-paging behavior separately from offset behavior. These are proposed checks and have not been executed against a CAP Java deployment.
Add a tie fixture before testing concurrent writes: give B and C the same sequence 20 while retaining distinct IDs. Under sequence ascending, ID ascending, the first page remains A/B and the next begins C. Repeat the static read several times and compare identities. This isolates an incomplete ordering from the separate offset-shift experiments; without a tie fixture, a missing tie-breaker can remain invisible.
Also inspect client accumulation independently. Store each received page's ordered IDs before appending them to the visible model. If the response pages are A/B, C/D and E but the display contains B twice, the paging service did not produce that duplicate. A client that requests the same continuation twice or appends after a refresh can create it. Deduplicating by ID may hide the symptom, but retain the original page sequence so a skipped record or broken continuation loop is still detectable.
11 Custom handlers must preserve the paging contract
A custom READ handler that retrieves a page and then filters rows in memory can return short pages while hiding additional eligible records. A handler that appends its own rows after applying a limit can violate count and continuation semantics. Review where filtering, ordering and pagination occur in the entire query path.
If proxying another service, preserve its continuation model rather than translating an opaque remote token into a guessed local offset. Count responses can also change while data changes; they are observations under a contract, not necessarily a fixed denominator for the whole browsing session. Keep UI loaded-row count distinct from the complete business population.
12 Frequently asked questions
Does orderBy prevent every missing row? It makes order deterministic when complete, but offset pages still observe a changing population.
Should I parse skiptoken? No. Follow the returned continuation link as the server's opaque contract.
Does reliable pagination mean snapshot isolation? No. It addresses positional continuation; changing values and membership still need a defined consistency requirement.
Can I set a huge top to export everything? Server limits and memory still apply. Use supported paging or an export process suited to the volume.
What belongs in a support case? Runtime/protocol versions, original query, both sanitized continuations, ordered returned IDs, intervening changes and expected browsing/export semantics. That distinguishes service behavior from client accumulation errors.
Related services and next steps
Primary sources
Found this useful?
Share this guide with your network, or leave a like.
Your like is saved in this browser.