Class JobQueryBuilder

Namespace

CivitaiSharp.Sdk.Request

Assembly

CivitaiSharp.Sdk.dll

Immutable, thread-safe builder for querying and managing job status. Each fluent method returns a new builder instance, allowing safe reuse and caching of base configurations.

public sealed record JobQueryBuilder : IEquatable<JobQueryBuilder>

Inheritance

object

JobQueryBuilder

Implements

IEquatable<JobQueryBuilder>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Methods

CancelAsync(Guid, bool, CancellationToken)

Cancels a specific job by its unique identifier.

public Task<Result<Unit>> CancelAsync(Guid jobId, bool force = true, CancellationToken cancellationToken = default)

Parameters

jobId Guid

The unique job identifier.

force bool

If true, cancels even if the job is processing. Default is true.

cancellationToken CancellationToken

Token to cancel the asynchronous operation.

Returns

Task<Result<Unit>>

A task representing the cancellation operation.

Exceptions

ArgumentOutOfRangeException

Thrown if jobId is empty.

CancelAsync(string, bool, CancellationToken)

Cancels jobs by their batch token.

public Task<Result<Unit>> CancelAsync(string token, bool force = true, CancellationToken cancellationToken = default)

Parameters

token string

The batch token from a previous job submission.

force bool

If true, cancels even if jobs are processing. Default is true.

cancellationToken CancellationToken

Token to cancel the asynchronous operation.

Returns

Task<Result<Unit>>

A task representing the cancellation operation.

Exceptions

ArgumentException

Thrown if token is null or whitespace.

ExecuteAsync(CancellationToken)

Executes a query for jobs matching the configured property filters.

public Task<Result<JobStatusCollection>> ExecuteAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Token to cancel the asynchronous operation.

Returns

Task<Result<JobStatusCollection>>

A task containing the matching jobs.

Remarks

Use WhereProperty or WhereProperties(IReadOnlyDictionary<string, JsonElement>) to add filters before calling this method.

Exceptions

InvalidOperationException

Thrown if no property filters are configured.

GetByIdAsync(Guid, CancellationToken)

Gets the status of a specific job by its unique identifier.

public Task<Result<JobStatus>> GetByIdAsync(Guid jobId, CancellationToken cancellationToken = default)

Parameters

jobId Guid

The unique job identifier.

cancellationToken CancellationToken

Token to cancel the asynchronous operation.

Returns

Task<Result<JobStatus>>

A task containing the job status.

Exceptions

ArgumentOutOfRangeException

Thrown if jobId is empty.

GetByTokenAsync(string, CancellationToken)

Gets the status of jobs by their batch token from a previous submission.

public Task<Result<JobStatusCollection>> GetByTokenAsync(string token, CancellationToken cancellationToken = default)

Parameters

token string

The batch token from a previous job submission.

cancellationToken CancellationToken

Token to cancel the asynchronous operation.

Returns

Task<Result<JobStatusCollection>>

A task containing the job status collection.

Exceptions

ArgumentException

Thrown if token is null or whitespace.

TaintAsync(Guid, CancellationToken)

Marks a specific job as tainted by its unique identifier.

public Task<Result<Unit>> TaintAsync(Guid jobId, CancellationToken cancellationToken = default)

Parameters

jobId Guid

The unique job identifier.

cancellationToken CancellationToken

Token to cancel the asynchronous operation.

Returns

Task<Result<Unit>>

A task representing the taint operation.

Exceptions

ArgumentOutOfRangeException

Thrown if jobId is empty.

TaintAsync(string, CancellationToken)

Marks jobs as tainted by their batch token.

public Task<Result<Unit>> TaintAsync(string token, CancellationToken cancellationToken = default)

Parameters

token string

The batch token from a previous job submission.

cancellationToken CancellationToken

Token to cancel the asynchronous operation.

Returns

Task<Result<Unit>>

A task representing the taint operation.

Exceptions

ArgumentException

Thrown if token is null or whitespace.

WhereProperties(IReadOnlyDictionary<string, JsonElement>)

Adds multiple custom property filters to the query.

public JobQueryBuilder WhereProperties(IReadOnlyDictionary<string, JsonElement> properties)

Parameters

properties IReadOnlyDictionary<string, JsonElement>

Dictionary of property key-value pairs to filter by.

Returns

JobQueryBuilder

A new builder instance with the added property filters.

Remarks

Multiple property filters are combined with AND logic - all must match.

WhereProperty(string, bool)

Adds a custom boolean property filter to the query.

public JobQueryBuilder WhereProperty(string key, bool value)

Parameters

key string

The property key to filter by.

value bool

The boolean value to match.

Returns

JobQueryBuilder

A new builder instance with the added property filter.

WhereProperty(string, DateTime)

Adds a custom DateTime property filter to the query.

public JobQueryBuilder WhereProperty(string key, DateTime value)

Parameters

key string

The property key to filter by.

value DateTime

The DateTime value to match.

Returns

JobQueryBuilder

A new builder instance with the added property filter.

WhereProperty(string, decimal)

Adds a custom decimal property filter to the query.

public JobQueryBuilder WhereProperty(string key, decimal value)

Parameters

key string

The property key to filter by.

value decimal

The decimal value to match.

Returns

JobQueryBuilder

A new builder instance with the added property filter.

WhereProperty(string, Guid)

Adds a custom GUID property filter to the query.

public JobQueryBuilder WhereProperty(string key, Guid value)

Parameters

key string

The property key to filter by.

value Guid

The GUID value to match.

Returns

JobQueryBuilder

A new builder instance with the added property filter.

WhereProperty(string, int)

Adds a custom integer property filter to the query.

public JobQueryBuilder WhereProperty(string key, int value)

Parameters

key string

The property key to filter by.

value int

The integer value to match.

Returns

JobQueryBuilder

A new builder instance with the added property filter.

WhereProperty(string, long)

Adds a custom long property filter to the query.

public JobQueryBuilder WhereProperty(string key, long value)

Parameters

key string

The property key to filter by.

value long

The long value to match.

Returns

JobQueryBuilder

A new builder instance with the added property filter.

WhereProperty(string, string)

Adds a custom string property filter to the query.

public JobQueryBuilder WhereProperty(string key, string value)

Parameters

key string

The property key to filter by.

value string

The string value to match.

Returns

JobQueryBuilder

A new builder instance with the added property filter.

WithDetailed()

Configures the query to include detailed job specifications in responses.

public JobQueryBuilder WithDetailed()

Returns

JobQueryBuilder

A new builder instance with detailed mode enabled.

WithWait()

Configures the query to wait for job completion (blocks up to ~10 minutes).

public JobQueryBuilder WithWait()

Returns

JobQueryBuilder

A new builder instance with wait mode enabled.

Remarks

When enabled, the API will block until jobs complete or timeout (~10 minutes). This is useful when you need immediate results without manual polling.