[AJDA-2500] Add PaginationHelper, JobStatus enum, remove executeWorkspaceQuery by ondrajodas · Pull Request #476 · keboola/platform-libraries

ondrajodas · 2026-03-24T09:47:46Z

Summary

Add optional $pageSize and $offset parameters to Client::getJobResults()
Add new PaginationHelper class to fetch all result pages for completed statements
Add JobStatus string-backed enum replacing hardcoded status strings
Remove executeWorkspaceQuery() method and WorkspaceQueryResponse class (breaking changes)

Breaking changes

getStatus() on Statement, JobStatusResponse, JobResultsResponse now returns JobStatus enum instead of string
Client::executeWorkspaceQuery() removed — use submitQueryJob() + waitForJobCompletion() + PaginationHelper::getAllResults() instead
Response\WorkspaceQueryResponse class removed

linear · 2026-03-24T09:47:50Z

AJDA-2500 [query-api-php-client] add optional $pageSize parameter to getJobResults

ondrajodas · 2026-03-24T09:48:06Z

# Release Notes
- New `PaginationHelper` class for fetching all pages of query results
- New `JobStatus` string-backed enum (`Completed`, `Failed`, `Canceled`, `Running`, `Waiting`, `Processing`, `NotExecuted`, `Enqueued`)
- `getStatus()` on `Statement`, `JobStatusResponse`, `JobResultsResponse` now returns `JobStatus` enum (breaking change)
- `Client::executeWorkspaceQuery()` removed (breaking change)
- `Response\WorkspaceQueryResponse` class removed (breaking change)
- `Client::getJobResults()` now accepts optional `$pageSize` and `$offset` query parameters

# Plans for Customer Communication
Consumers of this library need to update: replace `getStatus() === 'completed'` with `getStatus() === JobStatus::Completed` and replace calls to `executeWorkspaceQuery()` with `submitQueryJob()` + `waitForJobCompletion()` + `PaginationHelper::getAllResults()`.

# Impact Analysis
Breaking changes to `query-service-api-client`. All consumers must update their code. No infrastructure changes required.

# Change Type
Feature + breaking changes (major version bump required)

# Justification
Pagination support for large result sets; type-safe status handling via enum; cleaner API surface by removing the monolithic executeWorkspaceQuery.

# Deployment Plan
Bump major version of `query-service-api-client`. Update all internal consumers before release.

# Rollback Plan
Pin to previous major version of the library.

# Post-Release Support Plan
Monitor for ValueError exceptions from unknown JobStatus values if the API introduces new statuses.

Copilot

Pull request overview

This PR extends the Query Service API PHP client to support pagination when fetching job results by introducing optional query parameters and plumbing them through higher-level query execution.

Changes:

Added optional pageSize and offset parameters to Client::getJobResults() and appended them as Guzzle query parameters when provided.
Extended the internal sendRequest() helper to accept optional query parameters passed through to Guzzle.
Added PHPUnit coverage for getJobResults() query parameter behavior and for executeWorkspaceQuery() forwarding pagination.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.

File	Description
libs/query-service-api-client/src/Client.php	Adds optional pagination query params to job results fetching and extends request helper to support query parameters.
libs/query-service-api-client/tests/Phpunit/ClientTest.php	Adds tests asserting correct query string construction and pagination forwarding behavior.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

libs/query-service-api-client/src/Client.php

libs/query-service-api-client/tests/Phpunit/ClientTest.php

Copilot · 2026-03-24T10:03:02Z

libs/query-service-api-client/src/Client.php

        int $maxWaitSeconds = self::DEFAULT_MAX_WAIT_SECONDS,
        int $maxPollWaitMs = self::DEFAULT_MAX_POLL_WAIT_MS,
+        ?int $pageSize = null,
    ): WorkspaceQueryResponse {


executeWorkspaceQuery only added $pageSize but the PR description says both pageSize and offset should be supported and propagated. Consider adding an optional ?int $offset = null parameter here as well (after $pageSize) so callers can control the results offset when using executeWorkspaceQuery.

Intentionally not added — the Linear issue (AJDA-2500) specifies only $pageSize for executeWorkspaceQuery. $offset is available directly on getJobResults for callers who need fine-grained control.

Já tomu teda ale taky moc nerozumím jak to pak bude stránkovat :)

no todle nebude stránkovat no... já nevím jestli tu logiku stránkování úplně strkat sem... mě se upřímně celá tahle executeWorkspaceQuery metoda moc nelíbí :D

No, ale o to šlo, aby tohle stránkovalo ne? podle toho k čemu to směřuje https://linear.app/keboola/issue/AJDA-2501/editor-service-sqldataprovider-paginate-executequery-to-fetch-all-job

no jestli ju uděláš líp, tak hurá do toho, je to úzký hrdlo

libs/query-service-api-client/src/Client.php

odinuv · 2026-03-24T12:12:01Z

libs/query-service-api-client/src/Client.php

+            $queryParams['offset'] = $offset;
+        }
+        return JobResultsResponse::fromResponse(
+            $this->sendRequest('GET', $url, null, $queryParams !== [] ? $queryParams : null),


tady bych si to podminku asi odpustil - resp. nechal sendRequest at si to vyresi

odinuv · 2026-03-24T12:12:26Z

libs/query-service-api-client/src/Client.php

        int $maxWaitSeconds = self::DEFAULT_MAX_WAIT_SECONDS,
        int $maxPollWaitMs = self::DEFAULT_MAX_POLL_WAIT_MS,
+        ?int $pageSize = null,
    ): WorkspaceQueryResponse {


Já tomu teda ale taky moc nerozumím jak to pak bude stránkovat :)

…ults, remove executeWorkspaceQuery

…ult pages

ondrajodas · 2026-03-25T10:22:10Z

protikus k tomu - https://github.com/keboola/editor-service/pull/85

odinuv

jo, asi dobrý

ondrajodas requested a review from Copilot March 24, 2026 10:00

Copilot started reviewing on behalf of ondrajodas March 24, 2026 10:00 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

ondrajodas marked this pull request as ready for review March 24, 2026 10:15

ondrajodas requested a review from odinuv March 24, 2026 10:30

odinuv reviewed Mar 24, 2026

View reviewed changes

ondrajodas changed the title ~~[AJDA-2500] Add optional pageSize and offset parameters to getJobResults~~ [AJDA-2500] Add PaginationHelper, JobStatus enum, remove executeWorkspaceQuery Mar 24, 2026

ondrajodas added 2 commits March 25, 2026 10:51

feat(query-service-api-client)!: add pageSize and offset to getJobRes…

737f9f2

…ults, remove executeWorkspaceQuery

feat(query-service-api-client): add PaginationHelper to fetch all res…

6e3b662

…ult pages

ondrajodas force-pushed the ondra/AJDA-2500 branch from 624e869 to 6e3b662 Compare March 25, 2026 09:52

ondrajodas requested a review from odinuv March 25, 2026 10:25

odinuv approved these changes Mar 26, 2026

View reviewed changes

ondrajodas merged commit 24e1fd4 into main Mar 26, 2026
6 checks passed

ondrajodas deleted the ondra/AJDA-2500 branch March 26, 2026 11:03

Conversation

ondrajodas commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking changes

Uh oh!

linear bot commented Mar 24, 2026

Uh oh!

ondrajodas commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

ondrajodas Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

odinuv Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

ondrajodas Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

odinuv Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

odinuv Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

odinuv Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

ondrajodas commented Mar 25, 2026

Uh oh!

odinuv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ondrajodas commented Mar 24, 2026 •

edited

Loading

ondrajodas commented Mar 24, 2026 •

edited

Loading