Ranking Expressions

This is a complete reference to the ranking expressions used to configure application specific ranking functions. For an overview of how to use ranking expressions, see the ranking overview.

Ranking expressions are written in a simple language similar to ordinary functional notation. The atoms in ranking expressions are rank features and constants. These atoms can be combined by arithmetic operations and built-in functions.

Rank Features A rank feature is a named value calculated or looked up by vespa for each query/document combination. See the rank feature reference for a list of all the rank features available to ranking expressions.
Constants A constant is either a floating point number, or a quoted string. Strings are only useful for equality comparison in the if function.

Arithmetic operations

The four basic operations, addition, subtraction, multiplication and division are expressed in in-fix notation:

a + b - c * d / (e + f)
Multiplication and division has higher precedence than addition and subtraction. Terms can be ordered using parentheses when it is necessary to override default precedence.

Built-in Functions

The built-in functions is the usual mathematical set, as well as a special if function useful to create non-linear functions like decision trees.

Mathematical Functions

cosh(x) Hyperbolic cosine of x
sinh(x) Hyperbolic sine of x
tanh(x) Hyperbolic tangent of x
cos(x) Cosine of x
sin(x) Sine of x
tan(x) Tangent of x
acos(x) Inverse cosine of x
asin(x) Inverse sine of x
atan2(y, x) Inverse tangent of y / x, using signs of both arguments to determine correct quadrant.
atan(x) Inverse tangent of x
exp(x) Base-e exponential function.
ldexp(x, exp) Multiply x by 2 to the power of exp
log10(x) Base-10 logarithm of x
log(x) Base-e logarithm of x
pow(x, y) Return x raised to the power of y
sqrt(x) Square root of x
ceil(x) Lowest integral value not less than x
fabs(x) Absolute value of (floating-point) number x
floor(x) Largest integral value not greater than x
isNan(x) Returns 1.0 if x is NaN, 0.0 otherwise
fmod(x, y) Remainder of x / y
min(x, y) Smaller of x and y
max(x, y) Larger of x and y

x and y may be any ranking expression.

The if Function

The if function chooses between two sub-expressions based on the truth value of a condition.

if (expression1 operator expression2, trueExpression, falseExpression)
If the condition given in the first argument is true, the expression in argument 2 is used, otherwise argument 3. The four expressions may be any ranking expression. Conditional operators in ranking expression if functions:

<= Less than or equal
< Less than
== Equal
~= Approximately equal
>= Greater than or equal
> Greater than

The in membership operator uses a slightly modified if-syntax:

if (expression1 in [expression2, expression3, ..., expressionN], trueExpression, falseExpression)
If expression1 is equal to either of expression1 through expressionN, then trueExpression is used, otherwise falseExpresion.

The foreach Function

The foreach function is not really part of the expression language but implemented as a rank feature.


If the user is underage, assign 0 to adult content and use the average of match quality in the title field and popularity among kids. If the user is not, use the match quality in the title field:

if ( query(userage) < 18,
     if ( attribute(adultness) > 0.1, 0 , (fieldMatch(title)+attribute(kidspopularity)) / 2 ),
     fieldMatch(title) )

Use a weighted average of the match quality in some fields, multiplied by 1-exp of the document age:
( 10*fieldMatch(title) + 5*fieldMatch(description) +
  7*attributeMatch(tags).normalizedWeight ) /22 * ( 1 - age(creationtime) )