com.netrics.likeit

Class NetricsSearchOpts

java.lang.Object

com.netrics.likeit.NetricsSearchOpts

public class NetricsSearchOpts
extends java.lang.Object

This class is used to configure search options which apply for the overall search (for each table being searched).

See Also:

NetricsServerInterface.search(com.netrics.likeit.NetricsSearchCfg, com.netrics.likeit.NetricsSearchOpts)

Field Summary

Fields

Modifier and Type	Field and Description
static int	SCORE_IT Information Theory scoring.
static int	SCORE_MAX Maximum scoring, maximum of Normal and Reverse.
static int	SCORE_MIN Minimum scoring, minimum of Normal and Reverse.
static int	SCORE_NORMAL Normal scoring, look for query in record.
static int	SCORE_REVERSE Reverse scoring, look for record in query.
static int	SCORE_SYMMETRIC Symmetric scoring, match query and record.
static int	TIEBREAK_ALIGNMENT break ties to favor matches closer to beginning of record.
static int	TIEBREAK_FIELDVAL break ties based on the value of a field.
static int	TIEBREAK_RECID break ties using record key, guarantees deterministic order.
static int	TIEBREAK_RECLEN Deprecated, same as TIEBREAK_SCORETYPE Symmetric.
static int	TIEBREAK_SCORETYPE break ties based on another score type.

Constructor Summary

Constructors

Constructor and Description
NetricsSearchOpts() Create a default set of search options

Method Summary

Modifier and Type	Method and Description
void	addCustomTiebreak(int tiebreakId, int tiebreakParam) Can be used to specify how to break ties between two records that have identical textual similarity.
void	baseBgColor(java.lang.String color) Specify a background non-match color for HTML text.
void	baseColor(java.lang.String color) Specify a non-match color for HTML text.
void	boldThresh(int val) Specify the threshold beyond which to bold text.
void	italicsThresh(int val) Specify the threshold beyond which to italicize text.
void	matchBgColor(java.lang.String color) Specify a background match color for HTML text.
void	matchColor(java.lang.String color) Specify a match color for HTML text.
void	maxFontSize(int val) Specify the maximum font size of matching text.
void	scoreType(int scoreType) This specifies the type of score to be used for ordering records.
void	setDetailedStats(boolean enabled) Enable detailed statistics for this search.
void	setEmptyScore(double score) Sets the score a comparison gets when empty data is encountered.
void	setFailEmptyPred(boolean fail) Set whether the predicate fails on empty data.
void	setFailInvalidPred(boolean fail) Set whether a failed predicate is considered true or false.
void	setFetchSize(int size) Tuning parameter, use only on the advice of your TIBCO representative.
void	setGipFiltered(boolean enabled) Enable gip filtering for this table (default).
void	setGpuCallParallelism(java.lang.Integer count) Set the number of simultaneous GPU calls used in the search.
void	setGpuEnabled(java.lang.Boolean enabled) Set whether the search uses GPU-enabled indexing.
void	setGpuTableBlocksPerCall(java.lang.Integer count) Set the number of table-blocks evaluated per GPU call.
void	setInvalidScore(double score) Sets the score a comparison gets when an error occurs.
void	setMatchesRequested(int matchesRequested) Set the number of matches returned by the Netrics Server (default 25).
void	setPCSize(int size) Tuning parameter, use only on the advice of your TIBCO representative.
void	setPhonetic(boolean enabled) Enable phonetic searches for this table.
void	setPsiDensity(int density) Set the density of suffixes produced from query field values.
void	setPsiFiltered(boolean enabled) Enable PSI filtering for this table (default).
void	setPsiLookupFields(java.lang.String[] fields) You should only use this method with the help of your TIBCO technical support representative.
void	setQCSize(int size) Tuning parameter, use only on the advice of your TIBCO representative.
void	setRlModelName(java.lang.String name) You should only use this method with the help of your TIBCO technical support representative.
void	setSortFiltered(boolean enabled) Enable SORT filtering for this table (default).
void	setSortLookupFields(java.lang.String[] fields) You should only use this method with the help of your TIBCO technical support representative.
void	setStartMatch(int startMatch) Set the rank of the first match to be returned by the Netrics Server (default 1).
void	setThesaurusWeight(double weight) Use the specified thesaurus weight in determining matching records.
void	setVisStyle(int styleNo) Sets the visualization style you want returned.
void	setXparm(int id, double value) Use this method only on the advice of your TIBCO representative.
void	setXparm(int id, int value) Use this method only on the advice of your TIBCO representative.
void	underlineThresh(int val) Specify the threshold beyond which to underline text.
void	useAbsoluteCutoff(double val) Cut off the result set at a specific absolute value.
void	useEphemeralThesaurus(com.netrics.likeit.NetricsBaseThesaurus thes_def) Use an ephemeral thesaurus in determining matching records.
void	useExactPlusScoreCutoff(int val) Return all search results which are exact matches plus a fixed number of records which are inexact.
void	useNoCutoff() Revert to not using a cutoff.
void	usePercentOfTopCutoff(double val) Return search results whose scores are above a given percentage of the score of the first record.
void	useSimpleGapCutoff(double val) Return search results until there is gap between adjacent records.
void	useThesaurus(java.lang.String name) Use the specified thesaurus or combined thesaurus in determining matching records.
void	useWeightedDictionary(java.lang.String name) Use the specified weighted dictionary in determining matching records.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SCORE_NORMAL

public static final int SCORE_NORMAL

Normal scoring, look for query in record.

See Also:

Constant Field Values

SCORE_SYMMETRIC

public static final int SCORE_SYMMETRIC

Symmetric scoring, match query and record.

See Also:

Constant Field Values

SCORE_REVERSE

public static final int SCORE_REVERSE

Reverse scoring, look for record in query.

See Also:

Constant Field Values

SCORE_MIN

public static final int SCORE_MIN

Minimum scoring, minimum of Normal and Reverse.

See Also:

Constant Field Values

SCORE_MAX

public static final int SCORE_MAX

Maximum scoring, maximum of Normal and Reverse.

See Also:

Constant Field Values

SCORE_IT

public static final int SCORE_IT

Information Theory scoring.

See Also:

Constant Field Values

TIEBREAK_RECLEN

public static final int TIEBREAK_RECLEN

Deprecated, same as TIEBREAK_SCORETYPE Symmetric.

See Also:

Constant Field Values

TIEBREAK_RECID

public static final int TIEBREAK_RECID

break ties using record key, guarantees deterministic order.

See Also:

Constant Field Values

TIEBREAK_ALIGNMENT

public static final int TIEBREAK_ALIGNMENT

break ties to favor matches closer to beginning of record.

See Also:

Constant Field Values

TIEBREAK_SCORETYPE

public static final int TIEBREAK_SCORETYPE

break ties based on another score type.

See Also:

Constant Field Values

TIEBREAK_FIELDVAL

public static final int TIEBREAK_FIELDVAL

break ties based on the value of a field.

See Also:

Constant Field Values

Constructor Detail

NetricsSearchOpts

public NetricsSearchOpts()

Create a default set of search options

Method Detail

setGpuEnabled

public void setGpuEnabled(java.lang.Boolean enabled)

Set whether the search uses GPU-enabled indexing.

Parameters:

enabled -
True: use gpu-enabled indexing. If the table is not gpu-enabled the search will fail.
False: do not use gpu-enabled indexing.
null: use gpu-enabled indexing only if the table is gpu-enabled.

setGpuCallParallelism

public void setGpuCallParallelism(java.lang.Integer count)

Set the number of simultaneous GPU calls used in the search.

Parameters:

count - the number of simultaneous GPU calls used in the search. See the programmers guide for default and limits. Pass null to use the server's default value.

setGpuTableBlocksPerCall

public void setGpuTableBlocksPerCall(java.lang.Integer count)

Set the number of table-blocks evaluated per GPU call.

Parameters:

count - the number of table-blocks evaluated per GPU call. See the programmers guide for default and limits. Pass null to use the server's default value.

setFetchSize

public void setFetchSize(int size)

Tuning parameter, use only on the advice of your TIBCO representative.

Parameters:

size - the fetch size

setPCSize

public void setPCSize(int size)

Tuning parameter, use only on the advice of your TIBCO representative.

Parameters:

size - the PC size

setQCSize

public void setQCSize(int size)

Tuning parameter, use only on the advice of your TIBCO representative.

Parameters:

size - the QC size

setInvalidScore

public void setInvalidScore(double score)

Sets the score a comparison gets when an error occurs.

This is the same as the setInvalidScore method of the NetricsQuery class, but applies to all querylets that don't explicitly set their own invalid score.

Parameters:

score - the default invalid score for this search.

See Also:

NetricsQuery.setInvalidScore(double)

setEmptyScore

public void setEmptyScore(double score)

Sets the score a comparison gets when empty data is encountered.

This is the same as the setEmptyScore method of the NetricsQuery class, but applies to all querylets that don't explicitly set their own empty score.

Parameters:

score - the default empty score for this search

See Also:

NetricsQuery.setEmptyScore(double)

setFailEmptyPred

public void setFailEmptyPred(boolean fail)

Set whether the predicate fails on empty data.

This applies to filtering predicates. If this is true predicates that encounter empty data, either in the query or record value, fail. The treatment of the failed predicate is then controlled by the setting of the Invalid Predicate flag. If this is false the predicate is evaluated against the empty data assuming a default value appropriate to the data type of the field.

The default value for this flag is true.

Parameters:

fail - new value for the predicate-fail-on-empty flag.

See Also:

setFailInvalidPred(boolean)

setFailInvalidPred

public void setFailInvalidPred(boolean fail)

Set whether a failed predicate is considered true or false.

This applies to filtering predicates. It controls how failed predicates are treated. A predicate fails if:

• an invalid data value, either in the query or record data, is encountered,
• an empty data value, either in the query or record data, is encountered and the Fail Empty Predicate flag is true,
• a conversion is requested on data that can't be converted to the requested type,
• other rare conditions may cause a failure.

If this flag is true a failed predicate is treated as a false value, i.e. the record is not returned. If this value is false a failed predicate is treated as true, i.e. the test is considered to have passed even if other clauses in the test returned false.

For example: ( $"count" < 10 ) and ( DATE $"issue-date" > DATE "10/10/2010" ) If the value of issue-date is "notadate", causing the conversion to fail, and the Fail Invalid Predicate flag is set to false, the test returns true even if count is less than 10.

This flag should be set to false only after careful consideration.

The default value is true.

Parameters:

fail - new value for the flag.

setSortLookupFields

public void setSortLookupFields(java.lang.String[] fields)

You should only use this method with the help of your TIBCO technical support representative.

As the sortfilter is predominantly used in a record linking scenario, a query of the sortfilter is expected to contain the same structure as the fields of the table, Therefore, the number and structure of fields in this array must be the same as that for the table.

Parameters:

fields - array of new values for lookup-fields.

setPsiLookupFields

public void setPsiLookupFields(java.lang.String[] fields)

You should only use this method with the help of your TIBCO technical support representative.

As the PSI filter is predominantly used in a record linking scenario, a query of the PSI filter is expected to contain the same structure as the fields of the table, Therefore, the number and structure of fields in this array must be the same as that for the table.

Parameters:

fields - array of new values for lookup-fields.

setPsiDensity

public void setPsiDensity(int density)

Set the density of suffixes produced from query field values. It is recommended that you contact your TIBCO representative for advice before using this option.

Parameters:

density - One of NetricsTable.PSI_DENSITY_DENSE, NetricsTable.PSI_DENSITY_STANDARD, NetricsTable.PSI_DENSITY_SPARSE. DENSE: Queries will run more slowly but may achieve higher accuracy. SPARSE: Queries will run more quickly but may suffer in accuracy.

setRlModelName

public void setRlModelName(java.lang.String name)

You should only use this method with the help of your TIBCO technical support representative.

This method specifies the rlink model name to use for this search.

When you are using a decision engine model, you must use the same query structure that was used to create it. For instance, if there were five features used to train the model, five features which represent the same meaning must still be used. In the simplest case, a five featured model will translate to five querylets. The user would simply call AddQuery five times with the appropriate fields, the querylet scores would automatically be used as feature scores, and the user would receive a decision engine score in the NetricsSearchResult objects (see getRlScore). If more complicated features were used in the construction of the model, they should also be used when querying the model.

Parameters:

name - an RLink model name.

See Also:

NetricsSearchResult.getRlScore()

setDetailedStats

public void setDetailedStats(boolean enabled)

Enable detailed statistics for this search. Detailed statistics will return information which can be used by your TIBCO representative, but should be off by default as it will decrease search performance.

Parameters:

enabled - new value for the detailed-statistics setting.

setSortFiltered

public void setSortFiltered(boolean enabled)

Enable SORT filtering for this table (default). SORT filtering will greatly speed up the performance of the server for large data sets. To use SORT filtering it must be enabled at load time, and setSortLookupFields() must be called.

Parameters:

enabled - new value for the SORT filtering setting.

setPsiFiltered

public void setPsiFiltered(boolean enabled)

Enable PSI filtering for this table (default). PSI filtering will greatly speed up the performance of the server for large data sets. To use PSI filtering it must be enabled at load time, and setPsiLookupFields() must be called.

Parameters:

enabled - new value for the PSI filtering setting.

setGipFiltered

public void setGipFiltered(boolean enabled)

Enable gip filtering for this table (default). Available only if the GIP filter was enabled in the server and the table was loaded with GIP filtering enabled. Gip filtering will greatly speed up the performance of the server for large data sets.

Parameters:

enabled - new value for the GIP filtering setting.

setPhonetic

public void setPhonetic(boolean enabled)

Enable phonetic searches for this table. Phonetics is not currently supported, so this method can only be called with a value of false.

Parameters:

enabled - new value for the phonetic-search setting.

setVisStyle

public void setVisStyle(int styleNo)

Sets the visualization style you want returned. The definition is as follows:
0: no visualization (default)
2: return match strength arrays in the NetricsSearchResults object.
256: return HTML visualization strings.

Parameters:

styleNo - new value for the visualization-style setting.

See Also:

NetricsSearchResult.getCharMatchStrengths(java.lang.String)

setMatchesRequested

public void setMatchesRequested(int matchesRequested)

Set the number of matches returned by the Netrics Server (default 25).

Parameters:

matchesRequested - The number of matches to return

setStartMatch

public void setStartMatch(int startMatch)

Set the rank of the first match to be returned by the Netrics Server (default 1).

For instance, if startMatch is set to 11 and matchesRequested is set to 10, the server will return matches 11 through 20.

Parameters:

startMatch - The rank of the first match.

scoreType

public void scoreType(int scoreType)

This specifies the type of score to be used for ordering records.

This is the same as the scoreType method of the NetricQuery class except it applies to all queries that don't explicitly set their own score type.

Parameters:

scoreType - one of SCORE_xxx.

See Also:

NetricsQuery.scoreType(int)

useAbsoluteCutoff

public void useAbsoluteCutoff(double val)

Cut off the result set at a specific absolute value.

Although picking a hard cutoff is not the recommended usage of the Netrics Matching Engine (as the correct result will sometimes have the best score and yet still have a low score), sometimes the business requirements state that a "no results found" scenario is expected. In this case, using an absolute cutoff can be used to implement this. If one wants to use one of the dynamic cutoffs below, as well as an absolute cutoff, it is best to just postprocess the results to enforce the absolute cutoff.

Parameters:

val - The score at which to cut off returned records.

useExactPlusScoreCutoff

public void useExactPlusScoreCutoff(int val)

Return all search results which are exact matches plus a fixed number of records which are inexact.

Because it is inappropriate to cut off search results at a static score threshold, there are several configurable dynamic methods which can be used.

All cutoffs will use the score type specified in the scoreType property. Only one cutoff may be used at a time. The most recent cutoff specified is the one that will be used.

This cutoff returns all exact matches plus a specified number of records of the highest scoring inexact matches.

Parameters:

val - The number of records to return in addition to the exact matches.

usePercentOfTopCutoff

public void usePercentOfTopCutoff(double val)

Return search results whose scores are above a given percentage of the score of the first record.

This cutoff returns the first match plus all record above a certain percentage of the first match.

For example if the top score is 0.90 and the percent cutoff is 80.0 all records with a score of 0.72 or higher will be returned.

Parameters:

val - The percentage of the first records score for which no records below that score will be returned. (Valid range is from 0.0 to 100.0)

useSimpleGapCutoff

public void useSimpleGapCutoff(double val)

Return search results until there is gap between adjacent records.

This cutoff returns the first match and all records until a gap is found between the scores of consecutive records greater than a certain percentage of the score of the first record.

For example if the top scoring record has a score of 0.90 and there is a gap cut off of 10.0 and the first 5 records have a scores of: 0.90, 0.89, 0.87, 0.76, 0.76 respectively only the first three records will be returned as there is a gap of 0.11 between the 3rd and forth record which is greater than the cutoff gap of 0.90 * 10% or 0.09.

Parameters:

val - The percentage of the first record's score which will be used to look for a gap between the scores of consecutive records below which no records will be returned. (Valid range is from 0.0 to 100.0)

useNoCutoff

public void useNoCutoff()

Revert to not using a cutoff.

This method is used to specify that no cutoff should be used. Although this happens by default, the useNoCutoff method can be useful after a call to one of the above methods.

baseColor

public void baseColor(java.lang.String color)

Specify a non-match color for HTML text.

Because Netrics Intelligent Lookup returns a score per character in the matching record (see NetricsSearchResult.getDblCharMatchStrengths(java.lang.String), the matching characters can be visualized based on the strength of the match at that position. For instance, the color red can be used to signify a strong match and the color blue can be used to signify a weak match. A gradient between the two colors can then be used to show matches of varying strengths.

If you specify any of the following parameters, the visualization process will be done for you, and returned in the form of an HTML string per field in the record. The HTML strings can be accessed using the getHTMLStringByIndex method of the NetricsSearchResult object.

Each of the following parameters is used to customize the appearance of the HTML visualization.

Parameters:

color - All colors are specified as they are in an HTML document. The String should have 6 characters, each of which is a hex value (from 0 to F). The first two characters represent red, the second two represent green, and the last two represent blue. This parameter represents the color used to indicate a weak match.

See Also:

NetricsSearchResult.getDblCharMatchStrengths(java.lang.String)

matchColor

public void matchColor(java.lang.String color)

Specify a match color for HTML text.

Parameters:

color - This parameter represents the color used to indicate a strong match.

baseBgColor

public void baseBgColor(java.lang.String color)

Specify a background non-match color for HTML text.

Parameters:

color - The background color for a match can also be changed to indicate a match. This parameter represents the background color used to indicate a weak match.

matchBgColor

public void matchBgColor(java.lang.String color)

Specify a background match color for HTML text.

Parameters:

color - This parameter represents the background color used to indicate a strong match.

maxFontSize

public void maxFontSize(int val)

Specify the maximum font size of matching text.

Parameters:

val - This parameter represents the HTML font size to use for strong matches (ranges from 0 to 3).

italicsThresh

public void italicsThresh(int val)

Specify the threshold beyond which to italicize text.

Character scores are divided into 6 evenly spaced ranges over the entire range of 0.0 to 1.0. The integers 0 (0.0 score) through 6 (0.83 - 1.0) are used to select a range.

Parameters:

val - characters with scores of this range or higher (to the next defined range) are italicized.

boldThresh

public void boldThresh(int val)

Specify the threshold beyond which to bold text.

Character scores are divided into 6 evenly spaced ranges over the entire range of 0.0 to 1.0. The integers 0 (0.0 score) through 6 (0.83 - 1.0) are used to select a range.

Parameters:

val - characters with scores of this range or higher (to the next defined range) are in bold text.

underlineThresh

public void underlineThresh(int val)

Specify the threshold beyond which to underline text.

Character scores are divided into 6 evenly spaced ranges over the entire range of 0.0 to 1.0. The integers 0 (0.0 score) through 6 (0.83 - 1.0) are used to select a range.

Parameters:

val - characters with scores of this range or higher (to the next defined range) are underlined.

useWeightedDictionary

public void useWeightedDictionary(java.lang.String name)

Use the specified weighted dictionary in determining matching records.

Only one thesaurus or weighted dictionary can be used at a time.

Parameters:

name - Specifies which weighted dictionary to use for the query. The string should be the name of the dictionary as passed to the wdcreate method of the NetricsServerInterface object.

See Also:

NetricsServerInterface.wdcreate(com.netrics.likeit.NetricsWeightedDictionary)

useThesaurus

public void useThesaurus(java.lang.String name)

Use the specified thesaurus or combined thesaurus in determining matching records.

Only one thesaurus or weighted dictionary can be used at a time.

Parameters:

name - Specifies which thesaurus or combined thesaurus to use for the query. The string should be the name of the thesaurus as passed to the thcreate or cthcreate methods of the NetricsServerInterface object.

See Also:

NetricsServerInterface.thcreate(com.netrics.likeit.NetricsThesaurus), NetricsServerInterface.cthcreate(com.netrics.likeit.NetricsCombinedThesaurus)

useEphemeralThesaurus

public void useEphemeralThesaurus(com.netrics.likeit.NetricsBaseThesaurus thes_def)

Use an ephemeral thesaurus in determining matching records.

An ephemeral thesaurus is one that exists only for the duration of this query and is accessible only by this query. The thesaurus name, although required for consistency, is not used. Thus ephemeral thesauri may have the same name as a permanent thesaurus or another ephemeral thesaurus without causing interference.

Ephemeral thesauri are intended for those cases where possible substitutions or weighted terms for a query are generated dynamically based on the query and is not a fixed set of substitutions or weightings that can be encoded into a static thesaurus.

Parameters:

thes_def - A Thesaurus object (any extension of NetricsBaseThesaurus).

See Also:

NetricsThesaurus, NetricsWeightedDictionary, NetricsCombinedThesaurus

setThesaurusWeight

public void setThesaurusWeight(double weight)

Use the specified thesaurus weight in determining matching records.

Parameters:

weight - Specifies a thesaurus weight to use for the query (from 0.0 to 1.0). A weight of 1.0 means that the score associated with a matching thesaurus word will be exactly equivalent to the score which matches the query as entered. If a weight less than 1.0 is given, then the score of records matched based on thesaurus substitutions will be decreased.

See Also:

NetricsServerInterface.thcreate(com.netrics.likeit.NetricsThesaurus)

addCustomTiebreak

public void addCustomTiebreak(int tiebreakId,
                              int tiebreakParam)

Can be used to specify how to break ties between two records that have identical textual similarity. Each tiebreaking option has integer identifier and a possible integer parameter (most ignore the parameter).

Tiebreak Values and Descriptions:

.

Tiebreak Id	Description	Parameter
NetricsSearchOpts.TIEBREAK_RECLEN	Deprecated. This is identical to TIBREAK_SCORETYPE on Symmetric score.	ignored
NetricsSearchOpts.TIEBREAK_RECID	By record key - this can be used to guarantee a stable sort of tied records	ignored
NetricsSearchOpts.TIEBREAK_ALIGNMENT	By query alignment - records which the query matches closer to the beginning will come first. Can not be used with query expressions.	ingored
NetricsSearchOpts.TIEBREAK_SCORETYPE	By scoretype - you can tiebreak by a different scoretype than you're sorting on	The scoretype - described in NetricsSearchOpts.sortScore
NetricsSearchOpts.TIEBREAK_FIELDVAL	By field value - text fields will rank lesser values higher (alphabetically), other field types will rank higher field values higher	The integer value of the field number to use (zero based)

Any number of tiebreaks may be added. The first tiebreak added will be the primary sort, the second will be the secondary sort, and so on (e.g. if the records are still tied after the first tiebreak, the second will then be used).

Parameters:

tiebreakId - One of the Ids specified in the table above.

tiebreakParam - An int parameter which is explained in the table above.

setXparm

public void setXparm(int id,
                     int value)
              throws NetricsException

Use this method only on the advice of your TIBCO representative.

Parameters:

id - identifies the expert parameter.

value - value for the expert parameter.

Throws:

NetricsException - never. This exception specification is left in for backwards-compatibility.

setXparm

public void setXparm(int id,
                     double value)
              throws NetricsException

Use this method only on the advice of your TIBCO representative.

Parameters:

id - identifies the expert parameter.

value - value for the expert parameter.

Throws:

NetricsException - never. This exception specification is left in for backwards-compatibility.