# Search & Queries

**Bkper Search** uses a powerful query language for filtering transactions and balance values. This same language works across the Bkper web app, the [Bkper Add-on for Google Sheets](https://bkper.com/docs/guides/google-sheets.md), [Bkper Functions](https://github.com/bkper/bkper-sheets#functions-reference), and Google Apps Script — so a query that works in one place works everywhere.

Search results display matching transactions along with corresponding balance values (shown in charts). On the Bkper Add-on for Google Sheets, results can also be fetched as balance values and/or transactions.

## Search Assistant

The Search Assistant guides you through building queries visually. Access it from the search bar at the top of any Book.

![The Bkper search bar where the Search Assistant is accessed](https://bkper.com/docs/_astro/search-assistant-1.DU2yEmO-.png)

Type the term you are looking for and the Search Assistant suggests matching options based on your Book's Accounts, Groups, and transaction data.

![The Search Assistant suggesting options as you type a search term](https://bkper.com/docs/_astro/search-assistant-2.oiLKBTqP.png)

### Picking absolute dates

Click the **Date Picker** in the Search Assistant to select fixed start and end dates.

![The date picker for selecting absolute dates in the Search Assistant](https://bkper.com/docs/_astro/search-assistant-5.D_kotumh.png)

You can also choose which date type to filter on:

![Date type selector showing Transaction Date, Post Date, and Update Date options](https://bkper.com/docs/_astro/search-assistant-6.Dy-O2ZCe.png)

- **Transaction Date** — the first date column on a transaction.
- **Post Date** — the last date column on a transaction.
- **Update Date** — the date a transaction was last modified.

### Running the search

Press **Search** and the assembled query is added to the search bar and executed. The matching transactions appear in the list below.

![Search results after running a query built with the Search Assistant](https://bkper.com/docs/_astro/search-assistant-7.K6vPnjvP.png)

The Search Assistant is a great way to learn query syntax — the queries you build here work identically in [Bkper Functions for Google Sheets](https://github.com/bkper/bkper-sheets#functions-reference) and in the [Bkper Add-on](https://bkper.com/docs/guides/google-sheets.md).

## Using search directly

You can also type queries directly in the search field on the Transactions page and press **Enter**.

![Bkper search field on the transactions page](https://bkper.com/docs/_astro/bkper-search.DNib6u7V.png)

### By account or group

| Operator | Description | Example |
| --- | --- | --- |
| `account:` | Filter by account | `account:Cash` |
| `from:` | Filter by origin (From) account | `from:Cash` |
| `to:` | Filter by destination (To) account | `to:Expenses` |
| `group:` | Filter by group | `group:Expenses` |

### By transaction status

| Operator | Example |
| --- | --- |
| `is:draft` | Transactions not yet posted |
| `is:posted` | Posted transactions |
| `is:trashed` | Trashed transactions |
| `is:checked` | Checked transactions |
| `is:unchecked` | Unchecked transactions |

### By user

| Operator | Description | Example |
| --- | --- | --- |
| `createdBy:` | Filter by the user who recorded the transaction | `createdBy:arun` |
| `updatedBy:` | Filter by the user who last updated the transaction | `updatedBy:arun` |

### By account type

Use these keywords without a colon to filter by account type:

`asset` | `liability` | `incoming` | `outgoing`

### By date

| Operator | Description | Example |
| --- | --- | --- |
| `on:` | Transactions on a specific date | `on:2024-01-01` |
| `after:` | Transactions after a date | `after:2023-12-31` |
| `before:` | Transactions before a date | `before:2025-01-01` |
| `after: before:` | Date range (between) | `after:2023-12-31 before:2025-01-01` |

### By creation or modification date

| Operator | Description | Example |
| --- | --- | --- |
| `using:createdAt` | Search by creation date | `after:02/07/2025 before:02/10/2025 using:createdAt` |
| `using:updatedAt` | Search by last modification date | `using:updatedAt after:$d-2` |

### Date variables

Date variables create dynamic, relative date references — especially useful in Google Sheets reports that should always reflect recent data.

| Variable | Description | Example |
| --- | --- | --- |
| `$d` | Relative days | `$d-14` (14 days ago), `$d+1` (tomorrow) |
| `$m` | Relative months | `$m-3` (3 months ago), `$m+1` (1 month ahead) |
| `$y` | Relative years | `$y-1` (last year), `$y+1` (next year) |

Combine date ranges with variables to create rolling reports. For example, `after:$d-14 before:$d+1` always returns the last 14 days of results.

![Using date variables to define a dynamic date range in the search](https://bkper.com/docs/_astro/search-assistant-3.CTBzr7eZ.png)

The Date Variable annotation follows the pattern: `($y|$m|$d)(-|+)(1-999)`.

![Date variable annotation syntax reference](https://bkper.com/docs/_astro/search-assistant-4.CrSoCO1R.png)

### By amount

| Operator | Description | Example |
| --- | --- | --- |
| `amount:` | Exact amount | `amount:2000` |
| `amount>` | Greater than | `amount>1000` |
| `amount<` | Less than | `amount<1000` |

### Logical operators

| Operator | Description | Example |
| --- | --- | --- |
| `AND` (default) | Match all conditions | `amount:2000 AND account:Expense` |
| `OR` | Match either condition | `account:'Revenue' OR account:'Other Income'` |
| `NOT` | Exclude from results | `NOT "Bank Account"` |

### Balance periodicity

Change how balance values are grouped in search results:

| Operator | Description |
| --- | --- |
| `by:d` | Balance values per day |
| `by:m` | Balance values per month |
| `by:y` | Balance values per year |

## Examples

**Combining AND, OR, and a date filter** — Find salary payments from a specific account before a date:

```
account:'Brex Cash' ('Salary Pat' OR 'Salary Michael') before:01/01/2026
```

![Bkper search results showing salary transactions from the Brex Cash account](https://bkper.com/docs/_astro/bkper-search-query-example1.DoNubfwY.png)

**Dynamic income search for the last 24 months** — Show Revenue and Cost of Goods Sold over a rolling window:

```
group:'Revenue' OR group:'COGS' after:$m-24
```

![Bkper search results showing Revenue and COGS groups with balance chart over 24 months](https://bkper.com/docs/_astro/bkper-search-query-example2.B0YUAdv4.png)

## Saved queries

Saved queries reduce the effort of periodic reporting. Prepare your search conditions — including date variables for dynamic ranges — and save the query for later use. You can re-run it with a single click in the web app, or use it with auto-update in the Bkper Add-on for Google Sheets.

> **Tip**
> Saved queries are available on [Bkper paid plans](https://bkper.com/pricing/).
### Saving a query

Open your Book and type the desired query in the search box. Then open the **context menu** (three-dot icon), select **Save Query**, give it a meaningful name, and confirm with **OK**.

![Typing a query in the Bkper search box](https://bkper.com/docs/_astro/saved-queries-1.B-ex0M8f.png)

![Selecting Save Query from the context menu](https://bkper.com/docs/_astro/saved-queries-2.DyxNn37n.png)

![Entering a descriptive name for the saved query](https://bkper.com/docs/_astro/saved-queries-3.DZKm4pf3.png)

#### From the Bkper web app

Your saved queries appear in the left sidebar of the Book. Click any saved query to instantly run it and view the updated results.

![Saved queries listed in the left sidebar of a Bkper Book](https://bkper.com/docs/_astro/saved-queries-4.Cx3m4-f4.png)

#### From the Bkper Add-on for Google Sheets

Open a Google Sheet and launch the [Bkper Add-on for Google Sheets](https://bkper.com/docs/guides/google-sheets.md). Select your Book, click **Fetch**, and choose your saved query from the list. The add-on pulls the matching data directly into your spreadsheet.

![Using a saved query from the Bkper Add-on for Google Sheets to fetch data](https://bkper.com/docs/_astro/saved-queries-5.CE7dM9p-.png)

## Where queries work

The query language is universal across Bkper:

- **Web app** — type queries in the search bar on the Transactions page
- **Search Assistant** — build queries visually with guided suggestions
- **[Bkper Functions](https://github.com/bkper/bkper-sheets#functions-reference)** — use queries as parameters in `BKPER_BALANCES` and `BKPER_TRANSACTIONS`
- **[Bkper Add-on](https://bkper.com/docs/guides/google-sheets.md)** — fetch transactions and balances filtered by query
- **[Google Apps Script](https://bkper.com/docs/build.md)** — pass queries programmatically to the Bkper API

A query that works in one place works in all of them. This means you can prototype a query in the Search Assistant, then paste it into a Google Sheet for automated reporting.