DEFINESCORE

Use the DEFINESCORE operator to define how a term or phrase, or a set of term equivalences will be scored. The definition of a scoring expression can consist of an arithmetic expression of predefined scoring components and numeric literals. DEFINEMERGE can be used after DEFINESCORE.

Syntax

DEFINESCORE (query_term, scoring_expression)

query_term

The query term or phrase. Expressions containing the following operators are also allowed:

Operators	Operators
ABOUT	EQUIV(=)
Fuzzy	Soundex (!)
Stem ($)	Wildcards (% _)
SDATA	MDATA

scoring_expression

An arithmetic expression that describes how the query_term should be scored. This operand is a string that contains the following components:

• Arithmetic operators: + - * /. The precedence is multiplication and division (*, /) first before addition and subtraction (+, -).

• Grouping operators: (). Parentheses can be used to alter the precedence of the arithmetic operators.

• Absolute function: ABS(n) returns the absolute value of n; where n is any expression that returns a number.

• Logarithmic function: LOG(n) returns the base-10 logarithmic value of n ; where n is any expression that returns a number.

• Predefined scoring components: Each of the following scoring components returns a value of 0 - 100, depending on different criteria:

  Name	Description
  DISCRETE	If the term exists in the document, score =
  100. Otherwise, score = 0.
  OCCURRENCE	Score based on the number of occurrences.
  RELEVANCE	Score based on the document’s relevance.
  COMPLETION	Score based on coverage. Documents will score higher if the ratio between the number of the matching terms and the number of all terms in the section (counting stop words) is higher. The COMPLETION scoring is only applicable when used with the WITHIN operator to search in zone sections.
  IGNORE	Ignore the scoring of this term. This component should be used alone. Otherwise, the query will return a syntax error. If the scoring of the only term in the query is set to IGNORE, then all the matching documents should be returned with the same score of 100.

  Note: For numeric literals, any number literal can be used that conforms to the SQL pattern of number literal, and is within the range of the double precision floating point (-3.4e38 to 3.4e38).

scoring_expression Syntax

<Exp>   :=         <Exp> + <Term> | <Exp> - <Term> |  <Term>

<Term>   :=         <Term> * <Factor> | <Term> / <Factor> | <Factor>

<Factor> :=         <<NumericLiterals >>| DISCRETE | OCCURRENCE | RELEVANCE |
         COMPLETION | IGNORE |  ( <Exp> ) | -<Factor> | Abs(<Exp>) | Log(<Exp>)

Examples for DEFINESCORE Operator

'DEFINESCORE (dog, OCCURRENCE)'

Queries for the word dog, and scores each document using the occurrence score. Returns the score as integer.

'DEFINESCORE (Labradors are big dog, RELEVANCE)'

Queries for the phrase Labradors are big dogs, and scores each document using the relevance score.

'cat and DEFINESCORE (dog, IGNORE)'

Queries for the words dog and cat, using only the default relevance score of cat as the overall score of the document. Returns the score as integer.

'DEFINESCORE (dog, IGNORE)'

Queries for the word dog, and returns all documents with the word dog. The result is the same as if all documents get a score of 100. Returns the score as integer.

'DEFINESCORE (dog, ABS (100-RELEVANCE))'

Queries for the word dog, and scores each document using the absolute value of 100 minus the relevance score. Returns the score as integer.

'cat and DEFINESCORE (dog, RELEVANCE*5 - OCCURRENCE)'

Returns a syntax error: Two predefined components are used.

When DEFINESCORE is used with query templates, the scoring_expression overrides the values specified by the template. The following example queries for “dog” and “cat,” scores “cat” using OCCURRENCE(COUNT) and scores “dog” based on RELEVANCE.

<query>
      <textquery grammar="CONTEXT" lang="english">
                 DEFINESCORE(dog, RELEVANCE) and  cat
      </textquery>
      <score datatype="INTEGER" algorithm="COUNT"/>
</query>

Limitations

• If the ABOUT operator is used in query_term, the OCCURRENCE and COMPLETION scoring will not be applicable. If used, the query will return a syntax error.

• The IGNORE score cannot be used as right hand of the minus operator. If used, then a syntax error will occur.

• The COMPLETION score is only applicable if the DEFINESCORE is used with a WITHIN operator to search in zone sections, for example:

'DEFINESCORE (dog, COMPLETION) within zonesection'

otherwise, the query will return a syntax error.

• For the left hand operand of WITHIN:

  • All nodes must use the same predefined-scoring component. (If not specified, then the predefined scoring is RELEVANCE.)

  • If the nodes use DISCRETE or COMPLETION, then only the AND and OR operator is allowed as the left hand children of WITHIN.

  • If the nodes use DISCRETE or COMPLETION, then WITHIN will use the max score of all section instances as the score.

  • If the nodes use RELEVANCE or OCCURRENCE, then WITHIN will use the summation of the score of all section instances as the score.

• Only one predefined scoring component can be used in the scoring_expression at one time. If more than one predefined scoring component is used, then a syntax error will occur.

See Also: Oracle Database SQL Language Reference

Notes

• The DEFINESCORE operator, the absolute function, the logarithmic function, and the predefined scoring components are case-insensitive.

• The query_term and the scoring_expression parameters are mandatory.

• The final score of the DEFINESCORE operator will be truncated to be in the 0 – 100 range. If the data type is INTEGER, then the score is rounded up.

• The intermediate data type of the scoring value is a double precision float. As a result, the value is limited to be in the -3.4e38 to 3.4e38 range. If the intermediate scoring of any document exceeds the value, then the score will be truncated. If an integer scoring is required, then the score will always be rounded up after the score is calculated.

• The DEFINESCORE operator can be used as an operand of the following operators:

  • AND

  • NOT

  • INPATH

  • THRESHOLD

  • WITHIN

  • SQE

  • OR

  • DEFINEMERGE

  • MINUS

  • WEIGHT

  • ACCUM

  For example, the following statement is valid:

DEFINESCORE('dog', OCCURRENCE) AND DEFINESCORE('cat', RELEVANCE)

Queries for the term “dog” using occurrence scoring, and the term “cat” using relevance scoring.

• If DEFINESCORE is used as a parameter of other operators, then an error will be returned. For example, the following example returns an error:

SYN(DEFINESCORE('cat', OCCURRENCE))

• When used with query templates, the scoring_expression overrides the values specified by the template. For example,

<query>
    <textquery grammar="CONTEXT" lang="english">
        DEFINESCORE(dog, RELEVANCE) and  cat
    </textquery>
    <score datatype="INTEGER" algorithm="COUNT"/>
</query>

Queries for “dog” and “cat”, scores “cat” using OCCURRENCE(COUNT), and scores “dog” based on RELEVANCE.

Related Topic

DEFINEMERGE.