Package com.netrics.likeit

Class NetricsSearchCfg

    • Constructor Detail

      • NetricsSearchCfg

        public NetricsSearchCfg​(java.lang.String tblname)
        Configure a standard search against a single table. This configuration is not usable until a query has been added with the setNetricsQuery method.
        Parameters:
        tblname - The name of the table to be searched.

      • NetricsSearchCfg

        public NetricsSearchCfg​(NetricsJoin join_def)
        Configure a joined search against a set of joined tables. This configures a joined query as defined by the NetricsJoin object. This configuration is not usable until a query has been added with the setNetricsQuery method.
        Parameters:
        join_def - The definition of the join relation. This must not be null.

    • Method Detail

      • setNetricsQuery

        public void setNetricsQuery​(NetricsQuery nq)
        Set the NetricsQuery to be performed.

        This should be called exactly once for each NetricsSearchCfg object. The query is applied to the table, or joined set of tables for this search configuration.

        Parameters:
        nq - The query to use in the search.
        See Also:
        NetricsQuery

      • addQuery

        @Deprecated
public void addQuery​(java.lang.String query,
                     java.lang.String[] names)
        Deprecated.
        As of release 4.1.1. Use setNetricsQuery(NetricsQuery)
        Add a query to the NetricsSearchCfg object.

        This deprecated method can't be used with joined configurations. Queries are specified at the table level. That is, queries cannot span tables.

        The AddQuery method works by passing a query string and an array of field names (which are field names in the table you are searching) against which to search. You can add as many query / field-name-array pairs as you like.

        In the simple case, you can use the AddQuery method to restrict those fields against which you want to search (if some fields are non-searchable for instance).

        Another good example is the case where you want to search each query against its associated field. That is, imagine you have a table of music with an artist field, album field, and song field. You might have an "advanced" search where you want to search an artist query against the artist field, album query against the album field, and so on.

        In fact, you can specify any number of queries and any fields you want them to search against. You can even pass multiple NetricsSearchCfg objects to the search method, allowing you to search multiple tables at the same time.

        Parameters:
        query - The query that will be used to search the given field names.
        names - The field names against which the query will be searched (null will search all fields in the table).

      • addQuery

        @Deprecated
public void addQuery​(java.lang.String query,
                     java.lang.String[] names,
                     double[] fieldWeights,
                     double queryletWeight,
                     int alignField,
                     java.lang.String thesaurusName)
        Deprecated.
        As of release 4.1.1. Use setNetricsQuery(NetricsQuery)
        Add a query using querylet field weights.

        This deprecated method can't be used with joined configurations.

        Parameters:
        query - The query that will be used to search the given field names.
        names - The field names against which the query will be searched.
        fieldWeights - An array of doubles which weigh the importance of fields. Use a higher number to weigh a given field as more important. The doubles are one per field for the fields specified for this query (the lengths of the 2nd and 3rd parameters to this method should be the same). These weights are normalized into the standard range of 0.0 to 1.0.
        queryletWeight - Specifies the fraction of the entire record score that should come from this querylet. (A value of -1.0 will set each querylet to an equal weight.) If you set a queryletWeight for a query, you must set a queryletWeight for every query for the table.
        alignField - The field number which this querylet will most likely be found in. This can be used as a hint to the search algorithm (field numbers start at 0).
        thesaurusName - The name of a thesaurus to be used just for this querylet. (A null string will not use a thesaurus for the querylet.)

      • makeDependentQuerylets

        @Deprecated
public void makeDependentQuerylets​(int[] multiqueryletIds)
                            throws NetricsException
        Deprecated.
        As of release 4.1.1. Use setNetricsQuery(NetricsQuery)
        Deprecated method for specifying dependent/independent querylets.

        This method can't be used with joined query configurations.

        It is recommended that you call this function if the same field is used in two or more querylets (i.e. a "First Name" querylet and a "Last Name" querylet against the same "Full Name" field). This function allows the user to specify which querylets are "dependent" on each other (i.e. only one or the other of the querylets can match a given stretch of text in the record). If this function is not used, the querylet dependencies will be automatically detected (by looking for overlapping fieldsets), but it is almost always better to use this function, even if the querylet dependencies are trivial.

        Parameters:
        multiqueryletIds - Any two querylets that are dependent are part of the same "multiquerylet." The multiqueryletIds parameter should be the same length as the number of querylets added to the NetricsSearchCfg. Each position in the array is the ID of the multiquerylet that querylet belongs to. In this way, if any two positions in the array have the same multiquerylet id, they will be added to the same multiquerylet and will thus be dependent querylets. It is an error to use multiquerylet ids less than 0 or greater than the number of querylets added to the NetricsSearchCfg object. For example, with querylets "First Name", "Last Name", and "Address", the array {0,0,1} would make the first two querylets dependent and the last querylet independent of the other two.
        Throws:
        NetricsException - if an entry in multiqueryletIds is invalid, or if multiqueryletIds has already been called.

      • CreateIntOperand

        public static NetricsPredicate CreateIntOperand​(int i)
        Create a predicate constant value of type int.
        Parameters:
        i - value to place in the predicate
        Returns:
        a predicate constant value of type int.
        See Also:
        NetricsPredicate

      • CreateBoolOperand

        public static NetricsPredicate CreateBoolOperand​(boolean b)
        Create a predicate constant value of type boolean.
        Parameters:
        b - value to place in the predicate
        Returns:
        a predicate constant value of type boolean.
        See Also:
        NetricsPredicate

      • CreateStringOperand

        public static NetricsPredicate CreateStringOperand​(java.lang.String s)
        Create a predicate constant of type String.
        Parameters:
        s - value to place in the predicate
        Returns:
        a predicate constant of type String.
        See Also:
        NetricsPredicate

      • CreateDoubleOperand

        public static NetricsPredicate CreateDoubleOperand​(double d)
        Create a predicate constant of type double.
        Parameters:
        d - value to place in the predicate
        Returns:
        a predicate constant of type double.
        See Also:
        NetricsPredicate

      • CreateFieldNameOperand

        public static NetricsPredicate CreateFieldNameOperand​(java.lang.String fn)
        Create a predicate reference to a field using a field name.
        Parameters:
        fn - fields name to place in the predicate
        Returns:
        a predicate reference to a field using a field name.
        See Also:
        NetricsPredicate

      • CreatePredicate

        public static NetricsPredicate CreatePredicate​(NetricsPredicate predl,
                                               int op,
                                               NetricsPredicate predr)
        Create a predicate by combining two predicates that were previously created.

        The op parameter is applied between the two predicates. The possible op codes are listed in the table below.

        Predicate Operators:

        .
        Operator IdDescription
        NetricsPredicate.EQUALSThe equality operator (==) - valid for string comparisons as well
        NetricsPredicate.INSEN_EQUALSThe equality operator (==) - valid for case insensitive string comparisons as well
        NetricsPredicate.LESSTHANThe less than operator (<)
        NetricsPredicate.INSEN_LESSTHANThe case insensitive less than operator (<)
        NetricsPredicate.LESSTHANOREQThe less that or equal to operator (<=)
        NetricsPredicate.INSEN_LESSTHANOREQThe case insensitive less that or equal to operator (<=)
        NetricsPredicate.GREATERTHANThe greater than operator (>)
        NetricsPredicate.INSEN_GREATERTHANThe case insensitive greater than operator (>)
        NetricsPredicate.GREATERTHANOREQThe greater than or equal to operator (>=)
        NetricsPredicate.INSEN_GREATERTHANOREQThe case insensitive greater than or equal to operator (>=)
        NetricsPredicate.PLUSThe addition operator (+)
        NetricsPredicate.MINUSThe subtraction operator (-)
        NetricsPredicate.TIMESThe multiplication operator (*)
        NetricsPredicate.DIVIDEDBYThe division operator (/)
        NetricsPredicate.TOTHEThe exponent operator (^)
        NetricsPredicate.ANDThe AND operator (&&)
        NetricsPredicate.ORThe OR operator (||)
        NetricsPredicate.ISINThe substring operator - detects substring matches of the left operand in the right operand
        NetricsPredicate.INSEN_ISINThe substring operator - detects substring matches of the left operand in the right operand ignoring letter case
        NetricsPredicate.TOKENIZEThe tokenize operator
        NetricsPredicate.SUPERSETThe superset operator
        NetricsPredicate.SUBSETThe subset operator

        Predicates can nested to an arbitrary depth.

        See the NetricsPredicate object for information on predicates.

        Parameters:
        predl - left-hand operand
        op - predicate operand
        predr - right-hand operand
        Returns:
        a new binary predicate
        See Also:
        NetricsPredicate

      • CreateUnaryPredicate

        public static NetricsPredicate CreateUnaryPredicate​(NetricsPredicate pred,
                                                    int op)
        Create a predicate by combining a single predicate and an operation to be performed on the predicate.

        Possible op codes:

         
        Operator IdDescription
        NetricsPredicate.MINUSNegate - equivalent to multiplying by -1
        NetricsPredicate.NOTNot - logical negation (!)
        NetricsPredicate.TOINTTo int type (cast)
        NetricsPredicate.TODBLTo float type (cast)
        NetricsPredicate.TODATETo date type
        NetricsPredicate.TODATEEUTo EU date type (European data format)
        NetricsPredicate.TOKENIZETokenize
        NetricsPredicate.TOBLKTo block type
        NetricsPredicate.TODATETTo date type, with time (default format yyyy/mm/dd HH:MM:SS)
        NetricsPredicate.TODATEEUTTo EU date type, with time
        NetricsPredicate.ABSAbsolute Value

        Remember, predicates can nested to an arbitrary depth.

        See the NetricsPredicate object for information on predicates.

        Parameters:
        pred - operand
        op - predicate operator
        Returns:
        a new unary predicate
        See Also:
        NetricsPredicate

      • CreateGeoDistance

        public static NetricsPredicate CreateGeoDistance​(java.lang.String lat_field,
                                                 java.lang.String long_field,
                                                 double latitude,
                                                 double longitude,
                                                 NetricsPredicate.DistanceUnits units)
        Create a predicate to return the distance between a specified point and a point in a record. This method creates a predicate that uses the Geo-Distance function to determine the distance between two points, the first point is taken from two record fields, the second is given as fixed constants.
        Parameters:
        lat_field - Name of a record field that contains a latitude in degrees. This must have a field type of double.
        long_field - Name of a record field that contains a longitude in degrees. This must have a field type of double.
        latitude - A latitude in degrees.
        longitude - A longitude in degrees.
        units - The type of units the distance should be returned in.
        Returns:
        a new geo-distance predicate
        See Also:
        NetricsPredicate

      • CreateGeoDistance

        public static NetricsPredicate CreateGeoDistance​(NetricsPredicate lat1,
                                                 NetricsPredicate long1,
                                                 NetricsPredicate lat2,
                                                 NetricsPredicate long2,
                                                 NetricsPredicate.DistanceUnits units)
        Create a predicate to return the distance between two points. This method creates a predicate that uses the Geo-Distance function to determine the distance between two points. The values are given as predicate expressions.
        Parameters:
        lat1 - The latitude of the first point in degrees.
        long1 - The longitude of the first point in degrees.
        lat2 - The latitude of the second point in degrees.
        long2 - The longitude of the second point in degrees.
        units - The type of units the distance should be returned in.
        Returns:
        a new geo-distance predicate
        See Also:
        NetricsPredicate

      • CreateToScore

        public static NetricsPredicate CreateToScore​(NetricsPredicate raw_value,
                                             NetricsPredicate zero_score_val,
                                             NetricsPredicate one_score_val)
        Create a call to normalize a value into a zero to one score.

        This method creates a call to the "to_score" predicate function. This function is used to convert a float value into a valid score value. It is passed the raw value to be converted, a value that represents a 0.0 score, and a value that represents a value that represents a 1.0 score. The 0.0 score value may be greater than the 1.0 score value. Values outside the 0.0 value to 1.0 value range are assigned a score of 0.0 or 1.0. Values within the range are assigned a score based on linear interpolation. Some examples:

        to_score(10.0, 100.0, 0.0) = 0.1
        to_score(10.0, 0.0, 100.0) = 0.9
        to_score(12.0, 10.0, 0.0) = 0.0
        to_score(1.0, 5.0, 20.0) = 0.0

        This is useful in conjunction the geo_distance function to create scores based on the distance between two points. For example to assign a score based on how close a record is to a given location with records more than 25.0 miles away considered a non-match the following could be used: 

         
 
  NetricsPredicate dist_expr = NetricsSearchCfg.CreateGeoDistance(
                                "lat", "long",
                                45.0, 75.0,
                                NetricsPredicate.DistanceUnits.MILES);
  NetricsPredicate zero_val ;
  zero_val = NetricsSearchCfg.CreateDoubleOperand(25.0);
  NetricsPredicate one_val ;
  one_val = NetricsSearchCfg.CreateDoubleOperand(0.0);
  NetricsPredicate scoring_pred ;
  scoring_pred = NetricsSearchCfg.CreateToScore(dist_expr,
                                                zero_val,
                                                one_val);
        Parameters:
        raw_value - The raw float or double value to be normalized into a valid score.
        zero_score_val - The raw double value at which the output score becomes zero.
        one_score_val - The raw double value at which the output score becomes one.
        Returns:
        a new score-normalizing predicate
        See Also:
        NetricsPredicate

      • CreateToScore

        public static NetricsPredicate CreateToScore​(NetricsPredicate raw_value,
                                             double zero_score_val,
                                             double one_score_val)
        Create a call to normalize a value into a zero to one score. This is a convenience routine for CreateToScore that takes the zero value and one value as double arguments instead of as NetricsPredicate objects.
        Parameters:
        raw_value - The raw float or double value to be normalized into a valid score.
        zero_score_val - The raw value at which the output score becomes zero.
        one_score_val - The raw value at which the output score becomes one.
        Returns:
        a score-normalizing predicate
        See Also:
        NetricsPredicate

      • CreateSimpleIf

        public static NetricsPredicate CreateSimpleIf​(NetricsPredicate condition,
                                              NetricsPredicate then_case,
                                              NetricsPredicate else_case)
        Create a simple if-then-else clause. This creates a simple if-then-else clause using the predicate if function.
        Parameters:
        condition - the conditional expression.
        then_case - the expression value to use if condition is true.
        else_case - the expression value to use if condition is false.
        Returns:
        an if-then-else predicate

      • CreateIfElseIf

        public static NetricsPredicate CreateIfElseIf​(NetricsPredicate... sub_exprs)
        Create an if-then-elif-then*-else clause.

        The predicate if function allows an arbitrary number of conditional clauses. The generalized form of the if function is:

        if { [cond,result,]* default-value }

        The cond expressions are evaluated in order, the result value associated with the first one that evaluates to true is returned, if none evaluate to true, default-value is returned.

        All of the cond expressions must evaluate to a boolean value. All of the result and the default-value expressions must evaluate to the same type. If a single value is given it is treated as a default-value with no cond result clauses. I.e. a single value is just returned as the result of the if function.

        This method allows for creation of the generalized if clause by allowing any number of arguments to be passed in.

        Parameters:
        sub_exprs - the sub-expressions for the if function.
        Returns:
        an if-then-elif-then-else predicate
        See Also:
        NetricsPredicate

      • SetSearchPredicate

        public void SetSearchPredicate​(NetricsPredicate pred)
        Set the search predicate for a given search.

        This is the predicate which must evaluate to true for any record returned by the search. In other words, the ibi™ Patterns - Search server will return the "MatchesRequested" best records which evaluated to true for the given predicate. One one such filtering predicate can be defined for each table used in a search (i.e. one per NetricsSearchCfg object).

        See the NetricsPredicate object for information on predicates.

        Parameters:
        pred - predicate to use as the search predicate
        See Also:
        NetricsPredicate

      • SetSearchPredicate

        public void SetSearchPredicate​(java.lang.String expr)
        Set the search predicate from a string.

        In addition to building the search predicate piece by piece the entire predicate can be defined as a string using a SQL-like syntax.

        Basic items in predicate syntax:

        .
        ?TRUE?, ?FALSE?Boolean constant values are true and false enclosed in question marks. Letter case insensitive
        123,0777,0x8FFFInteger constant values. They follow the standard "C" and Java conventions for decimal, Octal and Hex integers.
        123.45, 0.17e-10Floating point values. They follow the standard "C" and Java conventions for fixed and scientific notation values.
        "string"string constants are enclosed in double quotes. The basic XML/HMTL encoding scheme is used to represent the double quote character (") itself and other special characters. 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 that you must NOT insert an encoded NULL character into the string as this is a NULL terminated string value.
        :"byte block"A byte block is specified by preceding a quoted string value with a colon (:) character. The length of the block is computed automatically. All non-valid string characters must be encoded using the XML/HTML like encodings as defined for strings.
        #2Table fields specified by numeric position. An integer value preceded with the pound (#) character is used to represent the table field at the indicated column position. Like array indexes in Java and "C" these field numbers are zero based.
        $"first name"Table fields specified by field name. A quoted string value (see string description above) preceded by the dollar ($) sign. The string value is the field name.
        [ :"block 1", :"block 2" ]
        [ :]        		Block arrays. A comma separated list of blocks enclosed in square brackets ([]). To specify a Block array with zero entries use an open bracket followed by colon close bracket (:]) no space between the colon and close bracket.
        { expr 1, expr 2 }Argument Lists. A comma separated list of expressions enclosed in curly braces ({}) is a special notation used to create argument lists for predicate functions.

        Predicate expressions are defined in a typical manner. E.g.
        INT $"age" > 21
        specifies all records where the "age" field is greater than 21 (this assumes the age field is a text field, if the age field was of type integer then the conversion operator INT would not be needed). Parenthesis can be used to group operations into more complex expressions:
        ((INT $"age" + INT $"years experience") / 2) - 1 >= 21
        Operators are left associative, that is:
        2 + 3 + 12
        is equivalent to:
        (2 + 3) + 12

        Operators have precedence similar to those in Java. So:
        12 + 2 * 3
        is the same as:
        12 + (2 * 3)
        Special unary operators called predicate functions take an argument list as their single argument:
        geod { DBL $"lat", DBL $"long", 45.0, 75.0, "miles" } < 25.0 calls the geo-distance function with an argument list consisting of five arguments and tests if the value is less than 25 miles.
        Some key differences between the precedence of predicate operators and Java or "C" operators are:

        • All unary operators have higher precedence (bind tighter) than binary operators, this includes all predicate function operators.
        • + has slightly higher precedence than - (minus), thus a - b + c is the same as a - (b + c) not (a - b) + c
        • similarly multiply (*) has slightly higher precedence than divide (/)
        • All comparison operators have the same precedence.

        Binary operators listed from highest precedence to lowest:

        .
        operatorsdescription
        **raise to power
        *multiple
        /divide
        +addition for numbers, concatenation for strings
        -subtraction
        =, ==, >, >=, <, <=, SUBSET, SUPERSET, IN Case-sensitive comparison operators, "=" and "==" are synonyms.
        ~=, ~==, ~> ~>=, ~<, ~<=, I_IN Case-insensitive comparison operators, ~"=" and ~"==" are synonyms.
        ANDLogical and joining operator, similar to the Java && operator
        ORLogical or joining operator, similar to the Java || operator

        Unary operators:

        .
        operatordescription
        +arithmetic positive, this does nothing
        -arithmetic negation
        NOTlogical inverse
        UPPERconvert character string/byte block to upper case
        LOWERconvert character string/byte block to lower case
        INTconvert value to integer
        DBL DOUBLE FLOATconvert value to floating point. These are all synonyms for the same operation.
        DATEconvert value to a date.
        DATEEU EUDATEconvert value to a date. String and byte block format dates are assumed to be in European format. These are synonyms for the same operation
        BLOCKconvert value to a byte block.
        SPLIT TOKENIZEsplit a string or block into a block array with each element of the array being a word from the string.
        ABSreturn the Absolute Value of an integer or double value.

        The names of operators are letter case insensitive. So ABS, Abs and abs are all names for the same absolute value operator. For more information on these operations see NetricsPredicate.

        The final example from NetricsPredicate as a string predicate would be:

        NetricsSearchCfg tblcfg = new NetricsSearchCfg("tbl");
        tblcfg.SetSearchPredicate("$\"Company\" == \"Pepsi\" or $\"Company\" == \"Coke\"");

        Parameters:
        expr - predicate expression to use as the search predicate
        See Also:
        NetricsPredicate