Skip to main content

Cursor-based search pagination

Cursor-based search pagination offers significantly better performance, particularly in large data sets, than offset-based search. This method uses a defined cursor, which represents the current position in the data set, and a limit to retrieve results. To start cursor pagination, the cursor: “_” query parameter needs to used in combination with limit. This is equivalent to starting the search from the first item in the data set.

After each API call using a cursor query parameter, a new header is returned in the response: Items-Next-Cursor. This value is the cursor to be used in the next cursor-based search API call. When Items-Next-Cursor is empty (an empty string), the search is over: there are no items left in the data set.

Cursor-based searching is supported for the following data types:

EndpointQuery exampleCursor field(s)
journal entries/gljournalentries:search?limit=100&cursor=_entryId
deposit accounts/deposits:search?limit=1&cursor=_lastModifiedDate and encodedKey
deposit transactions/deposits/transactions:search?limit=1&cursor=_transactionId
loan accounts/loans:search?limit=1&cursor=_lastModifiedDate and encodedKey
loan transactions/loans/transactions:search?limit=3&cursor=_transactionId

The journal entries, deposit transactions, and loan transactions data types use an indexed auto-incrementing ID field as their cursor. While the cursor is indexed, performance issues could arise if the search query contains additional filters that use non-indexed columns. Deposit accounts and loan accounts use a compound field to define the cursor, and do not allow for further query filters.

When using cursor-based searching, some features of the search APIs are not supported:

  • journal entries: at least one filter by creationDate or bookingDate using the BETWEEN operator should be present; on top of this, other filters can be added, for example, a filter by glAccountId or glAccountName.
  • loan and deposit transactions: at least one filter by creationDate or valueDate using the BETWEEN operator should be present; on top of this, other filters can be added, for example, a filter by parentAccountId.
  • Loan and deposit accounts: exactly one filter by the lastModifiedDate field using the BETWEEN operator is accepted.
  • No sort criteria can be specified; the items are always sorted by the cursor field.
  • paginationDetails=ON is not supported.
  • The first cursor-based search (using the “_” as the cursor) will also compute the minimum and maximum cursor values. Therefore, this API call can take more time than the subsequent API calls, which will take roughly the same amount of time regardless of the cursor’s position in the data set. This is in contrast to offset-based searching, which takes increasingly more time as the offset value increases.

For more information on pagination in Mambu APIs, see pagination.

Cursor-based search pagination with application/vnd.mambu.v2+octetstream Accept header​

Some APIs can handle conditions where the application/vnd.mambu.v2+octetstream Accept header is sent together with the cursor=_ parameter . This sends back an octet stream of all the data until the end of the cursor to a single file. The connection will only be closed if the client terminates it or all the data is retrieved from the database.