com.attivio.sdk.search.fields

Class Freshness

java.lang.Object

com.attivio.sdk.search.fields.FieldExpression

com.attivio.sdk.search.fields.UnaryFieldExpression

com.attivio.sdk.search.fields.Freshness

All Implemented Interfaces:

Serializable, 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

Nested Class Summary

Nested classes/interfaces inherited from class com.attivio.sdk.search.fields.FieldExpression

FieldExpression.StringMode

Field Summary

Fields

Modifier and Type	Field and Description
static TimeResolution	DEFAULT_CENTER_RESOLUTION The default center resolution.
static double	DEFAULT_DECAY The default value for decay

Fields inherited from class com.attivio.sdk.search.fields.UnaryFieldExpression

expression

Fields inherited from class com.attivio.sdk.search.fields.FieldExpression

alias, EMPTY_ARRAY

Constructor Summary

Constructors

Constructor and Description
Freshness(FieldExpression field)
Freshness(FieldExpression field, String alias)
Freshness(Freshness base, Date center) Crate a new freshness identical to base except with a new center.
Freshness(String fieldName)
Freshness(String fieldName, double decay)
Freshness(String fieldName, double decay, Date center)
Freshness(String fieldName, double decay, Date center, Date defaultValue)

Method Summary

Modifier and Type	Method and Description
void	addRange(FreshnessRange range)
void	addRange(long maxDelta, TimeResolution timeUnit, double a, double b, double c) Add a range to the freshness table.
Freshness	clone()
protected Freshness	clone(FieldExpression e) Create a new instance of this FieldExpression, with a different argument.
Date	getCenter() Get the "center" date used to calculate freshness.
TimeResolution	getCenterResolution() Get the resolution for rounding the center date.
double	getDecay() Get the "decay" exponent used to calculate freshness.
Date	getDefault() Get the default time to use for documents that do not have a value set for "fieldName".
ArrayList<FreshnessRange>	getRanges()
SchemaField.Type	getType(Schema schema) Resolve the type for this expression.
int	hashCode()
protected boolean	parametersEqual(FieldExpression other) Returns true if other's parameters are the same as this.
void	setCenter(Date center) Set the "center" date used to calculate freshness.
void	setCenterResolution(TimeResolution units) Set the resolution for rounding the center date.
void	setDecay(double decay) Set the "decay" exponent used to calculate freshness.
void	setDefault(Date value) Set the default time to use for documents that do not have a value set for "fieldName".
void	setFieldName(String fieldName) Set the field name to calculate freshness from.
void	setRanges(FreshnessRange... value)
void	setRanges(List<FreshnessRange> value)
void	toString(StringBuilder buffer, FieldExpression.StringMode mode) Writes the string representation of this field expression to buffer.

Methods inherited from class com.attivio.sdk.search.fields.UnaryFieldExpression

equalsIgnoreAlias, getExpression, getFieldName, hasChildren, isConstant, rewrite, rewriteChildren, setExpression

Methods inherited from class com.attivio.sdk.search.fields.FieldExpression

as, containsAlias, copyOf, equals, equalsIgnoreAlias, getAlias, getDefaultAlias, handleFieldExpression, isConstant, quote, rewrite, setAlias, toString, toString

Methods inherited from class java.lang.Object

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

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(FieldExpression field)

Freshness

public Freshness(FieldExpression field,
                 String alias)

Freshness

public Freshness(String fieldName)

Freshness

public Freshness(String fieldName,
                 double decay)

Freshness

public Freshness(String fieldName,
                 double decay,
                 Date center)

Freshness

public Freshness(String fieldName,
                 double decay,
                 Date center,
                 Date defaultValue)

Freshness

public Freshness(Freshness base,
                 Date center)

Crate a new freshness identical to base except with a new center.

Method Detail

getType

public SchemaField.Type getType(Schema schema)

Resolve the type for this expression.

Specified by:

getType in class FieldExpression

setFieldName

public void setFieldName(String fieldName)

Set the field name to calculate freshness from.

The field specified here must be a Date field.

getDefault

public 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(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 Date getCenter()

Get the "center" date used to calculate freshness.

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

setCenter

public void setCenter(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.

getRanges

public ArrayList<FreshnessRange> getRanges()

setRanges

public void setRanges(List<FreshnessRange> value)

setRanges

public void setRanges(FreshnessRange... value)

addRange

public void addRange(FreshnessRange range)

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.

toString

public void toString(StringBuilder buffer,
                     FieldExpression.StringMode mode)

Writes the string representation of this field expression to buffer.

NOTE: the alias will not be written to buffer by this function.

Specified by:

toString in class FieldExpression

hashCode

public int hashCode()

Overrides:

hashCode in class UnaryFieldExpression

parametersEqual

protected boolean parametersEqual(FieldExpression other)

Returns true if other's parameters are the same as this.

Specified by:

parametersEqual in class UnaryFieldExpression

clone

public Freshness clone()

Overrides:

clone in class UnaryFieldExpression

clone

protected Freshness clone(FieldExpression e)

Create a new instance of this FieldExpression, with a different argument.

Overrides:

clone in class UnaryFieldExpression