Package com.yahoo.searchlib.rankingexpression

Class RankingExpression

  • All Implemented Interfaces:
    java.io.Serializable
    public class RankingExpression
extends java.lang.Object
implements java.io.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​(java.io.File file)
      Creates a ranking expression from a file.
      RankingExpression​(java.io.Reader reader)
      Creates an anonymous ranking expression by consuming from the reader
      RankingExpression​(java.lang.String expression)
      Creates a ranking expression from a string
      RankingExpression​(java.lang.String name, ExpressionNode root)
      Creates a named ranking expression from an expression root node.
      RankingExpression​(java.lang.String name, java.io.Reader reader)
      Creates a new ranking expression by consuming from the reader
      RankingExpression​(java.lang.String name, java.lang.String expression)
      Creates a new ranking expression by consuming from the reader

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      RankingExpression copy()
      Returns a deep copy of this expression
      boolean equals​(java.lang.Object obj)  
      Value evaluate​(Context context)
      Returns the value of evaluating this expression over the given context.
      static RankingExpression from​(java.lang.String expression)
      Creates a ranking expression from a string
      java.lang.String getName()
      Returns the name of this ranking expression, or "" if no name is set.
      java.util.Map<java.lang.String,​java.lang.String> getRankProperties​(java.util.List<ExpressionFunction> functions)
      Creates the necessary rank properties required to implement this expression.
      ExpressionNode getRoot()
      Returns the root of the expression tree of this expression.
      int hashCode()  
      static java.lang.String propertyName​(java.lang.String expressionName)
      Returns the rank-property name for a given expression name.
      void setName​(java.lang.String name)
      Sets the name of this ranking expression.
      void setRoot​(ExpressionNode root)
      Sets the root of the expression tree of this expression.
      java.lang.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​(java.io.Reader reader)
                  throws ParseException
        Creates an anonymous ranking expression by consuming from the reader
        Throws:
        ParseException

      • RankingExpression

        public RankingExpression​(java.lang.String name,
                         java.io.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​(java.lang.String name,
                         java.lang.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​(java.lang.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​(java.io.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.
        java.lang.IllegalArgumentException - if the file could not be found

      • RankingExpression

        public RankingExpression​(java.lang.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

      • getName

        public java.lang.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​(java.lang.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 java.lang.Object

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • getRankProperties

        public java.util.Map<java.lang.String,​java.lang.String> getRankProperties​(java.util.List<ExpressionFunction> functions)
        Creates the necessary rank properties required to implement this expression.
        Parameters:
        functions - the expression functions to expand
        Returns:
        a list of named rank properties required to implement this expression

      • propertyName

        public static java.lang.String propertyName​(java.lang.String expressionName)
        Returns the rank-property name for a given expression name.
        Parameters:
        expressionName - the expression name to mangle.
        Returns:
        the property name.

      • 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:
        java.lang.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:
        java.lang.IllegalArgumentException - if there are variables which are not bound in the given map

      • from

        public static RankingExpression from​(java.lang.String expression)
        Creates a ranking expression from a string
        Throws:
        java.lang.IllegalArgumentException - if the string is not a valid ranking expression