Skip to content

Commit e76f5c3

Browse files
corentinmusardcorentinmusard
committed
Document query jobs
1 parent 22cd3d4 commit e76f5c3

File tree

8 files changed

+177
-53
lines changed

8 files changed

+177
-53
lines changed

‎api-reference/go/datasets/Datapoints.Query.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ The output sequence can be transformed into a typed `proto.Message` using [Colle
2828

2929
## Options
3030

31-
<ParamField path="WithTemporalExtent(temporalExtent query.TemporalExtent)">
31+
<ParamField path="WithTemporalExtent(temporalExtent query.TemporalExtent)" required>
3232
Specify the time interval for which data should be queried.
3333
Right now, a temporal extent is required for every query.
3434
</ParamField>

‎api-reference/go/workflows/Jobs.List.mdx

Lines changed: 0 additions & 47 deletions
This file was deleted.

‎api-reference/go/workflows/Jobs.Query.mdx

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: Client.Jobs.Query
3+
sidebarTitle: Jobs.Query
4+
icon: diagram-project
5+
---
6+
7+
```go
8+
func (*JobClient) Query(
9+
ctx context.Context,
10+
options ...job.QueryOption,
11+
) iter.Seq2[*workflows.Job, error]
12+
```
13+
14+
Query jobs in the specified interval.
15+
16+
The jobs are lazily loaded and returned as a sequence of Jobs.
17+
The jobs are returned sorted by creation time in reverse order.
18+
The output sequence can be transformed into a slice of Job using [Collect](/api-reference/go/workflows/Collect) function.
19+
20+
## Parameters
21+
22+
<ParamField path="options" type="[]job.QueryOption">
23+
Options for querying jobs
24+
</ParamField>
25+
26+
## Options
27+
28+
<ParamField path="WithTemporalExtent(temporalExtent query.TemporalExtent)" required>
29+
Specify the time interval for which data should be queried.
30+
Right now, a temporal extent is required for every query.
31+
</ParamField>
32+
<ParamField path="WithAutomationID(automationID uuid.UUID)">
33+
Specify the automation id for which data should be queried.
34+
Only jobs that were created by the specified automation will be returned.
35+
</ParamField>
36+
37+
## Returns
38+
39+
A sequence of jobs.
40+
41+
<RequestExample>
42+
```go Go
43+
import (
44+
"time"
45+
workflows "github.com/tilebox/tilebox-go/workflows/v1"
46+
"github.com/tilebox/tilebox-go/workflows/v1/job"
47+
"github.com/tilebox/tilebox-go/query"
48+
)
49+
50+
interval := query.NewTimeInterval(
51+
time.Now().Add(-24 * time.Hour),
52+
time.Now(),
53+
)
54+
55+
jobs, err := workflows.Collect(
56+
client.Jobs.Query(ctx,
57+
job.WithTemporalExtent(interval),
58+
),
59+
)
60+
```
61+
</RequestExample>

‎api-reference/python/tilebox.workflows/JobClient.find.mdx

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: JobClient.find
3+
icon: diagram-project
4+
---
5+
6+
```python
7+
def JobClient.find(job_or_id: Job | str) -> Job
8+
```
9+
10+
Get a job by its id. Can also be an existing job object, in which case this method acts as a refresh operation to fetch the latest job details.
11+
12+
## Parameters
13+
14+
<ParamField path="job_or_id" type="Job | str">
15+
The job or job id to get.
16+
</ParamField>
17+
18+
## Returns
19+
20+
A job object.
21+
22+
<RequestExample>
23+
```python Python
24+
job = job_client.find("0195c87a-49f6-5ffa-e3cb-92215d057ea6")
25+
```
26+
</RequestExample>

‎api-reference/python/tilebox.workflows/JobClient.query.mdx

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: JobClient.query
3+
icon: diagram-project
4+
---
5+
6+
```python
7+
def JobClient.query(
8+
temporal_extent: TimeIntervalLike | IDIntervalLike,
9+
automation_id: UUID | None = None,
10+
) -> list[Job]
11+
```
12+
13+
Query jobs in the specified interval.
14+
15+
## Parameters
16+
17+
<ParamField path="temporal_extent" type="TimeIntervalLike | IDIntervalLike" required>
18+
The temporal extent to filter jobs by. If an `IDInterval` is given, jobs are filtered by their job id instead of their creation time.
19+
It can be specified in the following ways:
20+
- TimeInterval: interval -> Use the time interval as its given
21+
- DatetimeScalar: [time, time] -> Construct a TimeInterval with start and end time set to the given
22+
value and the end time inclusive
23+
- tuple of two DatetimeScalar: [start, end) -> Construct a TimeInterval with the given start and
24+
end time
25+
- `IDInterval`: interval -> Use the ID interval as its given
26+
- tuple of two UUIDs: [start, end) -> Construct an `IDInterval` with the given start and end id
27+
- tuple of two strings: [start, end) -> Construct an `IDInterval` with the given start and end id
28+
parsed from the strings
29+
</ParamField>
30+
<ParamField path="automation_id" type="UUID | None">
31+
The automation id to filter jobs by. If not provided, jobs from all automations are returned.
32+
</ParamField>
33+
34+
## Returns
35+
36+
A list of jobs.
37+
38+
<RequestExample>
39+
```python Python
40+
jobs = job_client.query(("2025-01-01", "2025-02-01"))
41+
```
42+
</RequestExample>

‎api-reference/python/tilebox.workflows/JobClient.retry.mdx

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ icon: diagram-project
44
---
55

66
```python
7-
def JobClient.retry(job_or_id: Job | str)
7+
def JobClient.retry(job_or_id: Job | str) -> int
88
```
99

1010
Retry a job. All failed tasks will become queued again, and queued tasks will be picked up by task runners again.
@@ -15,8 +15,12 @@ Retry a job. All failed tasks will become queued again, and queued tasks will be
1515
The job or job id to retry.
1616
</ParamField>
1717

18+
## Returns
19+
20+
The number of tasks that were rescheduled.
21+
1822
<RequestExample>
1923
```python Python
20-
job_client.retry(job)
24+
nb_rescheduled = job_client.retry(job)
2125
```
2226
</RequestExample>

‎mint.json

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -222,9 +222,11 @@
222222
"api-reference/python/tilebox.workflows/JobCache.group",
223223
"api-reference/python/tilebox.workflows/JobCache.__iter__",
224224
"api-reference/python/tilebox.workflows/JobClient.submit",
225+
"api-reference/python/tilebox.workflows/JobClient.find",
225226
"api-reference/python/tilebox.workflows/JobClient.retry",
226227
"api-reference/python/tilebox.workflows/JobClient.cancel",
227-
"api-reference/python/tilebox.workflows/JobClient.visualize"
228+
"api-reference/python/tilebox.workflows/JobClient.visualize",
229+
"api-reference/python/tilebox.workflows/JobClient.query"
228230
]
229231
}
230232
]
@@ -273,7 +275,7 @@
273275
"api-reference/go/workflows/Jobs.Get",
274276
"api-reference/go/workflows/Jobs.Retry",
275277
"api-reference/go/workflows/Jobs.Cancel",
276-
"api-reference/go/workflows/Jobs.List",
278+
"api-reference/go/workflows/Jobs.Query",
277279
"api-reference/go/workflows/Collect"
278280
]
279281
}

‎workflows/concepts/jobs.mdx

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,42 @@ myJob, err := client.Jobs.Submit(ctx, "my-job", cluster,
8686

8787
In this example, if `MyFlakyTask` fails, it will be retried up to five times before being marked as failed.
8888

89+
## Querying jobs
90+
91+
You can query jobs in a given time range using the `query` method on the job client.
92+
93+
<CodeGroup>
94+
```python Python
95+
jobs = job_client.query(("2025-01-01", "2025-02-01"))
96+
print(jobs)
97+
```
98+
```go Go
99+
import (
100+
"time"
101+
workflows "github.com/tilebox/tilebox-go/workflows/v1"
102+
"github.com/tilebox/tilebox-go/workflows/v1/job"
103+
"github.com/tilebox/tilebox-go/query"
104+
)
105+
106+
interval := query.NewTimeInterval(
107+
time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC),
108+
time.Date(2025, 2, 1, 0, 0, 0, 0, time.UTC),
109+
)
110+
111+
jobs, err := workflows.Collect(client.Jobs.Query(ctx,
112+
job.WithTemporalExtent(interval),
113+
))
114+
if err != nil {
115+
slog.Error("Failed to query jobs", slog.Any("error", err))
116+
return
117+
}
118+
119+
for _, job := range jobs {
120+
fmt.Println(job)
121+
}
122+
```
123+
</CodeGroup>
124+
89125
## Retrieving a specific job
90126

91127
When you submit a job, it's assigned a unique identifier that can be used to retrieve it later.
@@ -522,7 +558,7 @@ job_client.retry(job)
522558
job_client.display(job)
523559
```
524560
```go Go
525-
err = client.Jobs.Retry(ctx, job.ID)
561+
_, err := client.Jobs.Retry(ctx, job.ID)
526562
```
527563
</CodeGroup>
528564

0 commit comments

Comments
 (0)