Skip to main content
Version: 0.4

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​

SelectorMatchesDoes not match
region = 'EU'region is EUregion is eu, or missing
region IN ('EU', 'APAC')region is EU or APACregion is US, or missing
region <> 'EU'region is USregion is EU, or missing
region <> 'EU' OR region IS NULLregion is US, or missingregion is EU
amount > 1000amount is 1200 or '1200'amount is 80 or 'abc', or missing
amount BETWEEN 50 AND 100amount is 50 or 100amount 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_1sku is AB1
tier IS NULLtier is missingtier is set, even to ''
urgenturgent is true or TRUEurgent is false or yes, or missing
region = 'EU' AND (amount > 1000 OR tier = 'gold')EU with amount 1200, or with tier goldEU with amount 5 and no tier
JMSPriority >= 5Priority 5 to 9No priority, which reads as 4
JMSDeliveryMode = 'PERSISTENT'durable is truedurable 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). On a routed address, the gateway reads a property that the route's template names from the subject, not from the header.

NameValueWhen unset
JMSMessageIDmessage-id, as a JMS client reads it. See RulesNULL
JMSCorrelationIDcorrelation-id, as a JMS client reads it. See RulesNULL
JMSTypesubjectNULL
JMSPrioritypriority, 0 to 9. A higher priority reads as 94
JMSTimestampcreation-time, in milliseconds since the Unix epoch0
JMSDeliveryMode'PERSISTENT' when durable is true, else 'NON_PERSISTENT''NON_PERSISTENT'
JMSExpirationWhen the message expires, in milliseconds since the Unix epoch0
JMSXUserIDuser-id, else the application property JMSXUserIDNULL
JMSXGroupIDgroup-idNULL
JMSXGroupSeqgroup-sequence, as a signed 32-bit integerNULL

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

Literals​

LiteralExamplesNotes
String'EU', 'it''s'Single quotes. Two quotes write one
Number57, -9.5, 1e3, 100LDecimal only. A Java type suffix L, F or D, in any case, is optional
BooleanTRUE, FALSE
NullNULLUnknown. a = NULL never matches. Use IS NULL

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

Operators​

OperatorExampleNotes
+ - (sign)-amount < -1000
* /amount * 2 >= 2400
+ -price + tax > 100
= <>region = 'EU'Any type
< <= > >=amount > 1000Not on a string or boolean literal
[NOT] BETWEEN ... AND ...amount BETWEEN 50 AND 100Not 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] NULLtier IS NULLTrue when the message has no such value
NOT AND ORNOT 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.
  • The gateway checks the selector at attach. It refuses the receiver's link when the selector does not parse.