Transaction Filtering and Search#

Overview#

The transaction list (GET /transactions) supports multi-dimensional filtering via a form-based search backed by two model classes: Transaction::Search and EntrySearch. All filters are applied as composable ActiveRecord scope chains — there is no user-controlled sort order; the list is always ordered reverse-chronological 1.

The eight available filter dimensions are defined in TransactionsHelper#transaction_search_filters:

A free-text search field (entry name / notes ILIKE) is also available alongside the structured filters 2.

Key Source Files#

Architecture#

Transaction::Search#

Transaction::Search is an ActiveModel::Model with one attribute per filter dimension. Its transactions_scope method chains filters in order:

1. Scopes to family.transactions and strips split-parent rows 3
2. Restricts to accessible_account_ids for permission scoping 4
3. Applies active_accounts_only (draft/active accounts by default) 5
4. Delegates to private apply_* methods and EntrySearch class methods 6

EntrySearch#

EntrySearch provides reusable class methods called directly by Transaction::Search:

• apply_search_filter — ILIKE on entries.name and entries.notes (SQL-injection-safe via sanitize_sql_like)
• apply_date_filters — entries.date >= start_date / <= end_date
• apply_amount_filter — compares ABS(entries.amount) with ±0.01 tolerance for equal
• apply_accounts_filter — by account name or account ID

Transaction-specific filters#

Implemented privately in Transaction::Search:

• Category (apply_category_filter) — matches by category name or parent ID; "Uncategorized" maps to categories.id IS NULL AND kind NOT IN (TRANSFER_KINDS) 7
• Type (apply_type_filter) — maps user-facing income/expense/transfer to amount sign + TRANSFER_KINDS conditions; selecting all three is a no-op 8
• Status (apply_status_filter) — delegates to Transaction.pending / Transaction.excluding_pending scopes sourced from PENDING_PROVIDERS; selecting both is a no-op 9
• Merchant (apply_merchant_filter) — inner join on merchants.name
• Tag (apply_tag_filter) — inner join on tags.name

Controller wiring#

TransactionsController#index builds @search, calls transactions_scope.reverse_chronological, and paginates via pagy. The search_params method allows the full set of filter keys. Filter state is persisted in Current.session.prev_transaction_page_params and restored on bare /transactions visits 10.

UI#

The search UI is a form (scope: :q, auto-submit via data-controller="auto-submit-form") at _form.html.erb. Structured filters live in a DS::Popover that renders transactions/searches/menu, which in turn renders individual partials via TransactionsHelper#get_transaction_search_filter_partial_path 11.

Each filter dimension has its own partial under app/views/transactions/searches/filters/:

• Multi-select (account, category, merchant, tag): searchable checkbox lists using a list-filter JS controller
• Checkboxes (type, status): hardcoded options — type: income/expense/transfer; status: confirmed/pending 12 13
• Date range: start_date / end_date date inputs 14
• Amount: numeric input + amount_operator select (equal, greater, less) 15

Totals Bar#

Transaction::Search#totals computes income, expense, transfer inflow/outflow, and transaction count for the current filter state 16. Results are cached under a SHA-256 key of the filter attributes + family.entries_cache_version 17. Tax-advantaged accounts (401k, IRA, etc.) are excluded from totals 18.

Related Topics#

• Dashboard Filtering and Drilldowns — chart-based drilldowns pass pre-built q[types][], q[status][], and date params to transactions_path 19
• Transaction Categorization — apply_category_filter and the "Uncategorized" special case are documented in Transaction Categorization
• Transaction Exclusion — the base scope does not filter by excluded; there is no "excluded" filter option 20