Package com.attivio.sdk.search.fields

Class Freshness

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable
    public class Freshness
extends UnaryFieldExpression
    Field Expression to calculate a Freshness score.

    The freshness score function will boost documents that are close to a center date.

    The standard freshness calculation for a document is as follows:
    freshness = 1 / pow( abs(center - freshnessValue(fieldName, doc)) + 1, " decay )
    freshnessValue(fieldName, doc) = the indexed freshness value for fieldName in doc.

    By default, the center value is System.currentTimeMillis()/1000 (ie. current seconds since epoch). You can specify a different center using the appropriate constructor, or by using setCenter(Date).

    NOTE: By Default the center value will be rounded up to the next hour during evaluation. This greatly improves cache hits when including freshness scores in searches. You can control the units used for rounding (minutes, seconds, etc) by setting the center time units.

    The decay is used to accelerate or decelerate the change in score as documents approach the center. The freshness score will be a number between 0.0 and 1.0 for positive decay values. Larger values for the decay will result in a faster dropoff in boost as the document's "date" diverges from the "center".

    The freshness score can consist of ranges instead of a static decay function. Ranges contain a maxDelta distance from the table's center in the specified timeUnit (by default seconds). When ranges are specified, the score is determined by the quadraticCoefficient a, linearCoefficient b, and constant c, which are used as the constants of the quadratic equation y = ax^2 + bx + c, where x is the time delta from the center in the given unit and y is the final score. Setting a and b to zero will result in the constant score c for a range. .

    Ranges are not additive; the score is determined only by the most specific (smallest delta from the center) matching range. If the function returns a value less than zero, the freshness score is zero. The final score is normalized to a score of 0 to 1 by dividing the function result by the max allowed function value for all ranges.

    See Also:
    Serialized Form

    • Field Detail

      • DEFAULT_DECAY

        public static final double DEFAULT_DECAY
        The default value for decay
        See Also:
        Constant Field Values

      • DEFAULT_CENTER_RESOLUTION

        public static final TimeResolution DEFAULT_CENTER_RESOLUTION
        The default center resolution.

    • Constructor Detail

      • Freshness

        public Freshness​(java.lang.String fieldName)

      • Freshness

        public Freshness​(java.lang.String fieldName,
                 double decay)

      • Freshness

        public Freshness​(java.lang.String fieldName,
                 double decay,
                 java.util.Date center)

      • Freshness

        public Freshness​(java.lang.String fieldName,
                 double decay,
                 java.util.Date center,
                 java.util.Date defaultValue)

      • Freshness

        public Freshness​(Freshness base,
                 java.util.Date center)
        Crate a new freshness identical to base except with a new center.

    • Method Detail

      • setFieldName

        public void setFieldName​(java.lang.String fieldName)
        Set the field name to calculate freshness from.

        The field specified here must be a Date field.

      • getDefault

        public java.util.Date getDefault()
        Get the default time to use for documents that do not have a value set for "fieldName".

        If null, this will be epoch start time.

      • setDefault

        public void setDefault​(java.util.Date value)
        Set the default time to use for documents that do not have a value set for "fieldName".

        If null, this will be epoch start time.

      • getCenter

        public java.util.Date getCenter()
        Get the "center" date used to calculate freshness.

        null value means calcualte freshness from "NOW" ( System.currentTimeMillis())

      • setCenter

        public void setCenter​(java.util.Date center)
        Set the "center" date used to calculate freshness.

        Set to null to use "NOW" (System.currentTimeMillis()) as the center.

      • getCenterResolution

        public TimeResolution getCenterResolution()
        Get the resolution for rounding the center date.

      • setCenterResolution

        public void setCenterResolution​(TimeResolution units)
        Set the resolution for rounding the center date.

      • getDecay

        public double getDecay()
        Get the "decay" exponent used to calculate freshness.

      • setDecay

        public void setDecay​(double decay)
        Set the "decay" exponent used to calculate freshness.

      • setRanges

        public void setRanges​(java.util.List<FreshnessRange> value)

      • addRange

        public void addRange​(long maxDelta,
                     TimeResolution timeUnit,
                     double a,
                     double b,
                     double c)
        Add a range to the freshness table.

        a, b, and c are the coefficients of the quadratic function y = ax^2 + bx + c, where x is the delta from the center point in the given units and y is the score.