# Selectors

An AMQP receiver can send a JMS message selector on its source, as an `apache.org:selector-filter:string` or `amqp:sql-filter` filter. The gateway then delivers only the messages that match. A JMS client sends one when it creates a consumer with a selector. Both filters use the Jakarta Messaging selector syntax that this page lists.

## Examples

| Selector                                             | Matches                                        | Does not match                           |
| ---------------------------------------------------- | ---------------------------------------------- | ---------------------------------------- |
| `region = 'EU'`                                      | `region` is `EU`                               | `region` is `eu`, or missing             |
| `region IN ('EU', 'APAC')`                           | `region` is `EU` or `APAC`                     | `region` is `US`, or missing             |
| `region <> 'EU'`                                     | `region` is `US`                               | `region` is `EU`, or missing             |
| `region <> 'EU' OR region IS NULL`                   | `region` is `US`, or missing                   | `region` is `EU`                         |
| `amount > 1000`                                      | `amount` is `1200` or `'1200'`                 | `amount` is `80` or `'abc'`, or missing  |
| `amount BETWEEN 50 AND 100`                          | `amount` is `50` or `100`                      | `amount` is `49.9`                       |
| `sku LIKE 'A-%'`                                     | `sku` is `A-100` or `A-`                       | `sku` is `a-100` or `B-100`              |
| `sku LIKE 'A\_%' ESCAPE '\'`                         | `sku` is `A_1`                                 | `sku` is `AB1`                           |
| `tier IS NULL`                                       | `tier` is missing                              | `tier` is set, even to `''`              |
| `urgent`                                             | `urgent` is `true` or `TRUE`                   | `urgent` is `false` or `yes`, or missing |
| `region = 'EU' AND (amount > 1000 OR tier = 'gold')` | `EU` with `amount` 1200, or with `tier` `gold` | `EU` with `amount` 5 and no `tier`       |
| `JMSPriority >= 5`                                   | Priority 5 to 9                                | No priority, which reads as 4            |
| `JMSDeliveryMode = 'PERSISTENT'`                     | `durable` is true                              | `durable` is false or unset              |

## Identifiers

An identifier starts with a letter, `_` or `$`, and continues with letters, digits, `_` or `$`. Identifiers are case sensitive: `Amount` does not read `amount`. A keyword, such as `AND` or `TRUE`, in any case, is not an identifier. Selectors have no quoted identifiers.

An identifier names an application property, unless it is one of the JMS names below. MQTT v5 User Properties and the `Mqg-Prop-<key>` headers of NATS clients are application properties too (see [Mapping to NATS](/mq-gateway/0.3/reference/mapping-to-nats.md#headers)). On a routed address, the gateway reads a property that the route's template names from the subject, not from the header.

| Name               | Value                                                          | When unset         |
| ------------------ | -------------------------------------------------------------- | ------------------ |
| `JMSMessageID`     | `message-id`, as a JMS client reads it. See Rules              | NULL               |
| `JMSCorrelationID` | `correlation-id`, as a JMS client reads it. See Rules          | NULL               |
| `JMSType`          | `subject`                                                      | NULL               |
| `JMSPriority`      | `priority`, 0 to 9. A higher priority reads as 9               | 4                  |
| `JMSTimestamp`     | `creation-time`, in milliseconds since the Unix epoch          | 0                  |
| `JMSDeliveryMode`  | `'PERSISTENT'` when `durable` is true, else `'NON_PERSISTENT'` | `'NON_PERSISTENT'` |
| `JMSExpiration`    | When the message expires, in milliseconds since the Unix epoch | 0                  |
| `JMSXUserID`       | `user-id`, else the application property `JMSXUserID`          | NULL               |
| `JMSXGroupID`      | `group-id`                                                     | NULL               |
| `JMSXGroupSeq`     | `group-sequence`, as a signed 32-bit integer                   | NULL               |

Any other name, JMS-prefixed or not, is an application property. The gateway refuses a selector on `JMSXDeliveryCount`.

## Literals

| Literal | Examples                    | Notes                                                                      |
| ------- | --------------------------- | -------------------------------------------------------------------------- |
| String  | `'EU'`, `'it''s'`           | Single quotes. Two quotes write one                                        |
| Number  | `57`, `-9.5`, `1e3`, `100L` | Decimal only. A Java type suffix `L`, `F` or `D`, in any case, is optional |
| Boolean | `TRUE`, `FALSE`             |                                                                            |
| Null    | `NULL`                      | Unknown. `a = NULL` never matches. Use `IS NULL`                           |

Keywords such as `AND`, `LIKE` and `TRUE` are not case sensitive.

## Operators

| Operator                      | Example                              | Notes                                                                                   |
| ----------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------- |
| `+` `-` (sign)                | `-amount < -1000`                    |                                                                                         |
| `*` `/`                       | `amount * 2 >= 2400`                 |                                                                                         |
| `+` `-`                       | `price + tax > 100`                  |                                                                                         |
| `=` `<>`                      | `region = 'EU'`                      | Any type                                                                                |
| `<` `<=` `>` `>=`             | `amount > 1000`                      | Not on a string or boolean literal                                                      |
| `[NOT] BETWEEN ... AND ...`   | `amount BETWEEN 50 AND 100`          | Not on a string or boolean literal. The bounds are inclusive                            |
| `[NOT] IN (...)`              | `region IN ('EU', 'APAC')`           | An identifier, and a list of strings                                                    |
| `[NOT] LIKE ... [ESCAPE ...]` | `sku LIKE 'A\_%' ESCAPE '\'`         | A string pattern: `%` is any run of characters, `_` is one. The escape is one character |
| `IS [NOT] NULL`               | `tier IS NULL`                       | True when the message has no such value                                                 |
| `NOT` `AND` `OR`              | `NOT region = 'EU' OR amount > 1000` |                                                                                         |

Precedence follows the table. The sign binds first, then `*` and `/`, then `+` and `-`. The comparisons, from `=` to `IS NULL`, share one level and do not chain. Then come `NOT`, `AND` and `OR`, in that order. Parentheses group terms.

The gateway refuses a string or boolean literal next to `<`, `<=`, `>`, `>=` or `BETWEEN`. Two properties can still be ordered (see Rules).

## Rules

* **A property takes the type of what it is compared with.** Against a number, it is a number when its text reads as one, so the string property `'1200'` matches `amount > 1000`. Against `TRUE` or `FALSE`, it is a boolean in any case. Against a string, it is text, compared exactly.
* **Unlike types do not match.** A property that does not read as a number, compared with one, makes the comparison false. Its negation, such as `NOT word < 100`, is then true. `word NOT BETWEEN 1 AND 2` is `word < 1 OR word > 2`, so it is false too.
* **A missing property is unknown.** Neither `tier = 'gold'` nor `tier <> 'gold'` matches a message without `tier`. Use `IS NULL` to match it. `OR` with a true side and `AND` with a false side still decide.
* **Two properties compare as numbers when both read as numbers.** Otherwise they compare as text, by their bytes.
* **IDs read as a JMS client reads them.** A `message-id` or `correlation-id` that is not a string reads with a type prefix, such as `ID:AMQP_ULONG:42`. A string `message-id` without `ID:` reads as `ID:AMQP_NO_PREFIX:<id>`.
* **Numbers are 64-bit floating point.** Integers above 2^53 compare inexactly.
* **A property alone is a condition.** `flag` matches when the property's text is `true`, in any case.
* **Spelling does not change a selector.** Selectors that differ only in spaces, keyword case, redundant parentheses or number format are the same. Receivers in queue mode on a stored address then share a queue. `a AND (b AND c)` and `a AND b AND c` are different selectors. See [AMQP support](/mq-gateway/0.3/reference/amqp-support.md#things-to-know).
* **The gateway checks the selector at attach.** It refuses the receiver's link when the selector does not parse.
