# Hub API Query Syntax

## Overview

This document provides a BNF description for Hub query grammar.

## Grammar

```XML
<Query> ::= <OrExpression> EOF
  <OrExpression> ::= <AndExpression> "or" <AndExpression>
    <AndExpression> ::= <SignExpression> "and" <SignExpression>
      <SignExpression> ::= ("not")? <Item>
        <Item> ::= <Field>| <Tuple>| <Paren>| <Phrase>| <Text>
          <Field> ::= <FieldName> ":" <FieldValue>
            <Tuple> ::= <TupleName> "(" <Field> <Field>* ")"
              <Paren> ::= "(" <OrExpression>| EOF ")"
```

Grammar is case-insensitive.

* `<Text>` — arbitrary text.

* `<Phrase>` — exactly text to match.

* `<FieldName>` — field name (id, name, etc.). It covers all available JSON field names + some additional like "is", "in", "has", etc.

* `<FieldValue>` — attribute value (admin, global, {my global permission}, etc.) for not single worded values value should be surrounded with "{" "}"

* `<Tuple>` — conditional match by fields (access(project: "myProject", with: "myRole"))

## Samples

|  Query  |  Description  |
| --- | --- |
|  name: admin  |  Finds all users with the `visibleName` "admin".  |
|  is: banned  |  Finds all banned users.  |
|  access(project: MyProject , with: read-issue-permission )  |  Finds all users with access to the project "MyProject" and permission "read-issue-permission".   |