Copilot commented on code in PR #12981:
URL: https://github.com/apache/gravitino/pull/12981#discussion_r3955585031
##########
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).
+ When combined with startedAfter or finishedAfter, all supplied time
filters must match
+ (AND semantics)
Review Comment:
The wording “When combined with startedAfter or finishedAfter” can read as
if only one of the two can be combined at a time. Consider using “and/or” (or
explicitly “one or more”) and phrasing it as “a job must satisfy all supplied
time filters” to remove ambiguity.
This issue also appears in the following locations of the same file:
- line 375
- line 386
##########
docs/open-api/jobs.yaml:
##########
@@ -381,15 +384,19 @@ 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. When combined with
queuedAfter or
+ startedAfter, all supplied time filters must match (AND semantics)
required: false
schema:
type: string
format: date-time
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
Review Comment:
Consider quoting the literal enum values for the sort orders ("asc"/"desc")
since these are query values clients will send.
This issue also appears on line 412 of the same file.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
