3.5.9. The default SQL-like filter¶

Filter expressions used by ContentFilteredTopic API may use a subset of SQL syntax, extended with the possibility to use program variables in the SQL expression. This section shows this default SQL-like syntax and how to use it.

Grammar
Like condition
Match condition
Type comparisons
Example

3.5.9.1. Grammar¶

The allowed SQL expressions are defined with the BNF-grammar below.

The following conventions are made:

“Terminals” are quoted.
TOKENS are typeset in code block with black font color.

Expression          ::=  FilterExpression
FilterExpression    ::=  Condition
Condition           ::=  Predicate |
                         Condition "AND" Condition |
                         Condition "OR" Condition |
                         "NOT" Condition |
                         "(" Condition ")"
Predicate           ::=  ComparisonPredicate |
                         BetweenPredicate
ComparisonPredicate ::=  FIELDNAME RelOp Parameter |
                         Parameter RelOp FIELDNAME |
                         FIELDNAME RelOp FIELDNAME
BetweenPredicate    ::=  FIELDNAME "BETWEEN" Range |
                         FIELDNAME "NOT BETWEEN" Range
RelOp               ::=  "=" | ">" | ">=" | "<" | "<=" |
                         "<>" | "!=" | like | match
Range               ::=  Parameter "AND" Parameter
Parameter           ::=  BOOLEANVALUE |
                         INTEGERVALUE |
                         CHARVALUE |
                         FLOATVALUE |
                         STRINGVALUE |
                         ENUMERATEDVALUE |
                         PARAMETER

“Terminals” and TOKENS are case sensitive but both uppercase and lowercase are supported.

The syntax and meaning of the tokens used in the SQL grammar is described as follows:

FIELDNAME: is a reference to a field in the data-structure. The dot . is used to navigate through nested structures. The number of dots that may be used in a FIELDNAME is unlimited. The FIELDNAME can refer to fields at any depth in the data structure. The names of the field are those specified in the IDL definition of the corresponding structure.
```
FIELDNAME     ::=  FieldNamePart ( "." FieldNamePart )*
FieldNamePart ::=  Identifier ( "[" Integer "]" )?
```
An example of FIELDNAMEs:
"points[0] = 0 AND color.red < 100"
struct Color { octet red; octet green; octet blue; }; struct Shape { long points[4]; Color color; };

BOOLEANVALUE: Can either be true of false, case sensitive.

BOOLEANVALUE ::=  ["TRUE", "true", "FALSE", "false"]

INTEGERVALUE: Any series of digits, optionally preceded by a plus or minus sign, representing a decimal integer value within the range of the system. A hexadecimal number is preceded by 0x and must be a valid hexadecimal expression.
```
INTEGERVALUE ::=  (["+","-"])? Integer
Integer      ::=  (["0"-"9"])+ | ["0x","0X"](["0"-"9", "A"-"F", "a"-"f"])+
```
An example of INTEGERVALUE:
```
value = -10
```
CHARVALUE: A single character enclosed between single quotes.
```
CHARVALUE ::=  "'" Character "'"
Character ::=  ~["\n"]
```
An example of CHARVALUE:
```
value = 'c'
```
FLOATVALUE: Any series of digits, optionally preceded by a plus or minus sign and optionally including a floating point (.). A power-of-ten expression may be postfixed, which has the syntax e:sup:n, where n is a number, optionally preceded by a plus or minus sign.
```
FLOATVALUE ::=  (["+"], "-"])? (Integer Exponent | Integer Fractional | Integer Fractional Exponent)
Fractional ::=  "." Integer
Exponent   ::=  ["e","E"] (["+"], "-"])? Integer
```
An example of FLOATVALUE:
```
value = 10.1e-10
```
STRINGVALUE: Any series of characters encapsulated in single quotes, except a new-line character or a right quote. A string starts with a left or right quote, but ends with a right quote.
```
STRINGVALUE ::=  ["'"] ~["'", "\r", "\n"] ["'"]
```
An example of STRINGVALUE:
```
value = 'This is a string'
```
ENUMERATEDVALUE: An enumerated value is a reference to a value declared within an enumeration. Enumerated values consist of the name of the enumeration label enclosed in single quotes. The name used for the enumeration label must correspond to the label names specified in the IDL definition of the enumeration.
```
ENUMERATEDVALUE ::=  ["'"] ~["'", "\r", "\n"] ["'"]
```
An example of ENUMERATEDVALUE:
value = 'ENUM_VALUE_1'
enum MyEnum { ENUM_VALUE_1, ENUM_VALUE_2, ENUM_VALUE_3 }; struct Enumerators { MyEnum value; };
PARAMETER: A parameter is of the form %n, where n represents a natural number (zero included) smaller than 100. It refers to the n + 1 th argument in the given context.
```
PARAMETER ::=  ["%"] ["0"-"9"] (["0"-"9"])?
```
An example of PARAMETER:
```
value = %1
```

3.5.9.2. Like condition¶

The like operator is similar as the one defined by SQL. This operator can only be used with strings. There are two wildcards that could be used in conjunction with this operator

The percent sign % (or its alias *) represents zero, one, or multiple characters.
The underscore sign _ (or its alias ?) represents one single character.

All wildcards can also be used in combinations.

An example of like operator

"str like '%bird%'"

struct Like
{
    string str;
};

where string There are birds flying will return true.

3.5.9.3. Match condition¶

The match operator performs a full-text search using a regular expression. This operator can only be used with strings. It uses the Basic Regular Expression (BRE) defined by POSIX.

An example of match operator

"str match '^The'"

struct Like
{
    string str;
};

where string There are birds flying will return true.

3.5.9.4. Type comparisons¶

For the supported operators in the grammar, next table shows the type compatibility.

Operator1 \| Operator2	BOOLEAN	INTEGER	FLOAT	CHAR	STRING	ENUM
BOOLEAN	✅	✅	❌	❌	❌	❌
INTEGER	✅	✅	✅	❌	❌	❌
FLOAT	❌	✅	✅	❌	❌	❌
CHAR	❌	❌	❌	✅	✅	❌
STRING	❌	❌	❌	✅	✅	❌
ENUM	❌	✅	❌	❌	❌	✅ *

(*) Only for the same enumerated type.

3.5.9.5. Example¶

Assuming Topic Shape has next IDL definition.

struct Shape
{
    long x,
    long y,
    long z,
    long width,
    long height
};

An example of filter expression would be:

"x < 23 AND y > 50 AND width BETWEEN %0 AND %1"

A ContentFilteredTopic may be created using this filter expression as explained in section Creating a ContentFilteredTopic.

ContentFilteredTopic* sql_filter_topic =
        participant->create_contentfilteredtopic("Shape", topic,
                "x < 23 AND y > 50 AND width BETWEEN %0 AND %1",
                {"10", "20"});

In this example parameters are used. Internally the ContentFilteredTopic will be created with the filter expression below, after setting the provided parameters.

"x < 23 AND y > 50 AND width BETWEEN 10 AND 20"