# Query language

> The one-line syntax of the filter box, saved views, and rules, with every word and value.

Source: https://hush-gh.com/docs/query-language

One short syntax filters the inbox, defines [saved views](https://hush-gh.com/docs/views), and writes the conditions of [rules](https://hush-gh.com/docs/rules):

```query
repo:acme/* needs:review -author:bots label:"good first issue" login bug
```

## Syntax

- `word:value` is a condition. All conditions must match.
- `word:a,b` (or the same word twice) matches **any** of the values: `repo:acme/web,acme/api`.
- `*` matches anything, and `?` one character, in `repo:`, `author:`, and `from:`: `repo:acme/*`, `author:dependabot*`.
- Quote a value that has spaces or commas: `label:"good first issue"`.
- `author:bots` and `from:bots` mean any bot. `-author:bots` and `-from:bots` mean a person.
- `is:draft` and `-is:draft`; `is:open`, `is:closed`, `is:merged`.
- Other words must all be in the title, the repository, or the author. They are not case-sensitive.
- Only `-author:bots`, `-from:bots`, and `-is:draft` can have a `-`.

When a part has an error (an unknown word, a value that does not exist), Hush says so and leaves that part out. While you type, suggestions show the words and their values; ↑ and ↓ move, Enter or Tab picks one, and Esc closes the list.

## Words

| Word | Filters on | Example | JSON condition |
| --- | --- | --- | --- |
| `repo:` | Repository (* matches anything) | `repo:acme/*` | `repo` |
| `author:` | Who opened it; author:bots for any bot | `author:dependabot*` | `author`; `author:bots` sets `bot` |
| `from:` | Who did the latest activity (a comment or a review); from:bots for any bot | `from:github-actions` | `by`; `from:bots` sets `byBot` |
| `label:` | Has this label | `label:"good first issue"` | `label` |
| `type:` | What it is | `type:pr` | `type` |
| `event:` | Why GitHub notified you | `event:you-opened` | `reason` |
| `needs:` | What Hush thinks you must do | `needs:review` | `kind` |
| `in:` | Hush's list for it, before your rules | `in:fyi` | `category` |
| `is:` | Draft, open, closed, or merged | `is:draft` | `draft`, `state` |
| other words | Words that must all be in the title, repository, or author | `login bug` | `text` |

## Values

### type:

What it is.

| Value | Means | In JSON |
| --- | --- | --- |
| `pr` | Pull request | `"PullRequest"` |
| `issue` | Issue | `"Issue"` |
| `ci` | Workflow run | `"CheckSuite"` |
| `release` | Release | `"Release"` |
| `discussion` | Discussion | `"Discussion"` |
| `commit` | Commit | `"Commit"` |
| `vulnerability` | Vulnerability alert | `"RepositoryVulnerabilityAlert"` |
| `dependabot` | Dependabot alerts | `"RepositoryDependabotAlertsThread"` |

### event:

Why GitHub notified you.

| Value | Means | In JSON |
| --- | --- | --- |
| `review-requested` | Your review was requested | `"review_requested"` |
| `mentioned` | You were mentioned | `"mention"` |
| `team-mentioned` | Your team was mentioned | `"team_mention"` |
| `you-opened` | You opened it | `"author"` |
| `you-commented` | You commented on it | `"comment"` |
| `assigned` | You were assigned | `"assign"` |
| `watching` | You watch the repository | `"subscribed"` |
| `subscribed` | You subscribed to it | `"manual"` |
| `state-changed` | You changed its state | `"state_change"` |
| `your-ci` | Your workflow run | `"ci_activity"` |
| `security` | Security alert | `"security_alert"` |
| `invited` | Repository invitation | `"invitation"` |
| `deploy-approval` | A deployment waits for your approval | `"approval_requested"` |
| `feature-request` | Feature request | `"member_feature_requested"` |
| `advisory-credit` | Security advisory credit | `"security_advisory_credit"` |

### needs:

What Hush thinks you must do.

| Value | Means | In JSON |
| --- | --- | --- |
| `review` | Review it | `"review"` |
| `fix-ci` | Fix failing CI | `"fix_ci"` |
| `changes` | Address review comments | `"address_review"` |
| `conflict` | Resolve a merge conflict | `"resolve_conflict"` |
| `merge` | Merge it | `"merge"` |
| `reply` | Reply | `"reply"` |
| `triage` | Triage it | `"triage"` |
| `security` | Handle a security alert | `"security"` |
| `nothing` | Nothing: FYI | `"none"` |

### in:

Hush's list for it, before your rules.

| Value | Means | In JSON |
| --- | --- | --- |
| `needs-you` | Needs you | `"action"` |
| `fyi` | FYI | `"fyi"` |
| `muted` | Muted | `"muted"` |

### is:

| Value | Means | In JSON |
| --- | --- | --- |
| `is:draft` | A draft pull request | `"draft": true` |
| `is:open` | Open | `"state": ["open"]` |
| `is:closed` | Closed | `"state": ["closed"]` |
| `is:merged` | Merged | `"state": ["merged"]` |

`-is:draft` is `"draft": false`.

## `author:` and `from:`

- `author:` is who **opened** the PR or issue.
- `from:` is who did the **newest activity** on it: the newest comment or review. New commits count as activity too, but GitHub does not say who pushed them, so `from:` does not match them.

For example, `from:github-actions` finds the threads where the newest thing is a comment by GitHub Actions.

## Examples

| Query                              | Finds                                                                |
| ---------------------------------- | -------------------------------------------------------------------- |
| `repo:acme/*`                      | Everything in the acme org.                                          |
| `needs:review -author:bots`        | Review requests from people.                                         |
| `type:pr is:open author:alice`     | Open PRs that Alice opened.                                          |
| `event:mentioned,team-mentioned`   | Threads where you or your team were mentioned.                       |
| `needs:fix-ci repo:acme/web`       | Failing CI on your PRs in one repository.                            |
| `from:bots in:fyi`                 | FYI threads where a bot did the newest thing.                        |
| `label:"good first issue" is:open` | Open threads with this label.                                        |
| `type:release,discussion`          | Releases and discussions.                                            |
| `login timeout`                    | Threads with both words in the title, the repository, or the author. |

## In JSON

A query is stored as a JSON object of conditions: the `when` of a rule or a view. Each word is one key; the tables above show the key and the stored values. `repo:acme/* needs:review -author:bots is:draft login` is:

```json
{ "repo": "acme/*", "kind": ["review"], "bot": false, "draft": true, "text": "login" }
```

`repo`, `author`, and `from` (`by`) are text when they have one value, and lists when they have more. The other words are always lists.