Home > Class Reference > %SYS namespace > %iFind.Rank.Abstract

%iFind.Rank.Abstract

This is the abstract superclass for all ranking algorithm implementations. In order to provide a rank or score for one or more records, an instance of this class is created and initialized with the search string and options. As part of this initialization, the search string will be parsed in the same way as it's done for the search operation itself and the resulting search tree is stored in the ParsedQuery.
Implementation-specific setup can be carried out by overriding the OnInitialize() method, for example to prepare term weights and other reusable metrics that are common for all per-record calculations.
Then, the GetRecordScore() method is invoked for every record, first invoking its OnBeforeGetRecordScore() and then traversing the search tree's nodes one by one through calls to GetNodeScore(), skipping the ones that are exclusion criteria (NOT). For each leaf node, GetLeafScore() is invoked to obtain a score expressing how well that record matches that leaf node's search string.
These scores are then aggregated by taking the minimum value when nodes are ANDed and the maximum value when nodes are ORed, producing an overall score for the record, which can finally be amended through the OnGetRecordScore() callback.

Subclasses should typically only override / implement the GetLeafScore() and do any preparation or cleanup in the callback methods.

Property Inventory (Including Private)

Method Inventory (Including Private)

Parameters

parameter OPERATORLOGICAND = MIN;

Defines how weight scores of different subnodes of an AND node in the search tree are combined by the GetNodeScore() method to provide an aggregated weight for the total. See OPERATORLOGICOR for a list of options.

parameter OPERATORLOGICOR = MAX;

Defines how weight scores of different subnodes of an OR node in the search tree are combined by the GetNodeScore() method to provide an aggregated weight for the total. The different values are:

  • MAX: the highest weight of any sub-node is used as the weight of this composite node
  • MIN: the smallest weight of any sub-node is used as the weight of this composite node
  • SUM: the sum of all sub-node's weights is used as the weight of this composite node
  • AVG: the average of all sub-node's weights is used as the weight of this composite node

Properties (Including Private)

property ClassName as %String [ Final , ReadOnly ];
Name of the class based on which' index records should be ranked
Property methods: ClassNameDisplayToLogical(), ClassNameGet(), ClassNameIsValid(), ClassNameLogicalToDisplay(), ClassNameLogicalToOdbc(), ClassNameNormalize()
property IndexName as %String [ Final , ReadOnly ];
The index based on which records should be ranked
Property methods: IndexNameDisplayToLogical(), IndexNameGet(), IndexNameIsValid(), IndexNameLogicalToDisplay(), IndexNameLogicalToOdbc(), IndexNameNormalize()
property IndexParams [ MultiDimensional ];
An array containing all the index parameters of IndexName
Property methods: IndexParamsDisplayToLogical(), IndexParamsGet(), IndexParamsIsValid(), IndexParamsLogicalToDisplay(), IndexParamsLogicalToOdbc(), IndexParamsNormalize(), IndexParamsSet()
property IndexType as %String [ Final , ReadOnly ];
The index class of IndexName
Property methods: IndexTypeDisplayToLogical(), IndexTypeGet(), IndexTypeIsValid(), IndexTypeLogicalToDisplay(), IndexTypeLogicalToOdbc(), IndexTypeNormalize()
property ParsedQuery [ MultiDimensional ];
The entire parsed query tree.
ParsedQuery([node ID], "o") = [operator: A|O|N]
ParsedQuery([node ID], "p") = [parent node ID]
ParsedQuery([node ID], "ch", [child node ID]) = [child node is negated]
ParsedQuery([node ID], "s") = n
ParsedQuery([node ID], "s", [leaf ID]) = [atomic string]
ParsedQuery([node ID], "s", [leaf ID], "n") = [atomic string is negated]
ParsedQuery([node ID], "s", [leaf ID], 1) = [left operator]
ParsedQuery([node ID], "s", [leaf ID], 2) = [right operator]
Property methods: ParsedQueryDisplayToLogical(), ParsedQueryGet(), ParsedQueryIsValid(), ParsedQueryLogicalToDisplay(), ParsedQueryLogicalToOdbc(), ParsedQueryNormalize(), ParsedQuerySet()
property SearchArgs as %String [ Final , ReadOnly ];
Any additional search option arguments the ranker was initialized with. For example, when SearchOption = $$$IFSEARCHFUZZY, this property may contain the requested maximum edit distance.
Property methods: SearchArgsDisplayToLogical(), SearchArgsGet(), SearchArgsIsValid(), SearchArgsLogicalToDisplay(), SearchArgsLogicalToOdbc(), SearchArgsNormalize()
property SearchOption as %Integer [ Final , ReadOnly ];
The primary search option this ranker is initialized with (defaults to $$$IFSEARCHNORMAL)
Property methods: SearchOptionDisplayToLogical(), SearchOptionGet(), SearchOptionIsValid(), SearchOptionLogicalToDisplay(), SearchOptionNormalize()
property SearchString as %String [ Final , ReadOnly ];
The full search string this ranker was initialized with.
Property methods: SearchStringDisplayToLogical(), SearchStringGet(), SearchStringIsValid(), SearchStringLogicalToDisplay(), SearchStringLogicalToOdbc(), SearchStringNormalize()
property option as %String [ Private ];
search option supplied to %FIND call
Property methods: optionDisplayToLogical(), optionGet(), optionIsValid(), optionLogicalToDisplay(), optionLogicalToOdbc(), optionNormalize(), optionSet()

Methods (Including Private)

private method GetIntegerRecordId(pRecordId As %RawString) as %Integer [ Language = objectscript ]
For classes where the INTKEYPROPERTY index parameter is set, this utility method retrieves the integer version of the IDKEY used internally.
private method GetLeafScore(pRecordId As %RawString, pNode As %Integer, pLeaf As %Integer, Output pSC As %Status) as %Float [ Language = objectscript ]

This method should be implemented by subclasses and return the score expressing how well record pRecordId matches the atomic search string for leaf sub-node pLeaf of node pNode, which can be retrieved from ParsedQuery.

private method GetNodeScore(pRecordId As %RawString, pNode As %Integer, pNegated As %Boolean = 0, Output pSC As %Status) as %Float [ Language = objectscript ]

This method will aggregate the score for one particular search tree node by looping over its sub-nodes (leaf or composite) in ParsedQuery and combining the results according to the values of OPERATORLOGICOR and OPERATORLOGICAND, which by default means by taking the minimum if this node carries an AND operator or the maximum if it has an OR operator.

For leaf sub-nodes, this method will call GetLeafScore() to obtain the score for an atomic search string. For composite sub-nodes, this method will invoke itself recursively.

This method should typically not be overriden by subclasses, as relevant behavior can be controlled through the OPERATORLOGICOR and OPERATORLOGICAND. parameters.
Leaf nodes which end up with a NOT context, either directly or inherited from parent nodes, will be skipped.

final method GetRecordScore(pRecordId As %RawString, Output pSC As %Status) as %Float [ Language = objectscript ]

This method calculates the overall score for the given search string for one specific record by invoking GetNodeScore() on the top-level node of the parsed search string. The resulting score can still be amended by OnGetRecordScore(), order dto apply any record-level modifiers.

This method will also invoke the callback methods OnBeforeGetRecordScore() and OnAfterGetRecordScore(), which can be used to retrieve and clean up any record- related information required for the GetLeafScore() implementation.

OnBeforeGetRecordScore() implemenations may return a skip flag, instructing this code to skip the calls to GetNodeScore() for this record.

final method Initialize(pClassName As %String, pIndexName As %String, pSearchString As %String, pSearchOptions As %String = $$$IFSEARCHNORMAL) as %Status [ Language = objectscript ]
This method initializes this ranker object for the given task, retrieving index metadata and parsing the search string
private method OnAfterGetRecordScore(pRecordId As %RawString) [ Language = objectscript ]
Callback method to clean up anything set during the calculations for this record.
private method OnBeforeGetRecordScore(pRecordId As %RawString, Output pSkip As %Boolean = 0) as %Status [ Language = objectscript ]
Callback method to do any relevant lookups specific to this record, before any calls to GetLeafScore(). If the value returned by pSkip is 1, the calls to GetNodeScore() are skipped and only OnAfterGetRecordScore() is invoked to yield a score for this record.
private method OnGetRecordScore(pRecordId As %RawString, pRecordScore As %Float, Output pSC As %Status) as %Float [ Language = objectscript ]
Callback method to optionally amend the total score for record pRecordId returned by the aggregated result of GetLeafScore() invocations. By default, it will just return pRecordScore.
private method OnInitialize() as %Status [ Language = objectscript ]
This callback method performs additional initialization activities, such as retrieving global IDF scores for the search terms. This method is specific to the Ranker implementation

Inherited Members

Inherited Methods (Including Private)