Package com.yahoo.searchlib.rankingexpression

Class RankingExpression

java.lang.Object

com.yahoo.searchlib.rankingexpression.RankingExpression

All Implemented Interfaces:

Serializable

public class RankingExpression
extends Object
implements Serializable

A ranking expression. Ranking expressions are used to calculate a rank score for a searched instance from a set of rank features.

A ranking expression wraps a expression node tree and may also optionally have a name.

The identity of a ranking expression is decided by both its name and expression tree. Two expressions which looks the same in string form are the same.

Simple usage

try {
    MapContext context = new MapContext();
    context.put("one", 1d);
    RankingExpression expression = new RankingExpression("10*if(i>35,if(i>one,if(i>=670,4,8),if(i>8000,5,3)),if(i==478,90,91))");
    double result = expression.evaluate(context);
   }
catch (ParseException e) {
    throw new RuntimeException(e);
}

Or, usage optimized for repeated evaluation of the same expression

// Members in a class living across multiple evaluations
RankingExpression expression;
ArrayContext contextPrototype;

...

// Initialization of the above members (once)
// Create reusable, gbdt optimized expression and context.
// The expression is multithread-safe while the context created is not
try {
    RankingExpression expression = new RankingExpression("10*if(i>35,if(i>one,if(i>=670,4,8),if(i>8000,5,3)),if(i==478,90,91))");
    ArrayContext contextPrototype = new ArrayContext(expression);
    ExpressionOptimizer optimizer = new ExpressionOptimizer(); // Increases evaluation speed of gbdt form expressions by 3-4x
    OptimizationReport triviaAboutTheOptimization = optimizer.optimize(expression, contextPrototype);
}
catch (ParseException e) {
    throw new RuntimeException(e);
}

...

// Execution (many)
context = contextPrototype.clone(); // If evaluation is multithreaded - skip this if execution is single-threaded
context.put("one",1d);
double result = expression.evaluate(context);

Author:

Simon Thoresen Hult, bratseth

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor	Description
RankingExpression(ExpressionNode root)	Creates a ranking expression from an expression root node.
RankingExpression(File file)	Creates a ranking expression from a file.
RankingExpression(Reader reader)	Creates an anonymous ranking expression by consuming from the reader
RankingExpression(String expression)	Creates a ranking expression from a string
RankingExpression(String name, ExpressionNode root)	Creates a named ranking expression from an expression root node.
RankingExpression(String name, Reader reader)	Creates a new ranking expression by consuming from the reader
RankingExpression(String name, String expression)	Creates a new ranking expression by consuming from the reader

Method Summary

Modifier and Type	Method	Description
RankingExpression	copy()	Returns a deep copy of this expression
boolean	equals(Object obj)
Value	evaluate(Context context)	Returns the value of evaluating this expression over the given context.
static String	extractScriptName(String propertyName)
static RankingExpression	from(String expression)	Creates a ranking expression from a string
String	getName()	Returns the name of this ranking expression, or "" if no name is set.
Map<String,String>	getRankProperties(SerializationContext context)	Creates the necessary rank properties required to implement this expression.
Map<String,String>	getRankProperties(List<ExpressionFunction> functions)	Deprecated.
ExpressionNode	getRoot()	Returns the root of the expression tree of this expression.
int	hashCode()
static String	propertyExpressionName(String expressionName)
static String	propertyName(String expressionName)	Returns the rank-property name for a given expression name.
void	setName(String name)	Sets the name of this ranking expression.
void	setRoot(ExpressionNode root)	Sets the root of the expression tree of this expression.
String	toString()
com.yahoo.tensor.TensorType	type(com.yahoo.tensor.evaluation.TypeContext<Reference> context)	Validates the type correctness of the given expression with the given context and returns the type this expression will produce from the given type context

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

RankingExpression

public RankingExpression(Reader reader)
                  throws ParseException

Creates an anonymous ranking expression by consuming from the reader

Throws:

ParseException

RankingExpression

public RankingExpression(String name,
                         Reader reader)
                  throws ParseException

Creates a new ranking expression by consuming from the reader

Parameters:

name - the name of the ranking expression

reader - the reader that contains the string to parse.

Throws:

ParseException - if the string could not be parsed.

RankingExpression

public RankingExpression(String name,
                         String expression)
                  throws ParseException

Creates a new ranking expression by consuming from the reader

Parameters:

name - the name of the ranking expression

expression - the expression to parse.

Throws:

ParseException - if the string could not be parsed.

RankingExpression

public RankingExpression(String expression)
                  throws ParseException

Creates a ranking expression from a string

Parameters:

expression - The reader that contains the string to parse.

Throws:

ParseException - if the string could not be parsed.

RankingExpression

public RankingExpression(File file)
                  throws ParseException

Creates a ranking expression from a file. For convenience, the file.getName() up to any dot becomes the name of this expression.

Parameters:

file - the name of the file whose content to parse.

Throws:

ParseException - if the string could not be parsed.

IllegalArgumentException - if the file could not be found

RankingExpression

public RankingExpression(String name,
                         ExpressionNode root)

Creates a named ranking expression from an expression root node.

RankingExpression

public RankingExpression(ExpressionNode root)

Creates a ranking expression from an expression root node.

Parameters:

root - The root node.

Method Detail

copy

public RankingExpression copy()

Returns a deep copy of this expression

getName

public String getName()

Returns the name of this ranking expression, or "" if no name is set.

Returns:

The name of this expression.

setName

public void setName(String name)

Sets the name of this ranking expression.

Parameters:

name - The name to set.

getRoot

public ExpressionNode getRoot()

Returns the root of the expression tree of this expression.

Returns:

The root node.

setRoot

public void setRoot(ExpressionNode root)

Sets the root of the expression tree of this expression.

Parameters:

root - The root node to set.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

toString

public String toString()

Overrides:

toString in class Object

getRankProperties

public Map<String,String> getRankProperties(SerializationContext context)

Creates the necessary rank properties required to implement this expression.

Parameters:

context - context for serialization

Returns:

a list of named rank properties required to implement this expression

getRankProperties

@Deprecated
public Map<String,String> getRankProperties(List<ExpressionFunction> functions)

Deprecated.

propertyName

public static String propertyName(String expressionName)

Returns the rank-property name for a given expression name.

Parameters:

expressionName - the expression name to mangle.

Returns:

the property name.

propertyExpressionName

public static String propertyExpressionName(String expressionName)

extractScriptName

public static String extractScriptName(String propertyName)

type

public com.yahoo.tensor.TensorType type(com.yahoo.tensor.evaluation.TypeContext<Reference> context)

Validates the type correctness of the given expression with the given context and returns the type this expression will produce from the given type context

Throws:

IllegalArgumentException - if this expression is not type correct in this context

evaluate

public Value evaluate(Context context)

Returns the value of evaluating this expression over the given context.

Parameters:

context - The variable bindings to use for this evaluation.

Returns:

the evaluation result.

Throws:

IllegalArgumentException - if there are variables which are not bound in the given map

from

public static RankingExpression from(String expression)

Creates a ranking expression from a string

Throws:

IllegalArgumentException - if the string is not a valid ranking expression