Match expressions

Match expressions always apply to a single attribute and so the attribute name isn't a part of the expression text itself.

Sample expressions

Here are some sample match expressions :-

Attribute Match Expression Comments
id EQ 4 matches if the id is equal to 4
id 4 shorthand for EQ 4
id EQ 4 OR EQ 6
id GE 100 AND LT 120 id >=100 and id <120
id NE 10 AND NE 20
name EQ "Andy" name is Andy (always case sensitive)
name "Andy" shorthand for EQ "Andy"
name Andy shorthand for "Andy" (it's ok, because there is no chance Andy can be confused with other reserved words in the match expression language)
name IN ("Andy","Alex") A bit like (EQ "Andy" OR EQ "Alex")
name IN ("Andy" "Alex") Like the above, to facilitate cut-n-paste of lists of values
name LIKE "%smith" name ending with "smith"
id LIKE "%000___" textual representation of the id is anything, followed by 000, followed by any 3 characters
queueName NOT LIKE "%.error" queue name doesn't end in .error
queueName PATTERN "[abc]_queue" this is a Java regular expression match. Note that . doesn't match newlines in multiline data unless you include (?s) to turn on "DOTALL" mode
age (GE 13 AND LE 19) AND NOT 18 an ordinary teenage birthday (18 is extraordinary)
id NULL value is NULL
id NOT NULL value is not NULL
id EQ "" value is the empty string
id no match expression supplied implies every value matches

Attribute	Match Expression	Comments
id	EQ 4	matches if the id is equal to 4
id	4	shorthand for EQ 4
id	EQ 4 OR EQ 6
id	GE 100 AND LT 120	id >=100 and id <120
id	NE 10 AND NE 20
name	EQ "Andy"	name is Andy (always case sensitive)
name	"Andy"	shorthand for EQ "Andy"
name	Andy	shorthand for "Andy" (it's ok, because there is no chance Andy can be confused with other reserved words in the match expression language)
name	IN ("Andy","Alex")	A bit like (EQ "Andy" OR EQ "Alex")
name	IN ("Andy" "Alex")	Like the above, to facilitate cut-n-paste of lists of values
name	LIKE "%smith"	name ending with "smith"
id	LIKE "%000___"	textual representation of the id is anything, followed by 000, followed by any 3 characters
queueName	NOT LIKE "%.error"	queue name doesn't end in .error
queueName	PATTERN "[abc]_queue"	this is a Java regular expression match. Note that `.` doesn't match newlines in multiline data unless you include `(?s)` to turn on "DOTALL" mode
age	(GE 13 AND LE 19) AND NOT 18	an ordinary teenage birthday (18 is extraordinary)
id	NULL	value is NULL
id	NOT NULL	value is not NULL
id	EQ ""	value is the empty string
id		no match expression supplied implies every value matches

You can also type symbolic equivalents to EQ, NE, etc..., as per BNF below.

Search and filter

Just because Tabulator offers a very comprehensive expression language, doesn't mean the data sources supplying the data do. Tabulator tries to translate what you have requested into what the source below it can support. Sometimes this will be imperfect, and Tabulator will ask the source to pull too much data, and then will have to filter the results. The sources supplied with Tabulator have limitations, and the types added to it may also have limitations of their own.

For example, Tabulator supports PATTERN "regexp", but SQL databases do not. So if you use this when querying data coming from a database, this won't be included as a WHERE clause, and instead Tabulator will filter each row returned against this regular expression.

In Tabulator, the LIKE "likestring" understands % and _ characters, and providing this is the only wildcarding in the "likestring", can convert to an SQL WHERE clause. If the likestring contains [, then Tabulator must filter.

Most types implement some kind of limit on the number of results they are prepared to fetch from the underlying source (eg: only fetch at most 500 rows from the database). Filtering can weed out many of these leaving few results, when perhaps if it had been possible for the source to fully implement the query, more results would have been returned. Tabulator warns you when the results it has returned might not be all of them, and this might be a clue that you should write a more targetted query, or one able to be better translated into the underlying query language (eg: SQL or XQuery).

Formal Description

For those who grok BNF :-

<expr4> ::= 'NULL'
          | '(' <expr1> ')'
          | ( 'EQ' | '='         ) <value>
          | ( 'NE' | '!=' | '<>' ) <value>
          | ( 'GT' | '>'         ) <value>
          | ( 'GE' | '>='        ) <value>
          | ( 'LT' | '<'         ) <value>
          | ( 'LE' | '<='        ) <value>
          |   'IN' '('             <value> { [ ',' ] <value> } ')'
          |   'LIKE'               <value>
          |   'PATTERN'            <value>
          | <value>
<expr3> ::= <expr4>
          | ( 'NOT' | '!' ) <expr4>
<expr2> ::= <expr3> { 'AND' <expr3> }
<expr1> ::= <expr2> { 'OR' <expr2> }
<expr>  ::= <expr1> EOF

When processing your match expression, the lexical analyser collects unquoted letters, digits, dots, plus symbols, minus symbols and colons into a token. It then considers whether the token it has just read is really a reserved word (such as EQ), or a value.

Quoted strings are easier. They're obviously not reserved words. The lexical analyser just reads characters upto the closing ". Remember to escape \s and "s within them with \s.

Reserved words are case-sensitive. eq isn't a reserved word. EQ is a reserved word, so if you need to write a match expression which matches the textual value EQ, then you'd need to quote it as EQ "EQ".

Converting a token into its value involves parsing it according to the rules of its primitive type. So if you were writing a match expression for an Integer, and you wrote EQ "abc", its going to fail when it tries to parse abc as a number.