# Search & Queries

**Bkper Search** filters transactions and balance values with one query language. The same syntax works in the Bkper web app, the Search Assistant, the Bkper Add-on for Google Sheets, Bkper Functions, Apps Script, and API-based workflows.

Use search when you need to:

- find transactions by account, group, amount, date, status, user, hashtag, or text
- filter the balance sheet or transaction list to a specific scope
- build reusable reporting queries for Google Sheets
- create rolling reports with relative date variables

## Search Assistant

The Search Assistant helps you build queries visually from the Book search bar. It is useful when you do not remember the exact syntax or want suggestions based on the current Book.

Use it to select:

- transaction status, such as draft, checked, unchecked, or trashed
- Accounts and Groups from your Book
- absolute dates from a date picker
- the date type to search against

Available date types are:

- **Transaction Date** — the business date assigned to the transaction.
- **Post Date** — the date the transaction was posted.
- **Update Date** — the date the transaction was last modified.

When you run the search, Bkper writes the assembled query into the search bar and executes it. This makes the Search Assistant a good way to learn query syntax before reusing the same query in Google Sheets or automation code.

## Using search directly

You can type queries directly in the Book search field and press **Enter**.

Use quotes around Account or Group names that contain spaces:

```txt
account:'Bank Account'
group:'Cost of Goods Sold'
```

A query can combine several conditions. By default, Bkper treats multiple conditions as **AND** conditions, so all of them must match.

### Account and Group filters

| Operator   | Description                                       | Example          |
| ---------- | ------------------------------------------------- | ---------------- |
| `account:` | Transactions involving an Account                 | `account:Cash`   |
| `from:`    | Transactions where resources leave an Account     | `from:Cash`      |
| `to:`      | Transactions where resources arrive at an Account | `to:Expenses`    |
| `group:`   | Transactions or balances scoped to a Group        | `group:Expenses` |

### Transaction status filters

| Operator       | Meaning                             |
| -------------- | ----------------------------------- |
| `is:draft`     | Incomplete or unposted transactions |
| `is:posted`    | Posted transactions                 |
| `is:checked`   | Reviewed transactions               |
| `is:unchecked` | Posted but not checked transactions |
| `is:trashed`   | Trashed transactions                |

### User filters

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

### Account type filters

Use account type keywords without a colon:

| Keyword     | Meaning            |
| ----------- | ------------------ |
| `asset`     | Asset Accounts     |
| `liability` | Liability Accounts |
| `incoming`  | Incoming Accounts  |
| `outgoing`  | Outgoing Accounts  |

### Date filters

| Operator         | Description                    | Example                                  |
| ---------------- | ------------------------------ | ---------------------------------------- |
| `on:`            | A specific day, month, or year | `on:2025`, `on:2025-01`, `on:2025-01-31` |
| `after:`         | On or after a date             | `after:2025-01-01`                       |
| `before:`        | Before a date                  | `before:2026-01-01`                      |
| `after: before:` | A date range                   | `after:2025-01-01 before:2026-01-01`     |

> **Note**
> `after:` is inclusive and `before:` is exclusive. For the full year 2025, use `after:2025-01-01 before:2026-01-01`.
### Creation and update date filters

Use `using:` when the date condition should apply to creation or update timestamps instead of the transaction date.

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

### Date variables

Date variables create dynamic, relative dates. They are useful for saved queries and Google Sheets reports that should update automatically.

| Variable | Meaning         | Example                                               |
| -------- | --------------- | ----------------------------------------------------- |
| `$d`     | Relative days   | `$d-14` means 14 days ago; `$d+1` means tomorrow      |
| `$m`     | Relative months | `$m-3` means 3 months ago; `$m+1` means 1 month ahead |
| `$y`     | Relative years  | `$y-1` means last year; `$y+1` means next year        |

Examples:

```txt
after:$d-14 before:$d+1
```

Returns a rolling range covering the last 14 days through tomorrow.

```txt
group:'Revenue' after:$m-24
```

Returns Revenue activity across a rolling 24-month window.

### Amount filters

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

### Logical operators

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

### Balance periodicity

Use `by:` to change how balance values are grouped in charts and reports.

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

### Find salary payments from a specific Account

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

This finds transactions involving the Brex Cash Account where the transaction text matches either salary phrase before 2026.

### Build a rolling income report

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

This shows Revenue and Cost of Goods Sold over the last 24 months, grouped monthly.

### Filter a full reporting year

```txt
after:2025-01-01 before:2026-01-01
```

This covers the full 2025 calendar year because the start date is included and the end date is excluded.

## Saved queries

Saved queries reduce the effort of recurring reporting. Prepare the search conditions once, then save the query with a meaningful name.

Saved queries are useful when you need to:

- re-run the same report in the web app
- fetch the same filtered data into Google Sheets
- use date variables for rolling periods
- share a consistent reporting definition with a team

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

To save a query:

1. Open the Book.
2. Type or build the query in the search field.
3. Open the search context menu.
4. Select **Save Query**.
5. Give the query a clear name.
6. Confirm.

A good saved query name describes the report and period, such as `Monthly Revenue last 24 months` or `Unchecked bank imports`.

### Using a saved query

In the web app, saved queries appear with the Book navigation and can be run again with one click.

In Google Sheets, open the Bkper Add-on, choose the Book, and select the saved query from the Fetch workflow. The add-on pulls the matching transactions or balances into the spreadsheet.

## Where queries work

The query language is universal across Bkper:

- **Web app** — search and filter transactions, balances, and charts.
- **Search Assistant** — build valid queries visually.
- **Bkper Functions** — pass queries to `BKPER_BALANCES` and `BKPER_TRANSACTIONS`.
- **Bkper Add-on for Google Sheets** — fetch filtered balances and transactions.
- **Google Apps Script and API workflows** — pass queries programmatically.

A query that works in one place works in all of them. You can prototype a query in the web app, save it, and reuse it in Google Sheets or automation code.

## Related guides

- [Google Sheets Add-on](http://preview.bkper.com/docs/guides/google-sheets.md)
- [Chart Reports](http://preview.bkper.com/docs/guides/using-bkper/chart-reports.md)
- [Bkper Functions](https://github.com/bkper/bkper-sheets#functions-reference)