This is an automated email from the ASF dual-hosted git repository.
yuqi1129 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new c5b9affa41 [MINOR] docs(open-api): Document job list filter
combination and missing-timestamp sorting (#12981)
c5b9affa41 is described below
commit c5b9affa41412eb7c89a8eb9b2cff2e00f920ff9
Author: Jerry Shao <[email protected]>
AuthorDate: Tue Sep 8 19:40:12 2026 +0800
[MINOR] docs(open-api): Document job list filter combination and
missing-timestamp sorting (#12981)
### What changes were proposed in this pull request?
Clarify the `GET /metalakes/{metalake}/jobs/runs` query-parameter docs
in
`docs/open-api/jobs.yaml`:
- `queuedAfter`, `startedAfter` and `finishedAfter` combine with AND
semantics
when more than one is supplied.
- Jobs with no value for the selected `sortBy` timestamp always sort
last, for
both the `asc` and `desc` sort orders.
### Why are the changes needed?
Clients need these rules to correctly construct requests and interpret
sorted
job-list responses. Both rules already match the server behaviour in
`JobOperations`, but were not stated in the specification.
### Does this PR introduce _any_ user-facing change?
No behaviour change; OpenAPI documentation only.
### How was this patch tested?
`./gradlew :docs:build` (Redocly validation passes).
---------
Co-authored-by: Claude Opus 5 <[email protected]>
---
docs/open-api/jobs.yaml | 22 +++++++++++++++++-----
1 file changed, 17 insertions(+), 5 deletions(-)
diff --git a/docs/open-api/jobs.yaml b/docs/open-api/jobs.yaml
index 7b7a75d6ab..7729301263 100644
--- a/docs/open-api/jobs.yaml
+++ b/docs/open-api/jobs.yaml
@@ -361,7 +361,9 @@ components:
name: queuedAfter
in: query
description: >-
- Only return jobs queued at or after this ISO-8601 instant (e.g.
2026-08-18T00:00:00Z)
+ Only return jobs queued at or after this ISO-8601 instant (e.g.
2026-08-18T00:00:00Z).
+ A job must satisfy all supplied time filters (AND semantics), so this
combines with
+ one or more of startedAfter and finishedAfter
required: false
schema:
type: string
@@ -371,7 +373,9 @@ components:
in: query
description: >-
Only return jobs started at or after this ISO-8601 instant (e.g.
2026-08-18T00:00:00Z).
- Jobs that have not started yet are excluded
+ Jobs that have not started yet are excluded. A job must satisfy all
supplied time
+ filters (AND semantics), so this combines with one or more of
queuedAfter and
+ finishedAfter
required: false
schema:
type: string
@@ -381,7 +385,9 @@ components:
in: query
description: >-
Only return jobs finished at or after this ISO-8601 instant (e.g.
2026-08-18T00:00:00Z).
- Jobs that have not finished yet are excluded
+ Jobs that have not finished yet are excluded. A job must satisfy all
supplied time
+ filters (AND semantics), so this combines with one or more of
queuedAfter and
+ startedAfter
required: false
schema:
type: string
@@ -389,7 +395,10 @@ components:
sortBy:
name: sortBy
in: query
- description: The field to sort the returned jobs by
+ description: >-
+ The field to sort the returned jobs by. Jobs with no value for the
selected field
+ (e.g. jobs that have not started or finished yet) always sort last,
for both the "asc"
+ and "desc" sort orders
required: false
schema:
type: string
@@ -401,7 +410,10 @@ components:
sortOrder:
name: sortOrder
in: query
- description: The sort order for the returned jobs
+ description: >-
+ The sort order for the returned jobs. It only orders the jobs that
have a value for the
+ selected sortBy field; jobs missing that value always sort last in
both "asc" and "desc"
+ order
required: false
schema:
type: string
