# `Zizq.Filter`
[🔗](https://github.com/zizq-labs/zizq-elixir/blob/v0.8.0/lib/zizq/filter.ex#L4)

Filters shared by every endpoint that selects jobs.

`Zizq.list_jobs/2`, `Zizq.count_jobs/2` and the bulk operations all
narrow the same way, so the vocabulary is described once here.

    Zizq.count_jobs([queue: "emails", status: [:ready, :scheduled]], MyApp.Zizq)

## Options

  * `:id` — one job id, or a list of them.
  * `:queue` — one queue name, or a list.
  * `:type` — one job type, or a list.
  * `:status` — one status atom, or a list.
  * `:budgets_key` — one budget key, or a list. Matches a job bound
    to any of them.
  * `:priority` — a number, a `Range`, or `[min: _, max: _]`.
  * `:ready_at` — the same, over `DateTime`s or milliseconds.
  * `:attempts` — the same, over attempt counts.
  * `:filter` — a jq expression run against each payload, e.g.
    `".user_id == 42"`.

An option left out does not narrow anything. A list matches any of
its members, so `status: [:ready, :scheduled]` finds jobs in either.

## Ranges

Ranges are inclusive at both ends. A bare number matches exactly:

    priority: 5           # exactly 5
    priority: 1..10       # 1 to 10
    priority: [min: 5]    # 5 and above
    priority: [max: 5]    # 5 and below

`:ready_at` accepts `DateTime`s as well as milliseconds, so a window
reads as one:

    ready_at: [min: DateTime.utc_now()]

## Budgets

`:budgets_key` selects by what a job is bound to, which is useful
for finding what is holding a budget in use — `Zizq.delete_budget/2`
refuses while anything remains bound:

    Zizq.query(MyApp.Zizq)
    |> Zizq.Query.where(budgets_key: "emails")
    |> Zizq.Query.unbind_budget("emails")

# `matches_nothing?`

```elixir
@spec matches_nothing?(keyword() | map()) :: boolean()
```

Whether these filters can match nothing at all.

A set filter given an empty list selects no jobs, but omitting it
from the query string would select *every* job — so the two must not
be confused. Callers check this and answer their own zero rather than
sending a request:

    Zizq.delete_all_jobs([queue: []], MyApp.Zizq)   # => {:ok, 0}

This matters most where the list is computed. `queue: Enum.filter(...)`
coming back empty must delete nothing, not everything.

An empty string counts the same way, since it encodes to the same
absent parameter.

---

*Consult [api-reference.md](api-reference.md) for complete listing*