Ranking Expressions

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.

A constant is either a floating point number, a boolean (true/false) or a quoted string. Since ranking expressions can only work on scalars and tensors, strings and booleans are immediately converted to scalars - true becomes 1.0, false 0.0 and a string its hash value. This means that strings can only be used for equality comparisons, other purposes such as parametrizing the key to slice out of a tensor will not work correctly.

Inverse cosine of x

Inverse sine of x

Inverse tangent of x

Inverse tangent of y / x, using signs of both arguments to determine correct quadrant.

Returns value of bit y in value x (for int8 values)

Lowest integral value not less than x

Cosine of x

Hyperbolic cosine of x

The Exponential Linear Unit activation function for value x

The Gauss error function for value x

Base-e exponential function.

Absolute value of (floating-point) number x

Largest integral value not greater than x

Remainder of x / y

Returns 1.0 if x is NaN, 0.0 otherwise

Multiply x by 2 to the power of exp

Base-e logarithm of x

Base-10 logarithm of x

Larger of x and y

Smaller of x and y

Return x raised to the power of y

The Rectified Linear Unit activation function for value x

The sigmoid (logistic) activation function for value x

Sine of x

Hyperbolic sine of x

Square root of x

Tangent of x

Hyperbolic tangent of x

Hamming (bit-wise) distance between x and y (considered as 8-bit integers).

Returns a new tensor with the lambda function defined in f(x)(expr) applied to each cell.

Arguments:

• tensor: a tensor expression. For example attribute(tensor_field)
• f(x)(expr): a lambda function with one argument.

map(t, f(x)(x*x))

Returns a new tensor with the lambda function defined in f(x)(expr) applied to each dense subspace.

Arguments:

• tensor: a tensor expression. For example attribute(tensor_field)
• f(x)(expr): a lambda function with one argument.

map_subspaces(tensor(x{},y[3]):{a:[1,2,3]},f(d)(tensor(z[2])(d{y:(z)}+d{y:(z+1)})))

Returns a new tensor containing only the subspaces for which the lambda function defined in f(x)(expr) returns true.

Arguments:

• tensor: a tensor expression. Must have at least one mapped dimension.
• f(x)(expr): a lambda function with one argument.

filter_subspaces(tensor(x{}):{a:1,b:2,c:3,d:4},f(value)(value>2)) # tensor(x{}):{c:3,d:4}

Returns a new tensor with the aggregator applied across dimensions dim1, dim2, etc. If no dimensions are specified, reduce over all dimensions.

Arguments:

• tensor: a tensor expression.
• aggregator: the aggregator to use. See below.
• dim1, dim2, ...: the dimensions to reduce over. Optional.

Returns a new tensor with the aggregator applied across dimensions dim1, dim2, etc. If no dimensions are specified, reduce over all dimensions.

Available aggregators are:

• avg: arithmetic mean
• count: number of elements
• max: maximum value
• median: median value
• min: minimum value
• prod: product of all values
• sum: sum of all values

reduce(t, sum)         # Sum all values in tensor
reduce(t, count, x)    # Count number of cells along dimension x

Returns a new tensor constructed from the natural join between tensor1 and tensor2, with the resulting cells having the value as calculated from f(x,y)(expr), where x is the cell value from tensor1 and y from tensor2.

Arguments:

• tensor1: a tensor expression.
• tensor2: a tensor expression.
• f(x,y)(expr): a lambda function with two arguments.

Returns a new tensor constructed from the natural join between tensor1 and tensor2, with the resulting cells having the value as calculated from f(x,y)(expr), where x is the cell value from tensor1 and y from tensor2.

Formally, the result of the join is a new tensor with dimensions the union of dimension between tensor1 and tensor2. The cells are the set of all combinations of cells that have equal values on their common dimensions.

Examples:

join(t1, t2, f(x,y)(x * y))

Returns a new tensor consisting of all cells from both the arguments, where the lambda function is used to produce a single value in the cases where both arguments provide a value for a cell.

Arguments:

• tensor1: a tensor expression.
• tensor2: a tensor expression.
• f(x,y)(expr): a lambda function with two arguments.

Returns a new tensor having all the cells of both arguments, where the lambda is invoked to produce a single value only when both arguments have a value for the same cell.

The argument tensors must have the same type, and that will be the type of the resulting tensor. Example:

merge(t1, t2, f(left,right)(right))

Generates new tensors according to type specification and expression expr.

Arguments:

• tensor-type-spec: an indexed tensor type specification.
• (expression): a lambda function expressing how to generate the tensor.

Generates new tensors according to the type specification and expression expr. The tensor type must be an indexed tensor (e.g. tensor<float>(x[10])). The expression in expr will be evaluated for each cell. The arguments in the expression is implicitly the names of the dimensions defined in the type spec.

Useful for creating transformation tensors. Examples:

tensor<float>(x[3])(x)

Renames one or more dimensions in the tensor.

Arguments:

• tensor: a tensor expression.
• dim-to-rename: a dimension, or list of dimensions, to rename.
• new-names: new names for the dimensions listed above.

rename(t1,x,z)

Concatenates two tensors along dimension dim.

Arguments:

• tensor1: a tensor expression.
• tensor2: a tensor expression.
• dim: the dimension to concatenate along.

concat(t,t2,x)

Slice - returns a new tensor containing the cells matching the partial address.

Arguments:

• tensor: a tensor expression.
• partial-address: Can be given in the form of a tensor address {dimension:label,..}, or for tensors referenced directly and having a single mapped or indexed type respectively as just a label in curly brackets {label} or just an index in square brackets, [index]. Index labels may be specified by a lambda expression enclosed in parentheses.

# a_tensor is of type tensor(key{},x[2])
a_tensor{key:key1,x:1}

Returns a new tensor having the type and cell values given explicitly. Each cell value may be supplied by a lambda which can access other features.

Returns a new tensor from the literal form, where the type must be specified explicitly. Each value may be supplied by a lambda, which - in contrast to all other lambdas - may refer to features and expressions from the context. Examples:

# Declare an indexed tensor
tensor(x[2]):[1.0, 2.0]

# Declare an mapped tensor
tensor(x{}):{x1:3, x2:4}

Returns a new tensor that is the same as the argument, except that all cell values are converted to the given cell type.

Arguments:

• tensor: a tensor expression.
• cell_type: wanted cell type.

# With a tensor t of the type tensor<bfloat16>(x[5])(x+1)
cell_cast(t, float)

Returns a new tensor with the rank of the original cells based on the given order.

Arguments:

• tensor: a tensor expression.
• order: max or min

cell_order(tensor(x[3]):[2,3,1],max) # tensor(x[3]):[1,0,2]
cell_order(tensor(x[3]):[2,3,1],min) # tensor(x[3]):[1,2,0]

join(t, reduce(t, max, dim), f(x,y)(if (x == y, 1, 0)))

Returns a tensor with cell(s) of the highest value(s) in the tensor set to 1. The dimension argument follows the same format as reduce as multiple dimensions can be given and is optional.

join(t, reduce(t, min, dim), f(x,y)(if (x == y, 1, 0)))

Returns a tensor with cell(s) of the lowest value(s) in the tensor set to 1. The dimension argument follows the same format as reduce as multiple dimensions can be given and is optional.

reduce(t, avg, dim)

Reduce the tensor with the average aggregator along dimension dim. If the dimension argument is omitted, this reduces over all dimensions.

reduce(t, count, dim)

Reduce the tensor with the count aggregator along dimension dim. If the dimension argument is omitted, this reduces over all dimensions.

reduce(t1*t2, sum, dim) / sqrt(reduce(t1*t1, sum, dim) * reduce(t2*t2, sum, dim))

The cosine similarity between the two vectors in the given dimension.

tensor(i[n1],j[n2])(if (i==j, 1.0, 0.0)))

Returns a tensor with the diagonal set to 1.0.

map(t, f(x)(if(x < 0, exp(x)-1, x)))

Exponential linear unit.

join(reduce(map(join(t1, t2, f(x,y)(x-y)), f(x)(x * x)), sum, dim), f(x)(sqrt(x)))

euclidean_distance: sqrt(sum((t1-t2)^2, dim)).

t * tensor(dim[1])(1)

Adds an indexed dimension with name dim to the tensor t.

join(t1, t2, f(x,y)(hamming(x,y)))

Join and return the Hamming distance between matching cells of t1 and t2. This function is mostly useful when the input contains vectors with binary data and summing the hamming distance over the vector dimension, e.g.:

Note that the cell values are always treated as if they were both 8-bit integers in the range [-128,127], and only then counting the number of bits that are different. See also the corresponding distance metric. Arguments can be scalars.

join(t, reduce(t, sum, dim), f(x,y) (x / y))

L1 normalization: t / sum(t, dim).

join(t, map(reduce(map(t, f(x)(x * x)), sum, dim), f(x)(sqrt(x))), f(x,y)(x / y))

L2 normalization: t / sqrt(sum(t^2, dim).

reduce(join(t1, t2, f(x,y)(x * y)), sum, dim)

Matrix multiplication of two tensors. This is the product of the two tensors summed along a shared dimension.

reduce(t, max, dim)

Reduce the tensor with the max aggregator along dimension dim.

reduce(t, median, dim)

Reduce the tensor with the median aggregator along dimension dim. If the dimension argument is omitted, this reduces over all dimensions.

reduce(t, min, dim)

Reduce the tensor with the min aggregator along dimension dim.

reduce(t, prod, dim)

Reduce the tensor with the product aggregator along dimension dim. If the dimension argument is omitted, this reduces over all dimensions.

tensor(i1[n1],i2[n2],...)(random(1.0))

Returns a tensor with random values between 0.0 and 1.0, uniform distribution.

tensor(i[n])(i)

Returns a tensor with increasing values.

map(t, f(x)(max(0,x)))

Rectified linear unit.

map(t, f(x)(1.0 / (1.0 + exp(0.0-x))))

Returns the sigmoid of each element.

join(map(t, f(x)(exp(x))), reduce(map(t, f(x)(exp(x))), sum, dim), f(x,y)(x / y))

The softmax of the tensor, e.g. e^x / sum(e^x).

reduce(t, sum, dim)

Reduce the tensor with the summation aggregator along dimension dim. If the dimension argument is omitted, this reduces over all dimensions.

t * filter_subspaces(cell_order(t, max) < n, f(s)(s))

top N function: Picks top N cells in a simple mapped tensor.

unpacks bits from int8 input to 8 times as many floats

The innermost indexed dimension will expand to have 8 times as many cells, each with a float value of either 0.0 or 1.0 determined by one bit in the 8-bit input value. Comparable to numpy.unpackbits which gives the same basic functionality. A minimal input such as tensor<int8>(x[1]):[9] would give output tensor<float>(x[8]):[0,0,0,0,1,0,0,1] (default bit-order is big-endian). As a very complex example, an input with type tensor<int8>(foo{},x[3],y[11],z{}) will produce output with type tensor<float>(foo{},x[3],y[88],z{}) where "foo", "x" and "z" are unchanged, as "y" is the innermost indexed dimension.

unpacks bits from int8 input to 8 times as many values

Same as above, but with optionally different cell_type (could be double for example, if you will combine the output with other tensors using double).

unpacks bits from int8 input to 8 times as many values

Same as above, but also optionally different endian for the bits; must be either big (default) or little.

join(reduce(join(x, w, f(x,y)(x * y)), sum, dim), b, f(x,y)(x+y))

Matrix multiplication of x (usually a vector) and w (weights), with b added (bias). A typical operation for activations in a neural network layer, e.g. sigmoid(xw_plus_b(x,w,b))).