# Filtering and queries

Source: https://libtmux.org/en/java/latest/concepts/queries/

> How you get from every session on the server to the one pane you mean, and what happens when zero or several match.

Use a collection filter to find matching sessions, windows, or panes. Use an
exactly-one lookup when your next operation requires a single target.

- **Filtering returns a collection; exactly-one lookup checks the result
  count.** A filter returns zero or more matches. An exactly-one operation
  returns one object or reports a missing or ambiguous match.

- **Choose where to filter.** Filter a snapshot in your program when you need
  several queries over the same data. A tmux format filter can reduce the rows
  returned by a live read. The cost depends on the data and queries you need.

<a id="go-rust-java-c-typed-fields-that-fail-queries-at-compile-time"></a>

## Typed and local filters

Typed field operations let the compiler reject incompatible comparisons:

[`Pane_`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-pane_-pane_/>), [`Window_`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-window_-window_/>), and [`Session_`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-session_-session_/>) expose typed field accessors for stream
predicates. A numeric field has no [`startsWith`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-query-fields-fields-textfield-startswith/>) operation. Use
[`Selections.exactlyOne`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-query-selections-selections-exactlyone/>) to reject absent or ambiguous matches.

Examples of typed and local filters:

```java
List<Window> editors = server.windows().stream()
        .filter(Window_.name().startsWith("edit"))
        .toList();

// Selections.exactlyOne() is the `.get()`-shaped call.
Session build = Selections.exactlyOne(
        server.sessions().stream().filter(Session_.name().is("build")).toList());
```

<a id="the-cardinality-contract-side-by-side"></a>

## Result counts

Filter with [`Stream.filter`](<https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/stream/Stream.html#filter(java.util.function.Predicate)>) and require one match with
[`Selections.exactlyOne`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-query-selections-selections-exactlyone/>). Empty and multiple results raise
[`CardinalityException.NoMatch`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-exception-cardinalityexception-cardinalityexception-nomatch/>) and [`CardinalityException.MultipleMatches`](<https://libtmux.org/en/java/latest/reference/io-github-libtmux-exception-cardinalityexception-cardinalityexception-multiplematches/>),
respectively.

[Filtering and querying](https://libtmux.org/en/java/latest/guides/querying-and-filtering/) shows exactly-one
lookups and their error handling. Do not index the first result until the
operation has established that a match exists.