Skip to content

Backend API support for pagination#4948

Closed
ahkcs wants to merge 5 commits into
opensearch-project:mainfrom
ahkcs:feat/pagination_support
Closed

Backend API support for pagination#4948
ahkcs wants to merge 5 commits into
opensearch-project:mainfrom
ahkcs:feat/pagination_support

Conversation

@ahkcs

@ahkcs ahkcs commented Dec 11, 2025

Copy link
Copy Markdown
Collaborator

Description

This PR adds offset-based pagination support for PPL queries executed through the Calcite engine. Users can now paginate through large result sets by specifying pageSize and offset parameters in the request body

  • Simple API: Pass pageSize and offset in the JSON request body
  • Respects user intent: User-specified commands like head X from Y are honored first

API Design

Request Format

  POST /_plugins/_ppl
  {
    "query": "source=logs | where status='error' | sort timestamp",
    "pageSize": 100,
    "offset": 0
  }

Parameters

Parameter Type Default Description
pageSize int 0 Number of rows per page. 0 = pagination disabled
offset int 0 Number of rows to skip (0-based)

Example: Paginating Through Results

  Page 1 (rows 0-99):
  { "query": "source=accounts | fields name, age | sort age", "pageSize": 100, "offset": 0 }

  Page 2 (rows 100-199):
  { "query": "source=accounts | fields name, age | sort age", "pageSize": 100, "offset": 100 }

  Page 3 (rows 200-299):
  { "query": "source=accounts | fields name, age | sort age", "pageSize": 100, "offset": 200 }

Check List

  • New functionality includes testing.
  • New functionality has been documented.
  • New functionality has javadoc added.
  • New functionality has a user manual doc added.
  • New PPL command checklist all confirmed.
  • API changes companion pull request created.
  • Commits are signed per the DCO using --signoff or -s.
  • Public documentation issue/PR created.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

@coderabbitai

coderabbitai Bot commented Dec 11, 2025

Copy link
Copy Markdown
Contributor

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment

Comment @coderabbitai help to get the list of available commands and usage tips.

@LantaoJin LantaoJin added the enhancement New feature or request label Dec 12, 2025

@LantaoJin LantaoJin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add some tests in CalciteExplainIT?

Is this query

POST /_plugins/_ppl
  {
    "query": "source=logs | where status='error' | sort timestamp",
    "pageSize": 100,
    "offset": 1000
  }

equals to

POST /_plugins/_ppl
  {
    "query": "source=logs | where status='error' | sort timestamp | head 100 from 1000"
  }

?

* <p>Unlike regular LogicalSort which may be merged with other sorts by Calcite optimizer, this
* class ensures pagination is applied as a final post-processing step on the query result.
*/
public class LogicalPaginationLimit extends Sort {

@LantaoJin LantaoJin Dec 12, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please reuse LogicalSystemLimit with type=pagination

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated

RelNode optimized = optimize(relNode, context);
RelNode calcitePlan = convertToCalcitePlan(optimized);
executionEngine.execute(calcitePlan, context, listener);
AccessController.doPrivileged(

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why add the doPrivileged back?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated to remove doPrivileged

@ahkcs

ahkcs commented Dec 12, 2025

Copy link
Copy Markdown
Collaborator Author

Can you add some tests in CalciteExplainIT?

Is this query

POST /_plugins/_ppl
  {
    "query": "source=logs | where status='error' | sort timestamp",
    "pageSize": 100,
    "offset": 1000
  }

equals to

POST /_plugins/_ppl
  {
    "query": "source=logs | where status='error' | sort timestamp | head 100 from 1000"
  }

?

Added test cases in CalciteExplainIT

@ahkcs ahkcs force-pushed the feat/pagination_support branch from 39352de to 9a809b7 Compare December 12, 2025 19:39
Signed-off-by: Kai Huang <ahkcs@amazon.com>

# Conflicts:
#	core/src/main/java/org/opensearch/sql/executor/QueryService.java
Signed-off-by: Kai Huang <ahkcs@amazon.com>
Signed-off-by: Kai Huang <ahkcs@amazon.com>
Signed-off-by: Kai Huang <ahkcs@amazon.com>

# Conflicts:
#	integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalciteExplainIT.java
Signed-off-by: Kai Huang <ahkcs@amazon.com>
@ahkcs ahkcs force-pushed the feat/pagination_support branch from 69f3cdb to ad1c15b Compare December 15, 2025 23:13

@LantaoJin LantaoJin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this PR ready for review now?

*/
@Test
public void testExplainPaginationApi() throws IOException {
enabledOnlyWhenPushdownIsEnabled();

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove this line since the PPL pagination feature should work when the DSL pushdown disabled. We should check the calcite plan without pushdown.

*/
@Test
public void testExplainPaginationApiWithHeadFrom() throws IOException {
enabledOnlyWhenPushdownIsEnabled();

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ditto

@ahkcs

ahkcs commented Dec 18, 2025

Copy link
Copy Markdown
Collaborator Author

Is this PR ready for review now?

Not yet, it's currently a POC PR, still need to finalize design

@ahkcs ahkcs closed this Feb 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants