From e76f5c356293251c43987f7cbc053486a4c00ecf Mon Sep 17 00:00:00 2001 From: Corentin Musard Date: Fri, 23 May 2025 17:05:15 +0200 Subject: [PATCH] Document query jobs --- .../go/datasets/Datapoints.Query.mdx | 2 +- api-reference/go/workflows/Jobs.List.mdx | 47 -------------- api-reference/go/workflows/Jobs.Query.mdx | 61 +++++++++++++++++++ .../tilebox.workflows/JobClient.find.mdx | 26 ++++++++ .../tilebox.workflows/JobClient.query.mdx | 42 +++++++++++++ .../tilebox.workflows/JobClient.retry.mdx | 8 ++- mint.json | 6 +- workflows/concepts/jobs.mdx | 38 +++++++++++- 8 files changed, 177 insertions(+), 53 deletions(-) delete mode 100644 api-reference/go/workflows/Jobs.List.mdx create mode 100644 api-reference/go/workflows/Jobs.Query.mdx create mode 100644 api-reference/python/tilebox.workflows/JobClient.find.mdx create mode 100644 api-reference/python/tilebox.workflows/JobClient.query.mdx diff --git a/api-reference/go/datasets/Datapoints.Query.mdx b/api-reference/go/datasets/Datapoints.Query.mdx index 437abf5..53c4443 100644 --- a/api-reference/go/datasets/Datapoints.Query.mdx +++ b/api-reference/go/datasets/Datapoints.Query.mdx @@ -28,7 +28,7 @@ The output sequence can be transformed into a typed `proto.Message` using [Colle ## Options - + Specify the time interval for which data should be queried. Right now, a temporal extent is required for every query. diff --git a/api-reference/go/workflows/Jobs.List.mdx b/api-reference/go/workflows/Jobs.List.mdx deleted file mode 100644 index 5afff72..0000000 --- a/api-reference/go/workflows/Jobs.List.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Client.Jobs.List -sidebarTitle: Jobs.List -icon: diagram-project ---- - -```go -func (*JobClient) List( - ctx context.Context, - interval query.TemporalExtent, -) iter.Seq2[*workflows.Job, error] -``` - -List all available jobs. - -The jobs are lazily loaded and returned as a sequence of Jobs. -The jobs are returned sorted by creation time in reverse order. -The output sequence can be transformed into a slice of Job using [Collect](/api-reference/go/workflows/Collect) function. - -## Parameters - - - The interval for which to load jobs - - -## Returns - -A sequence of jobs. - - -```go Go -import ( - "time" - workflows "github.com/tilebox/tilebox-go/workflows/v1" - "github.com/tilebox/tilebox-go/query" -) - -interval := query.NewTimeInterval( - time.Now().Add(-24 * time.Hour), - time.Now(), -) - -jobs, err := workflows.Collect( - client.Jobs.List(ctx, interval), -) -``` - diff --git a/api-reference/go/workflows/Jobs.Query.mdx b/api-reference/go/workflows/Jobs.Query.mdx new file mode 100644 index 0000000..eff067a --- /dev/null +++ b/api-reference/go/workflows/Jobs.Query.mdx @@ -0,0 +1,61 @@ +--- +title: Client.Jobs.Query +sidebarTitle: Jobs.Query +icon: diagram-project +--- + +```go +func (*JobClient) Query( + ctx context.Context, + options ...job.QueryOption, +) iter.Seq2[*workflows.Job, error] +``` + +Query jobs in the specified interval. + +The jobs are lazily loaded and returned as a sequence of Jobs. +The jobs are returned sorted by creation time in reverse order. +The output sequence can be transformed into a slice of Job using [Collect](/api-reference/go/workflows/Collect) function. + +## Parameters + + + Options for querying jobs + + +## Options + + + Specify the time interval for which data should be queried. + Right now, a temporal extent is required for every query. + + + Specify the automation id for which data should be queried. + Only jobs that were created by the specified automation will be returned. + + +## Returns + +A sequence of jobs. + + +```go Go +import ( + "time" + workflows "github.com/tilebox/tilebox-go/workflows/v1" + "github.com/tilebox/tilebox-go/workflows/v1/job" + "github.com/tilebox/tilebox-go/query" +) + +interval := query.NewTimeInterval( + time.Now().Add(-24 * time.Hour), + time.Now(), +) + +jobs, err := workflows.Collect( + client.Jobs.Query(ctx, + job.WithTemporalExtent(interval), + ), +) +``` + diff --git a/api-reference/python/tilebox.workflows/JobClient.find.mdx b/api-reference/python/tilebox.workflows/JobClient.find.mdx new file mode 100644 index 0000000..afb4a37 --- /dev/null +++ b/api-reference/python/tilebox.workflows/JobClient.find.mdx @@ -0,0 +1,26 @@ +--- +title: JobClient.find +icon: diagram-project +--- + +```python +def JobClient.find(job_or_id: Job | str) -> Job +``` + +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. + +## Parameters + + + The job or job id to get. + + +## Returns + +A job object. + + +```python Python +job = job_client.find("0195c87a-49f6-5ffa-e3cb-92215d057ea6") +``` + diff --git a/api-reference/python/tilebox.workflows/JobClient.query.mdx b/api-reference/python/tilebox.workflows/JobClient.query.mdx new file mode 100644 index 0000000..625ea23 --- /dev/null +++ b/api-reference/python/tilebox.workflows/JobClient.query.mdx @@ -0,0 +1,42 @@ +--- +title: JobClient.query +icon: diagram-project +--- + +```python +def JobClient.query( + temporal_extent: TimeIntervalLike | IDIntervalLike, + automation_id: UUID | None = None, +) -> list[Job] +``` + +Query jobs in the specified interval. + +## Parameters + + + The temporal extent to filter jobs by. If an `IDInterval` is given, jobs are filtered by their job id instead of their creation time. + It can be specified in the following ways: + - TimeInterval: interval -> Use the time interval as its given + - DatetimeScalar: [time, time] -> Construct a TimeInterval with start and end time set to the given + value and the end time inclusive + - tuple of two DatetimeScalar: [start, end) -> Construct a TimeInterval with the given start and + end time + - `IDInterval`: interval -> Use the ID interval as its given + - tuple of two UUIDs: [start, end) -> Construct an `IDInterval` with the given start and end id + - tuple of two strings: [start, end) -> Construct an `IDInterval` with the given start and end id + parsed from the strings + + + The automation id to filter jobs by. If not provided, jobs from all automations are returned. + + +## Returns + +A list of jobs. + + +```python Python +jobs = job_client.query(("2025-01-01", "2025-02-01")) +``` + diff --git a/api-reference/python/tilebox.workflows/JobClient.retry.mdx b/api-reference/python/tilebox.workflows/JobClient.retry.mdx index 090cbd3..81017df 100644 --- a/api-reference/python/tilebox.workflows/JobClient.retry.mdx +++ b/api-reference/python/tilebox.workflows/JobClient.retry.mdx @@ -4,7 +4,7 @@ icon: diagram-project --- ```python -def JobClient.retry(job_or_id: Job | str) +def JobClient.retry(job_or_id: Job | str) -> int ``` 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 The job or job id to retry. +## Returns + +The number of tasks that were rescheduled. + ```python Python -job_client.retry(job) +nb_rescheduled = job_client.retry(job) ``` diff --git a/mint.json b/mint.json index 1be512f..5d8b33c 100644 --- a/mint.json +++ b/mint.json @@ -222,9 +222,11 @@ "api-reference/python/tilebox.workflows/JobCache.group", "api-reference/python/tilebox.workflows/JobCache.__iter__", "api-reference/python/tilebox.workflows/JobClient.submit", + "api-reference/python/tilebox.workflows/JobClient.find", "api-reference/python/tilebox.workflows/JobClient.retry", "api-reference/python/tilebox.workflows/JobClient.cancel", - "api-reference/python/tilebox.workflows/JobClient.visualize" + "api-reference/python/tilebox.workflows/JobClient.visualize", + "api-reference/python/tilebox.workflows/JobClient.query" ] } ] @@ -273,7 +275,7 @@ "api-reference/go/workflows/Jobs.Get", "api-reference/go/workflows/Jobs.Retry", "api-reference/go/workflows/Jobs.Cancel", - "api-reference/go/workflows/Jobs.List", + "api-reference/go/workflows/Jobs.Query", "api-reference/go/workflows/Collect" ] } diff --git a/workflows/concepts/jobs.mdx b/workflows/concepts/jobs.mdx index 716f45e..f3a5b35 100644 --- a/workflows/concepts/jobs.mdx +++ b/workflows/concepts/jobs.mdx @@ -86,6 +86,42 @@ myJob, err := client.Jobs.Submit(ctx, "my-job", cluster, In this example, if `MyFlakyTask` fails, it will be retried up to five times before being marked as failed. +## Querying jobs + +You can query jobs in a given time range using the `query` method on the job client. + + +```python Python +jobs = job_client.query(("2025-01-01", "2025-02-01")) +print(jobs) +``` +```go Go +import ( + "time" + workflows "github.com/tilebox/tilebox-go/workflows/v1" + "github.com/tilebox/tilebox-go/workflows/v1/job" + "github.com/tilebox/tilebox-go/query" +) + +interval := query.NewTimeInterval( + time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC), + time.Date(2025, 2, 1, 0, 0, 0, 0, time.UTC), +) + +jobs, err := workflows.Collect(client.Jobs.Query(ctx, + job.WithTemporalExtent(interval), + )) +if err != nil { + slog.Error("Failed to query jobs", slog.Any("error", err)) + return +} + +for _, job := range jobs { + fmt.Println(job) +} +``` + + ## Retrieving a specific job 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) job_client.display(job) ``` ```go Go -err = client.Jobs.Retry(ctx, job.ID) +_, err := client.Jobs.Retry(ctx, job.ID) ```