More advanced querying on JobListParams.Metadata()

Start in job_list_params.go with JobListParams, NewJobListParams, Metadata, and toDBParams, then trace how client.JobList consumes the converted parameters. Review the proposed Where behavior alongside existing conditions and copying semantics. Done means the maintainer-approved API supports the metadata query example without breaking existing filters, with the requested documentation and tests.

Right now JobListParams.Metadata() only offers querying via metadata >@ …, but I'd like to do slightly more advanced stuff. For example if the metadata contains:

{"object_id": 42}

And I'd like to list all jobs that match any of a set:

objectsUserHasAccessTo := []int{1, 5, 42}

params := NewJobListParams().Where(
    `(metadata->'object_id')::int = any(@objects)`,
    map[string]any{"objects": objectsUserHasAccessTo},
)

client.JobList(ctx, params)

I don't mind writing a patch for this; the simplest would be to just allow appending to the condition list and argument map, via the patch below. Although arguably that would give too much control (and the ability to do very stupid things).

Then again, restricting this would probably more trouble than its worth(?) The alternative is writing my own query from scratch, which allows for even more stupid stuff.

Well, let me know what you want and I'll submit a working patch with docs, tests, etc.

diff --git i/job_list_params.go w/job_list_params.go
index ffdc39a..7edd6f9 100644
--- i/job_list_params.go
+++ w/job_list_params.go
@@ -174,6 +174,8 @@ type JobListParams struct {
        sortField        JobListOrderByField
        sortOrder        SortOrder
        states           []rivertype.JobState
+       whereSQL         string
+       whereArgs        map[string]any
 }

 // NewJobListParams creates a new JobListParams to return available jobs sorted
@@ -263,6 +265,12 @@ func (p *JobListParams) toDBParams() (*dblist.JobListParams, error) {
                conditions = append(conditions, `metadata @> @metadata_fragment::jsonb`)
                namedArgs["metadata_fragment"] = p.metadataFragment
        }
+       if p.whereSQL != "" {
+               conditions = append(conditions, p.whereSQL)
+               for k, v := range p.whereArgs {
+                       namedArgs[k] = v
+               }
+       }

        if p.after != nil {
                if p.after.time.IsZero() { // order by ID only
@@ -346,6 +354,13 @@ func (p *JobListParams) Metadata(json string) *JobListParams {
        return paramsCopy
 }

+func (p *JobListParams) Where(sql string, args map[string]any) *JobListParams {
+       paramsCopy := p.copy()
+       paramsCopy.whereSQL = sql
+       paramsCopy.whereArgs = args
+       return paramsCopy
+}
+
 // Queues returns an updated filter set that will only return jobs from the
 // given queues.
 func (p *JobListParams) Queues(queues ...string) *JobListParams {