# `PhoenixReplay.Recording.Filter`
[🔗](https://github.com/elixir-vibe/phoenix_replay/blob/v0.6.2/lib/phoenix_replay/recording/filter.ex#L1)

Criteria for narrowing a list of `PhoenixReplay.Recording.Summary` structs.

Filters round-trip through URL query parameters, so a filtered dashboard
view can be shared as a link:

  * `"q"` — text found in the recording's URL, id, event names, mark
    names, source or campaign
  * `"view"` — exact view module name, such as `"MyAppWeb.CheckoutLive"`
  * `"event"` — a `handle_event/3` name the session triggered
  * `"mark"` — the name of a moment the session reached; see
    `PhoenixReplay.Recording.Event.mark_name/1`
  * `"source"`, `"medium"` and `"campaign"` — where the visit came from,
    such as `"google"`, `"cpc"` and `"spring"`; see
    `PhoenixReplay.Recording.Client.traffic/1`
  * `"device_type"` — `"phone"`, `"tablet"` or `"desktop"`
  * `"browser"` — the browser's family, such as `"Mobile Safari"`
  * `"release"` — the release the session was recorded with; see
    `PhoenixReplay.Recording.Code`
  * `"within"` — `"15m"`, `"1h"`, `"24h"`, `"7d"` or `"30d"` since the
    session started
  * `"from"` and `"to"` — the session started within this time range,
    each an ISO 8601 time such as `"2026-10-06T14:00:00Z"`
  * `"longer_than"` — a minimum duration, in seconds
  * `"min_events"` — minimum number of recorded events
  * `"errors"` — `"1"` to keep only sessions with an error, such as an
    error log, a failed query or a crash
  * `"tab"` — sessions from one browser tab, a user's journey

Blank or invalid parameters are ignored.

# `bucket`

```elixir
@type bucket() :: {integer(), pos_integer(), non_neg_integer()}
```

Sessions started in one stretch of time: its start, how many, and how many with an error.

# `field`

```elixir
@type field() ::
  :view
  | :event
  | :mark
  | :source
  | :medium
  | :campaign
  | :device_type
  | :browser
  | :release
```

A criterion whose values can be listed and counted, for suggesting them:
see `values_of/2`.

# `page_opts`

```elixir
@type page_opts() :: [
  now: integer(),
  until: integer() | nil,
  since: integer() | nil,
  offset: non_neg_integer(),
  limit: non_neg_integer(),
  utc_offset: integer()
]
```

Which page of matching summaries to read:

  * `:now` — the current time in Unix milliseconds, for `"within"`
  * `:until` — only recordings saved at or before this time, so pages stay
    put while sessions end; see `PhoenixReplay.Recording.Summary.stored_at/1`
  * `:since` — only recordings saved after this time
  * `:offset` and `:limit` — the slice to return
  * `:utc_offset` — for counts by start time, how far the viewer's time
    zone is ahead of UTC, in milliseconds; see `histogram/4`

# `t`

```elixir
@type t() :: %PhoenixReplay.Recording.Filter{
  browser: String.t() | nil,
  campaign: String.t() | nil,
  device_type: PhoenixReplay.Recording.Client.device_type() | nil,
  errors: boolean(),
  event: String.t() | nil,
  from: integer() | nil,
  longer_than: pos_integer() | nil,
  mark: String.t() | nil,
  medium: String.t() | nil,
  min_events: pos_integer() | nil,
  query: String.t() | nil,
  release: String.t() | nil,
  source: String.t() | nil,
  tab: String.t() | nil,
  to: integer() | nil,
  view: String.t() | nil,
  within: String.t() | nil
}
```

# `bucket`

```elixir
@spec bucket(integer(), pos_integer(), integer()) :: integer()
```

The start of the stretch of `size` milliseconds that `at` falls in, in
a time zone `utc_offset` milliseconds ahead of UTC.

# `count_values`

```elixir
@spec count_values(
  [PhoenixReplay.Recording.Summary.t()],
  field(),
  t(),
  integer(),
  pos_integer()
) :: [
  {String.t(), pos_integer()}
]
```

Counts the values of `field` among the `summaries` matching `filter`,
ignoring the filter's own criterion on `field`, so the other values
stay on offer: the most common first, at most `limit`. `now` is in Unix
milliseconds, for `"within"`.

# `empty?`

```elixir
@spec empty?(t()) :: boolean()
```

Returns true when no criteria are set.

# `fields`

```elixir
@spec fields() :: [field()]
```

The criteria whose values can be listed; see `t:field/0`.

# `from_params`

```elixir
@spec from_params(map()) :: t()
```

Builds a filter from string-keyed query parameters.

# `histogram`

```elixir
@spec histogram(
  [PhoenixReplay.Recording.Summary.t()],
  t(),
  pos_integer(),
  page_opts()
) :: [bucket()]
```

Counts the `summaries` matching `filter` by when they started, in
stretches of `size` milliseconds, earliest first; see `t:bucket/0`.
Stretches begin at midnights and hours of the viewer's time zone,
`:utc_offset` milliseconds ahead of UTC (default `0`); `:now` is for
`"within"`.

# `page`

```elixir
@spec page([PhoenixReplay.Recording.Summary.t()], t(), page_opts()) ::
  {[PhoenixReplay.Recording.Summary.t()], non_neg_integer()}
```

Reads a page of `summaries`, which are ordered most recent first, and
counts every summary that matches. See `t:page_opts/0`.

# `select`

```elixir
@spec select([PhoenixReplay.Recording.Summary.t()], t(), integer()) :: [
  PhoenixReplay.Recording.Summary.t()
]
```

Keeps the summaries matching every criterion. `now` is in Unix milliseconds.

# `started_after`

```elixir
@spec started_after(t(), integer()) :: integer() | nil
```

The earliest start time `"within"` allows at `now`, in Unix milliseconds,
or `nil` without it.

# `time_range`

```elixir
@spec time_range(t(), integer()) :: {integer(), integer()}
```

The stretch of time `filter` covers at `now`, in Unix milliseconds: its
window, its range, completed by the last 30 days or now where it is
open, or the last 30 days without either.

# `to_params`

```elixir
@spec to_params(t()) :: %{optional(String.t()) =&gt; String.t()}
```

Converts a filter back to query parameters, omitting unset criteria.

# `top`

```elixir
@spec top(
  %{required(String.t()) =&gt; pos_integer()} | [{String.t(), pos_integer()}],
  pos_integer()
) :: [
  {String.t(), pos_integer()}
]
```

The most common of counted values, then by value, at most `limit`.

# `values_of`

```elixir
@spec values_of(PhoenixReplay.Recording.Summary.t(), field()) :: [String.t()]
```

The values a summary has for `field`, such as its view or its event names.

# `windows`

```elixir
@spec windows() :: [String.t()]
```

The supported `"within"` values, shortest first.

---

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