# libtmux.query

- **Package:** libtmux/query
- **Language:** Common Lisp
- **Kind:** module
- **Source:** https://github.com/libtmux/libtmux-lisp/blob/c2e5fc4ed3befda21f45dfa5d5868c38fd138311/src/query.lisp#L1
- **Page:** https://libtmux.org/en/lisp/latest/reference/libtmux-query/

Validated native queries over finite captured libtmux observations.
Loading this package adds no transport dependency and performs no tmux I/O.

## Members

### Common operations

- [`matching`](/en/lisp/latest/reference/libtmux-query-matching/) (function): Return a fresh simple vector of VALUES accepted by FILTER.
VALUES must be a finite list or non-string vector. The result preserves order,
multiplicity and the original captured handles. MAX-ITEMS bounds validation.
One execution budget is shared across the entire traversal; no I/O occurs.
- [`ambiguous-match`](/en/lisp/latest/reference/libtmux-query-ambiguous-match/) (exception): Strict selection received more than one item.
- [`compile-filter`](/en/lisp/latest/reference/libtmux-query-compile-filter/) (function): Compile FORM for captured MODEL into an owned local filter.
Scalar and registered relation operators perform no I/O and never evaluate
FORM as Lisp code. Regex operators require the optional regex system.
Keyword limits bound container depth, input visits, membership size, copied
character counts and later predicate execution. Limit failures signal
QUERY-LIMIT-EXCEEDED; malformed or mistyped forms signal INVALID-FILTER.
- [`fields`](/en/lisp/latest/reference/libtmux-query-fields/) (function): Return fresh field metadata for one captured query MODEL in key order.
MODEL is one of :SESSION, :WINDOW, :PANE, :WINDOW-LINK or :CLIENT. Wire bounds
describe capture decoding and do not restrict native query integer operands.
- [`from`](/en/lisp/latest/reference/libtmux-query-from/) (function): Copy finite VALUES into an eager local QUERY-SET.
VALUES is a proper list, non-string vector or another query set. MODEL may name
one registered captured entity model; omit it for unrestricted ordinary data.
- [`invalid-filter`](/en/lisp/latest/reference/libtmux-query-invalid-filter/) (exception): A declarative filter is malformed, mistyped or exceeds a compile limit.
- [`invalid-query-target`](/en/lisp/latest/reference/libtmux-query-invalid-query-target/) (exception): A compiled filter received an object outside its captured root model.
- [`items`](/en/lisp/latest/reference/libtmux-query-items/) (function): Return a fresh simple vector containing SET's selected items in order.
- [`no-match`](/en/lisp/latest/reference/libtmux-query-no-match/) (exception): Strict selection received no items.
- [`one`](/en/lisp/latest/reference/libtmux-query-one/) (function): Return the only item in finite VALUES.
Signal NO-MATCH for zero items or AMBIGUOUS-MATCH for more than one. The full
bounded container is validated before a candidate is returned. NIL is an item.
- [`one-or-none`](/en/lisp/latest/reference/libtmux-query-one-or-none/) (function): Return the only item and T, or NIL,NIL when finite VALUES is empty.
Signal AMBIGUOUS-MATCH for more than one item after validating the full bounded
container. A singleton containing NIL returns NIL,T.
- [`order-by`](/en/lisp/latest/reference/libtmux-query-order-by/) (function): Return a new query set stably ordered by native PREDICATE and KEY.
PREDICATE and KEY are function objects or symbols naming global functions,
each resolved once before sorting. Invalid designators signal
LIBTMUX:INVALID-ARGUMENT. Their calls follow the STABLE-SORT callback contract.
Sorting is eager and local, mutating only a private simple-vector copy. SET
remains unchanged; items are shared and equal keys retain input order.
- [`query-limit-exceeded`](/en/lisp/latest/reference/libtmux-query-query-limit-exceeded/) (exception): A bounded query compilation, execution or selection exhausted its budget.
- [`required-relations`](/en/lisp/latest/reference/libtmux-query-required-relations/) (function): Return a fresh vector of relation fields in first-occurrence order.
- [`where`](/en/lisp/latest/reference/libtmux-query-where/) (function): Return a new query set containing SET items accepted by compiled FILTER.
Evaluation is eager and local. FILTER supplies the result model; conflicting
declared model metadata signals INVALID-QUERY-TARGET before evaluation.
- [`where-if`](/en/lisp/latest/reference/libtmux-query-where-if/) (function): Return a new query set selected by native FUNCTION in input order.
FUNCTION is a function object or a symbol naming a global function, resolved
once before traversal. Invalid designators signal LIBTMUX:INVALID-ARGUMENT.
On normal completion it has been called exactly once per item, eagerly and
locally. Its effects and call order are never optimized as declarative data.
The result owns its container and shares the selected items with SET.

### Other members

- [`compiled-filter`](/en/lisp/latest/reference/libtmux-query-compiled-filter/) (class): An owned validated expression and reusable local evaluator.
- [`count-exact-p`](/en/lisp/latest/reference/libtmux-query-count-exact-p/) (function): Return true when MATCH-COUNT is exact, false when it is a lower bound.
- [`error-expected`](/en/lisp/latest/reference/libtmux-query-error-expected/) (function): Return an owned bounded description of the expected query shape or type.
- [`error-operator`](/en/lisp/latest/reference/libtmux-query-error-operator/) (function): Return a bounded invalid-operator summary, or NIL.
- [`error-path`](/en/lisp/latest/reference/libtmux-query-error-path/) (function): Return a fresh bounded vector locating the invalid query input.
- [`error-received`](/en/lisp/latest/reference/libtmux-query-error-received/) (function): Return a safe bounded description of the received query value or target.
- [`explain`](/en/lisp/latest/reference/libtmux-query-explain/) (function): Return fresh execution metadata for FILTER. Query execution is local and acquires nothing.
- [`expression`](/en/lisp/latest/reference/libtmux-query-expression/) (function): Return a fresh ordinary-data copy of FILTER's canonical native expression.
- [`match-count`](/en/lisp/latest/reference/libtmux-query-match-count/) (function): Return the known cardinality associated with a selection condition.
- [`match-sample`](/en/lisp/latest/reference/libtmux-query-match-sample/) (function): Return a fresh bounded vector of safe selected-item summaries.
- [`predicate`](/en/lisp/latest/reference/libtmux-query-predicate/) (function): Return a genuine one-argument function that evaluates FILTER locally.
Each invocation receives a fresh execution budget and performs no tmux I/O.
- [`query-set`](/en/lisp/latest/reference/libtmux-query-query-set/) (class): An eager owned local selection with optional captured-model metadata.
- [`query-set-model`](/en/lisp/latest/reference/libtmux-query-query-set-model/) (function): Return SET's declared captured model, or NIL for untyped ordinary data.
- [`required-fields`](/en/lisp/latest/reference/libtmux-query-required-fields/) (function): Return a fresh vector of scalar fields in first-occurrence order.

## Guides

Pages that discuss `libtmux.query`.

- [Getting started](/en/lisp/latest/guides/getting-started/)
- [REPL tutorial](/en/lisp/latest/guides/tutorial/)