Constructing Predicate Expressions

The simple predicate in the example Filtering with Predicates, $“STATE” = “CA”, exhibits all of the main features of predicate expressions:

•

Predicate expressions generally contain references to one or more fields of the table. In the example, $“STATE” is a reference to the content of the STATE field of the record being evaluated.

•

Predicate expressions usually also contain constant “data” of their own. In the example, “CA” is a constant value private to the predicate expression.

•

Predicate expressions usually use operators to test the truth of a condition involving given data and the content of one or more fields. In the example, the “=” operator tests for (case-sensitive) string equality between the constant value “CA” and the value of the STATE field.

Constants, Field References, and Operators

Field references in predicate expressions can refer to fields by name or by numeric column position. Field names in predicate expressions are the same as used elsewhere in the ibi Patterns - Search API. They can be qualified with table names (for joined records) and attribute names. In a joined search, column position refers to the position in the joined record, not the table. Constant values used in predicate expressions include boolean, integer, double-precision float, string, byte block, and byte-block array. The following table illustrates how field references and constants are represented in predicate strings:

Examples	Description
?TRUE?, ?FALSE?	Boolean constants (letter-case insensitive)
123, 0777, 0x8FFF	Integer constants (decimal, octal, hexadecimal)
123.45, 0.17e-10	Floating point values
“string value”	String constants
:“byte block”	Byte block (note the preceding colon)
#2	Table field specified by the column position (zero-based)
$“first name”	Table field specified by the field name
$"varattrs:Color"	Variable attribute specified by name. The text in quotes contains a colon separating the field name for the container field from the Variable Attribute name.
[:“block 1”, :“block 2”], [:]	Block array (note the special representation for empty array)

Integer and floating point values must be within the defined range for “C” integers and doubles, respectively. Both string constants and byte block constants support the basic XML/HTML entity encoding scheme for representing the double quote character itself (that is, &quot;). The numeric conventions: &#ddd;, &#xhh; are recognized and the entity names: quot, amp, lt, gt and apos are recognized. (No other entity names are recognized.)

Note: Do not insert an encoded NULL character into a string constant, since the string is converted to a standard "C" NULL terminated string. Inserting a NULL therefore effectively terminates the string value at that position. Byte blocks on the other hand might contain NULL characters as they are not NULL terminated strings but use an explicit length value, which is computed automatically and need not be provided by the user.

Operators in predicate expressions are either unary (like absolute value, logical inverse, or type conversion operators) or binary (like string equality or addition operators). In general, operators accept as operands constant values, field references, or other (nested) predicate expressions. Not all combinations of operators and constant or field-value types make sense. In such cases, the predicate expression is rejected by the search with an error.

In addition, there is a special type of unary operator called a predicate function. These operators accept a single value of the special type "argument list". An argument list is a special type that is constructed using special operators, but it is not necessary to know the details of an argument list construction unless you are using the "C" interface. The Java and .NET API's provide method calls to create each of the defined predicate functions. In predicate string expressions the argument lists are contained within braces.

   geo_distance { 40.0, 75.0, $"latitude", $"longitude", "miles" }

calls the geo-distance function to compute the distance in miles between latitude 40.0, longitude 75.0, and the location defined by the latitude and longitude fields of the record.

ibi Patterns - Search provides a rich set of operators with which to construct predicate expressions. Here is the complete list of unary operators (note that some operators have one or more synonyms):

Operator	Description
int	Type conversion to integer
dbl, double, float	Type conversion to double
date	Type conversion to date
date_time, datet	Type conversion to date-time
eudate, dateeu	Type conversion to date (expects European day/month/year format)
eudate_time, dateeu_time, eudatet, dateeut	Type conversion to date-time (expects European day/month/year format)
blk, block	Type conversion to byte block
-	Unary minus
+	Unary plus (does nothing)
not	Boolean logical inverse
split, tokenize	Split string or block into words
abs	Absolute value of integer or double
geo_distance, geodistance, geod	Predicate function to compute the distance between two points on the Earth’s surface.
if	Predicate function that implements a conditional expression.
to_score, toscore	Predicate function to normalize a floating point value into a 0.0 - 1.0 score range.

Here is the complete list of binary operators (note that several operators have synonyms):

Operator	Description
+	Addition of integers and doubles; concatenation of strings and byte blocks
-	Subtraction of integers and doubles
*	Multiplication of integers and doubles
/	Division of integers and doubles
**	Exponentiation of integers and doubles
and	Logical AND of Booleans
or	Logical OR of Booleans
=, ==	Equality of integers, doubles, strings, blocks, dates, date-times
~=, ~==	Letter case insensitive equality of strings, blocks
<	Comparison of integers, doubles, strings, blocks, dates, date-times
~<	Letter case insensitive comparison of strings, blocks
<=	Comparison of integers, doubles, strings, blocks, dates, date-times
~<=	Letter case insensitive comparison of strings, blocks
>	Comparison of integers, doubles, strings, blocks, dates, date-times
~>	Letter case insensitive comparison of strings, blocks
>=	Comparison of integers, doubles, strings, blocks, dates, date-times
~>=	Letter case insensitive comparison of strings, blocks
i_in	Letter case insensitive substring match of strings, blocks.
in	Substring match of strings, blocks
superset	Set comparison of block arrays
subset	Set comparison of block arrays
split, tokenize	Split string or block into words using a specified separator

Note: All lexical comparisons are based on Unicode code points and DON'T take into consideration locale specific sorting conventions for characters.

Operator precedence

All unary operators have higher precedence than binary operators. That is,

block abs $"count1" - $"count2"

is equivalent to

( block ( abs $"count1" ) ) - $"count2"

which is probably not what was intended. Parentheses can be used to alter the default precedence relations:

block abs ( $"count1" - $"count2" )

Since predicate functions are unary operators, they bind to their argument list more tightly than any binary operator. For example,

geod { 40.0, 75.0, $"lat", $"long", "kilometers" } ** 2

is equivalent to:

( geod { 40.0, 75.0, $"lat", $"long", "kilometers" } ) ** 2

and not equivalent to:

geod ( { 40.0, 75.0, $"lat", $"long", "kilometers" } ** 2 )

Binary operators are left associative, for example,

1 + 2 + 3

is implemented as

( 1 + 2 ) + 3

The binary operators listed by precedence from highest to lowest are:

–

tokenize, split

=, ~=, ==, ~==, <. ~<, <=, ~<=, >, ~>, >=, ~>=, in, i_in, superset, subset

and

This listing reflects “standard” precedence relations, but with the following caveats:

• + (addition) has a slightly higher precedence than does - (subtraction), thus a - b + c is equivalent to a - (b + c), not to (a - b) + c

•

* (multiplication) similarly has slightly higher precedence than does / (division)

•

Note that all comparison operators have the same precedence.

More Examples of Predicate Expressions

Include in the search results only records of males born on or after January 1st, 1980:

( $"sex" ~= "m" OR $"sex" ~= "male" ) AND $"birth date" >= date "1/1/1980"

Note: There is no explicit Date constant, so this is how a constant date value is expressed. Note the use of case-insensitive string comparison, and the type conversion of string to date.

Include in the search results only records of the category "tool" at an average price of less than ten dollars:

$"category" ~= "tool" AND ( $"max price" + $"min price" ) / 2.0 < 10.0

Include in the search results only those persons whose previous and current weight differs by less than five pounds:

abs ( $"cur weight" - $"prev weight" ) < 5.0

Include in the search results only the records within 25 miles of a given point.

geod { 40.0, 75.0, $"lat", $"long", "miles" } <= 25.0

Did you find this helpful?

Yes No