NetricsServerInterface.NetricsPredicate Class Reference

Search predicates are used to select or score records based on exact matching tests. More...

Public Types
enum	pred_ops {   EQUALS = 0 , INSEN_EQUALS = 1 , LESSTHAN = 2 , INSEN_LESSTHAN = 3 ,   LESSTHANOREQ = 4 , INSEN_LESSTHANOREQ = 5 , GREATERTHAN = 6 , INSEN_GREATERTHAN = 7 ,   GREATERTHANOREQ = 8 , INSEN_GREATERTHANOREQ = 9 , PLUS = 10 , MINUS = 11 ,   TIMES = 12 , DIVIDEDBY = 13 , TOTHE = 14 , AND = 15 ,   OR = 16 , NOT = 17 , ISIN = 18 , INSEN_ISIN = 19 ,   TOINT = 20 , TODBL = 21 , TODATE = 22 , TODATEEU = 23 ,   TOKENIZE = 24 , SUPERSET = 25 , SUBSET = 26 , TOBLK = 27 ,   TODATET = 28 , TODATEEUT = 29 , ABS = 30 , ARGS_CREATE = 31 ,   ARGS_APPEND = 32 , FUNC_IF = 33 , FUNC_GEO_DIST = 34 , FUNC_TO_SCORE = 35 ,   STARTSWITH = 36 , INSEN_STARTSWITH = 37 , ENDSWITH = 38 , INSEN_ENDSWITH = 39 ,   LIKE = 40 , INSEN_LIKE = 41 , REGEX_MATCH = 42 , INSEN_REGEX_MATCH = 43 ,   ISBLANK = 44 }
	An enumeration of all the predicate operators. More...
enum	DistanceUnits { KILOMETERS , MILES }
	Units of measure for distance functions. More...

Public Member Functions
	NetricsPredicate (String pred_str)
	Create a predicate from a string.

Detailed Description

Search predicates are used to select or score records based on exact matching tests.

Predicates are used in two ways: as a filter to restrict the records to be considered based on some exact match criteria, as a querylet within a query that computes a score based on some exact match criteria. The first is strictly a true/false test that, if false, completely eliminates a record from consideration before the record is scored. The second contributes a score (usually either 0.0 or 1.0 but could be any value between 0.0 and 1.0) that is combined with other querylet scores to determine the overall match score for a record. It acts like an exact matching version of the simple or cognate querylets. Thus the second form doesn't necessarily filter out records even if the predicate match fails. In both cases the Predicate is defined in exactly the same way, the only difference being that for a filtering predicate the result type must be boolean, for a predicate querylet the result type may be boolean or a floating point value.

Search predicates can be specified in two ways, either through a string that defines the predicate or by building it up using this class. The string format is described under the setSearchPredicate method of the NetricsSearchCfg class, how to build predicates using the NetricsPredicate class is described here.

Let's start with a simple example.

Imagine you have two fields in a table - name and company. Your business requirements assert that you be able to search only within a given company.

For example, someone might want to search for the Joe Schmoe who works for Pepsi, not the one who works for Coca-cola. He knows Joe Schmoe works for Pepsi and he wants no results returned for people who work for Coca-cola. This would be an example of a filtering predicate.

If you performed a fuzzy search on both of the fields, this is not guaranteed. Some not-insignificant value would still be assigned to a match in the company field, and the matching company could be Coca-cola. For instance, searching for the name "Bloke" would have a reasonably strong match with the company Coca-cola. This is not the behavior you want.

Instead, you want to search only the first name field and set a predicate where the field "company" must match the String "Pepsi," or it will not be evaluated at all. This would pass to the search filter only those records which evaluate to true in the predicate, in this case guaranteeing that only those people who work for Pepsi are searched.

Here is what the code would look like.

NetricsSearchCfg tblcfg = new NetricsSearchCfg("tbl");
NetricsPredicate pred1 = tblcfg.CreateStringOperand("Pepsi");
NetricsPredicate pred2 = tblcfg.CreateFieldNameOperand("Company");
NetricsPredicate pred3 = tblcfg.CreatePredicate(pred1,0,pred2);
tblcfg.SetSearchPredicate(pred3);

In addition, the relationship between predicates is hierarchical. You can create predicate operands and then combine them with other operators using the CreatePredicate method of the NetricsSearchCfg class.

In fact, you can nest predicates to an arbitrary depth. Imagine you are searching for Joe Schmoe, and you aren't sure whether he works for Pepsi or Coke, but you are positive it is either Pepsi or Coke and you don't want to see any results from Snapple.

Here is what the code would look like.

NetricsSearchCfg tblcfg = new NetricsSearchCfg("tbl");
NetricsPredicate pred1 = tblcfg.CreateStringOperand("Pepsi");
NetricsPredicate pred2 = tblcfg.CreateFieldNameOperand("Company");
// create the pepsi predicate as before
NetricsPredicate pred3 = tblcfg.CreatePredicate(pred1,0,pred2);
NetricsPredicate pred4 = tblcfg.CreatePredicate("Coke");
// create the coke predicate
NetricsPredicate pred5 = tblcfg.CreatePredicate(pred2,0,pred4);
// combine the two predicates
NetricsPredicate pred6 = tblcfg.CreatePredicate(pred3,10,pred5);
tblcfg.SetSearchPredicate(pred6);

Remember, predicates can be arbitrarily nested, but not all predicates make sense. For instance, a predicate can be created by using the TOKENIZE operator on a long data type, but will generate an error in the server. Make sure your predicates are not only well formed, but make sense. If you continue to receive error messages, check the error description, and you will get a detailed account of what is causing the error.

Predicates do not support implicit type conversions. Make sure the operands to each binary operator have the same type. Make sure the operand of each unary operator has the correct type.

See also

NetricsSearchCfg, NetricsSearchCfg.SetSearchPredicate(String), NetricsQuery.Predicate(NetricsPredicate)

Member Enumeration Documentation

DistanceUnits

enum NetricsServerInterface.NetricsPredicate.DistanceUnits

Units of measure for distance functions.

Enumerator
KILOMETERS	Return Distance in Kilometers.
MILES	Return Distance in Miles.

pred_ops

enum NetricsServerInterface.NetricsPredicate.pred_ops

An enumeration of all the predicate operators.

Enumerator
EQUALS	return true if operands are equal
INSEN_EQUALS	letter case insensitive version of EQUALS
LESSTHAN	return true if left side is less than right
INSEN_LESSTHAN	letter case insensitive version if LESSTHAN
LESSTHANOREQ	return true if left side is less than or equal to right
INSEN_LESSTHANOREQ	letter case insensitive version of LESSTHANOREQ
GREATERTHAN	return true if left side is greater than right
INSEN_GREATERTHAN	letter case insensitive version of GREATHERTHAN
GREATERTHANOREQ	return true if left side is greater than or equal to right
INSEN_GREATERTHANOREQ	letter case insensitive version of GREATERTHANOREQ
PLUS	Sum numbers, concatenate strings.
MINUS	Subtract numbers.
TIMES	Multiply numbers.
DIVIDEDBY	Divide numbers.
TOTHE	Raise a number to a power.
AND	Return true if both operands are true.
OR	Return true if either operand is true.
NOT	Return true if operand is false.
ISIN	Return true if left is substring of right.
INSEN_ISIN	Return true if left is substring of right letter case insensitive.
TOINT	Convert operand to an integer.
TODBL	Convert operand to a double.
TODATE	Convert operand to a date.
TODATEEU	Convert operand to a date assuming European formatting.
TOKENIZE	Split a string into tokens returning a block array.
SUPERSET	Return true if the block array on the left contains all values in the block array on the right.
SUBSET	Return true if all values in the block array on the left are in the block array on the right.
TOBLK	Convert operand to a block.
TODATET	Convert operand to a data-time value.
TODATEEUT	Convert operand to a date-time value assuming European formatting.
ABS	Return absolute value of a number.
ARGS_CREATE	Create an argument list with one argument.
ARGS_APPEND	Append an argument to an argument list.
FUNC_IF	If predicate function.
FUNC_GEO_DIST	Geo-distance predicate function for calculating distances between two points.
FUNC_TO_SCORE	Normalize a float value into a 0.0 to 1.0 score.
STARTSWITH	Check if left argument starts with right argument.
INSEN_STARTSWITH	Check if left argument starts with right argument, ignoring letter case and diacritics.
ENDSWITH	Check if left argument ends with right argument.
INSEN_ENDSWITH	Check if left argument ends with right argument, ignoring letter case and diacritics.
LIKE	Check if left argument matches right argument as a SQL LIKE pattern. % matches 0 or more characters. %% matches a percent sign. _ matches exactly one character.
INSEN_LIKE	As LIKE, but ignores letter case and diacritics.
REGEX_MATCH	Check if left argument matches right argument as a regular expression. This uses regular-expressions, not ibi Patterns fuzzy matching. Uses the "ECMAScript 3" regular expression grammar.
INSEN_REGEX_MATCH	As See also REGEX_MATCH , but ignores letter case and diacritics.
ISBLANK	Check if the argument consists only of whitespace and punctuation. See the Programmers Guide for a complete list of whitespace and punctuation characters.