> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invoca.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Keyword Searches

> Keywords narrow and further define a search, beyond column names, values, and filters.

In addition to column names, values, and filters, the search bar also accepts Keywords. Access a list of Keywords and other reference material in the reference section or the in-app help — open it by selecting **Help** from the top navigation bar, where you'll find videos and documentation for your current version of Invoca, including a list of Keywords you can expand by section.

## Example: simplify a search with the top keyword

The `top` keyword can greatly simplify a search when you remember to use it. Its syntax looks like `top n for each x`.

Some common examples: top two performing sales rep; top revenue average revenue by state; top two students ranked by source for each class.

## Types of keywords

Keywords serve a variety of predefined purposes, divided into groups:

* **Basic Keywords**: use keywords such as `top` and `bottom` to see results for the best or worst performing sales rep, for example.
* **Date Keywords**: narrow your search by days, weeks, months, quarters, or years, plus keywords like `after`, `before`, and `year-over-year`.
* **Time Keywords**: most useful for figuring out how many visitors you've received within the last `n` minutes or hours.
* **Text Keywords**: find similar words or phrases containing a certain word, such as `product name contains green`.
* **Number Keywords**: define your search by sum, average, count, max, min, and other accumulations.
* **Comparative Keywords**: work the same way as filters on table columns or chart axes.
* **Location Keywords**: `near` and `farther than` let you search with spatial filters on geo-type columns with latitude/longitude data, based on distance in miles, kilometers, or meters.

<Note>
  **Note**

  When using the **top** or **bottom** keywords without specifying a number (*n*), the number defaults to 10.
</Note>

## General

| Keyword               | Description                                                                                                                                                 | Example                                               |
| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------- |
| `best n`              | Generates the best n items from a sorted result                                                                                                             | `best 25 customer by revenue for each sales rep`      |
| `bottom n`            | Generates the bottom n items from a sorted result                                                                                                           | `bottom 25 customer by revenue for each sales rep`    |
| `by measure`          | Treats the measure as an attribute and groups the result set by it                                                                                          | `cost by revenue`                                     |
| `sort by`             | Sorts the result set by an attribute or measure                                                                                                             | `revenue by state sort by average revenue descending` |
| `top n`               | Generates the top n items from a sorted result. If your search has more than one measure, sorts by the first measure unless you specify `top n by <column>` | `top 10 sales rep revenue`                            |
| `top n ... ranked by` | Ranks the top n items by a specified measure; only works with `top`                                                                                         | `top 10 sales rep revenue sales ranked by sales`      |
| `worst`               | Generates the worst n items from a sorted result                                                                                                            | `worst revenue average`                               |

## Date

<Note>
  **Note**

  The `last` keyword returns the last n full periods and doesn't include the current period. For example, `last 6 hours` returns the last 6 full hours, not including the current hour. To include the current period, add `this <period>` — for example, `last 6 hours this hour`.
</Note>

Common date keywords include `after`, `before`, `between ... and ...`, `calendar`, `daily`, `day`, `day of month/quarter/week/year`, `fiscal`, `growth of ... by ...` (with daily/monthly/quarterly/weekly/yearly variants), `hourly`, `last n days/months/quarters/weeks/years` (with `for each <period>` variants), `month`, `month to date`, `monthly`, `n <period>s ago`, `next <period>`, `on or after`/`on or before`, `quarter to date`, `this <period>`, `today`, `week`, `year`, and `yesterday` — along with month-name keywords (`January`–`December`) and day-of-week keywords (`Monday`–`Sunday`).

Examples:

```text theme={null}
order date after 10/31/2014
sales April
growth of revenue by order date daily year-over-year
sales 2 months ago by region
```

## Time *(Early Access)*

Timezone-aware keywords ensure relative date filters — like "today," "yesterday," and "last 7 days" — always reflect the correct local time for each user, so searches, dashboards, and tiles show time-based data matching local business hours.

Keywords include `detailed`, `hourly`, `last hour`/`last minute`, `n hours`/`n hours ago`, `n minutes`/`n minutes ago`, `next hour`/`next minute`, and `this hour`/`this minute`.

```text theme={null}
ship time detailed
count homepage views last minute
```

## Text

| Keyword                                                                 | Description                                                                                 | Example                              |
| :---------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ | :----------------------------------- |
| `begins with`                                                           | Items starting with the given text. Can't combine with `and`                                | `product name begins with 'pro'`     |
| `contains`                                                              | Items containing the given text                                                             | `country name contains 'a' or 'b'`   |
| `ends with`                                                             | Items ending with the given text. Can't combine with `and`                                  | `product name ends with 'deluxe'`    |
| `similar to`                                                            | Items similar to a pattern; use `%` for zero/one/multiple characters, `_` for one character | `product name similar to '%jacket%'` |
| `not begins with` / `not contains` / `not ends with` / `not similar to` | Negated versions of the above                                                               | `product name not begins with 'pro'` |

<Note>
  **Note**

  If a query includes two or more `contains` phrases modifying the same column, Invoca combines them with `or` logic (prior to version 9.2.0.cl, Invoca used `and` logic; existing content was automatically updated on upgrade).
</Note>

## Number

`average`, `count`, `max`, `min`, `standard deviation`, `sum`, `total count`, `unique count`, `variance`. Example: `average revenue by store`

## Comparative

| Keyword                 | Description                                                                 | Example                                                                  |
| :---------------------- | :-------------------------------------------------------------------------- | :----------------------------------------------------------------------- |
| `all`                   | Used only as part of a versus phrase                                        | `revenue asia vs all`                                                    |
| `between... and...`     | Range filter                                                                | `revenue between 0 and 1000`                                             |
| `=` / `!=`              | Equal / not equal. Supports `{null}` and `{empty}` constants                | `unique count visitor by store purchased products = 3 for last 5 days`   |
| `>` / `>=` / `<` / `<=` | Greater than, greater or equal, less than, less or equal                    | `sum sale amount by visitor by product for last year sale amount > 2000` |
| `of`                    | Level of detail keyword; returns a measure at the level of detail specified | `revenue of region`                                                      |
| `percentage of`         | Mix, contribution, or share ratios                                          | `state revenue percentage of region`                                     |
| `vs`, `versus`          | Compares values across a split                                              | `revenue east vs west`                                                   |

<Note>
  **Note**

  Invoca supports multiple `contains`, `begins_with`, and `ends_with` phrases in `vs` queries (combined with OR, or AND for multiple `contains` phrases depending on environment settings). Invoca doesn't support `group_*` formula measures with `vs`, or `vs` inside an `in`/`not in` subquery.
</Note>

## Location

`farther than n miles|km|meters from ...`, `near`, `near ... within n miles|km|meters`.

```text theme={null}
average hours worked branch farther than 80 km from scarborough
revenue store name county near san francisco
```

## Period

`day`, `day of month`, `day of quarter`, `day of week`, `day of year`, `hour`, `month of quarter`, `month of year`, `quarter`, `quarter of year`, `week of month`, `week of quarter`, `week of year`.

<Note>
  **Note**

  Invoca uses ISO week format for the `week of [month | quarter | year]` keywords, so the last few days of a quarter may sometimes show as the first few days of the next quarter.
</Note>

## In / Not in

`in`: query-in-query search (intersection of two sets). Must match the last attribute before the keyword with the first attribute inside the subsearch. Doesn't support `vs`.

```text theme={null}
attribute in (attribute subsearch)
store name in (top 10 store name by sales footwear)
```

`not in`: relative complement of two sets, with the same matching rules.

```text theme={null}
attribute not in (attribute subsearch)
product name 2014 product name not in (product name 2013) sales
```

## Where to go next

* [Search bar features](/s/article/search-bar-features)
* [Search suggestions](/s/article/search-suggestions)