OpenSearch:Util

The Util class provides a set of functionality functions that are frequently used, such as decay functions and normalization functions.

static double gaussDecay(double origin, double value, double scale, double decay, double offset)

This function uses a Gaussian function to calculate the degree of attenuation based on the distance between a value and a specific start point. You can use this decay function to sort numbers. The numbers within a specific value range do not need to be sorted. For example, you want to search for the nearest hotel. The nearby hotels are sorted from near to far, and the hotels less than 100 meters away from you do not need to be sorted. In this case, if the distanceValue parameter is used to specify the distance, the following decay function can be used: gauss_decay(0, distanceValue, 5, 0.000001, 0.1).

Parameters:

• origin: the start point. If the value of the value parameter is equal to the value of the origin parameter, the score is 1.0.

• value: the value for which you want to calculate the decay degree.

• scale: the decay rate. The parameter reflects the rate at which the score changes when the value of the value parameter decreases from the value of the origin parameter.

• decay: the score that is obtained when the value of the value parameter decreases from the value of the origin parameter to that of the scale parameter.

• offset: the offset. The decay degree starts to be calculated when the distance is greater than the value of the offset parameter. If the value of the value parameter is greater than the value that is obtained by subtracting the value of the offset parameter from that of the origin parameter but is less than the sum of the values of the origin and offset parameters, the decay function returns 1.0.

Return value:

Returns the decay degree. Valid values: [0,1].

Sample code:

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.gaussDecay(0.0, distanceValue, 5.0, 0.000001, 0.1);
    }
}

static double gaussDecay(double origin, double value, double scale, double decay)

The details of this function are similar to those of the static double gaussDecay(double origin, double value, double scale, double decay, double offset) function. The difference lies in that the offset parameter in this function must be set to 0.

Parameters:

• origin: the start point. If the value of the value parameter is equal to the value of the origin parameter, the score is 1.0.

• value: the value for which you want to calculate the decay degree.

• scale: the decay rate. The parameter reflects the rate at which the score changes when the value of the value parameter decreases from the value of the origin parameter.

• decay: the score that is obtained when the value of the value parameter decreases from the value of the origin parameter to that of the scale parameter.

Return value:

Returns the decay degree. Valid values: [0,1].

Sample code:

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.gaussDecay(0.0, distanceValue, 5.0, 0.000001);
    }
}

static double gaussDecay(double origin, double value, double scale)

The details of this function are similar to those of the static double gaussDecay(double origin, double value, double scale, double decay, double offset) function. The difference lies in that the decay and offset parameters in this function must be set to 0.000001 and 0.

Parameters:

• origin: the start point. If the value of the value parameter is equal to the value of the origin parameter, the score is 1.0.

• value: the value for which you want to calculate the decay degree.

• scale: the decay rate. The parameter reflects the rate at which the score changes when the value of the value parameter decreases from the value of the origin parameter.

Return value:

Returns the decay degree. Valid values: [0,1].

Sample code:

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.gaussDecay(0.0, distanceValue, 5.0);
    }
}

static double expDecay(double origin, double value, double scale, double decay, double offset)

This function uses an exponential function to calculate the decay degree based on the distance between a value and a specific start point. The application scenario is the same as that of the gaussDecay function.

Parameters:

• origin: the start point. If the value of the value parameter is equal to the value of the origin parameter, the score is 1.0.

• value: the value for which you want to calculate the decay degree.

• scale: the decay rate. The parameter reflects the rate at which the score changes when the value of the value parameter decreases from the value of the origin parameter.

• decay: the score that is obtained when the value of the value parameter decreases from the value of the origin parameter to that of the scale parameter.

• offset: the offset. The decay degree starts to be calculated when the distance is greater than the value of the offset parameter. If the value of the value parameter is greater than the value that is obtained by subtracting the value of the offset parameter from that of the origin parameter but is less than the sum of the values of the origin and offset parameters, the decay function returns 1.0.

Return value:

Returns the decay degree. Valid values: [0,1].

Sample code:

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.expDecay(0.0, distanceValue, 5.0, 0.000001, 0.1);
    }
}

static double expDecay(double origin, double value, double scale, double decay)

The details of this function are similar to those of the static double expDecay(double origin, double value, double scale, double decay, double offset) function. The difference lies in that the offset parameter in this function must be set to 0.

Parameters:

• origin: the start point. If the value of the value parameter is equal to the value of the origin parameter, the score is 1.0.

• value: the value for which you want to calculate the decay degree.

• scale: the decay rate. The parameter reflects the rate at which the score changes when the value of the value parameter decreases from the value of the origin parameter.

• decay: the score that is obtained when the value of the value parameter decreases from the value of the origin parameter to that of the scale parameter.

Return value:

Returns the decay degree. Valid values: [0,1].

Sample code:

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.expDecay(0.0, distanceValue, 5.0, 0.000001);
    }
}

static double expDecay(double origin, double value, double scale)

The details of this function are similar to those of the static double expDecay(double origin, double value, double scale, double decay, double offset) function. The difference lies in that the decay and offset parameters in this function must be set to 0.000001 and 0.

Parameters:

• origin: the start point. If the value of the value parameter is equal to the value of the origin parameter, the score is 1.0.

• value: the value for which you want to calculate the decay degree.

• scale: the decay rate. The parameter reflects the rate at which the score changes when the value of the value parameter decreases from the value of the origin parameter.

Return value:

Returns the decay degree. Valid values: [0,1].

Sample code:

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.expDecay(0.0, distanceValue, 5.0);
    }
}

static double linearDecay(double origin, double value, double scale, double decay, double offset)

This function uses a linear function to calculate the decay degree based on the distance between a value and a specific start point. The application scenario is the same as that of the gaussDecay function.

Parameters:

• origin: the start point. If the value of the value parameter is equal to the value of the origin parameter, the score is 1.0.

• value: the value for which you want to calculate the decay degree.

• scale: the decay rate. The parameter reflects the rate at which the score changes when the value of the value parameter decreases from the value of the origin parameter.

• decay: the score that is obtained when the value of the value parameter decreases from the value of the origin parameter to that of the scale parameter.

• offset: the offset. The decay degree starts to be calculated when the distance is greater than the value of the offset parameter. If the value of the value parameter is greater than the value that is obtained by subtracting the value of the offset parameter from that of the origin parameter but is less than the sum of the values of the origin and offset parameters, the decay function returns 1.0.

Return value:

Returns the decay degree. Valid values: [0,1].

Sample code:

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.linearDecay(0.0, distanceValue, 5.0, 0.000001, 0.1);
    }
}

static double linearDecay(double origin, double value, double scale, double decay)

The details of this function are similar to those of the static double linearDecay(double origin, double value, double scale, double decay, double offset) function. The difference lies in that the offset parameter in this function must be set to 0.

Parameters:

• origin: the start point. If the value of the value parameter is equal to the value of the origin parameter, the score is 1.0.

• value: the value for which you want to calculate the decay degree.

• scale: the decay rate. The parameter reflects the rate at which the score changes when the value of the value parameter decreases from the value of the origin parameter.

• decay: the score that is obtained when the value of the value parameter decreases from the value of the origin parameter to that of the scale parameter.

Return value:

Returns the decay degree. Valid values: [0,1].

Sample code:

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.linearDecay(0.0, distanceValue, 5.0, 0.000001);
    }
}

static double linearDecay(double origin, double value, double scale)

The details of this function are similar to those of the static double linearDecay(double origin, double value, double scale, double decay, double offset) function. The difference lies in that the decay and offset parameters in this function must be set to 0.000001 and 0.

Parameters:

• origin: the start point. If the value of the value parameter is equal to the value of the origin parameter, the score is 1.0.

• value: the value for which you want to calculate the decay degree.

• scale: the decay rate. The parameter reflects the rate at which the score changes when the value of the value parameter decreases from the value of the origin parameter.

Return value:

Returns the decay degree. Valid values: [0,1].

Sample code:

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.linearDecay(0.0, distanceValue, 5.0);
    }
}

static double normalize(double value, double max, double min)

This function uses a linear function for normalization. The following formula is used: value / (max - min).

Parameters:

• value: the value that needs to be normalized.

• max: the maximum value of the value parameter.

• min: the minimum value of the value parameter.

Return value:

Returns the normalized result. Valid values: [0,1]. If the value of the max parameter is less than that of the min parameter, 0 is returned.

Sample code:

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;

class BasicSimilarityScorer {
    boolean init(OpsScorerInitParams params) {
        return params.getDoc().requireAttribute("price");
    }

    double score(OpsScoreParams params) {
        OpsDoc doc = params.getDoc();
        long price = doc.docFieldLong("price");
        return Util.normalize(price, 0.0, 100000.0);
    }
}

static double normalize(double value, double max)

This function uses a logarithmic function for normalization. The following formula is used: log10(value)/log(max).

Parameters:

• value: the value that needs to be normalized.

• max: the maximum value of the value parameter.

Return value:

Returns the normalized result. Valid values: [0,1]. If the values of the value and max parameters are less than 1, 0 is returned.

Sample code:

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;

class BasicSimilarityScorer {
    boolean init(OpsScorerInitParams params) {
        return params.getDoc().requireAttribute("price");
    }

    double score(OpsScoreParams params) {
        OpsDoc doc = params.getDoc();
        long price = doc.docFieldLong("price");
        return Util.normalize(price, 100000.0);
    }
}

static double normalize(double value)

This function uses an arctangent function for normalization. The following formula is used: atan(value / 1000.0) * 2 / pi, where pi is equal to 3.141593.

Parameters:

• value: the value that needs to be normalized.

Return value:

Returns the decay degree. Valid values: [0,1].

Sample code:

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;

class BasicSimilarityScorer {
    boolean init(OpsScorerInitParams params) {
        return params.getDoc().requireAttribute("price");
    }

    double score(OpsScoreParams params) {
        OpsDoc doc = params.getDoc();
        long price = doc.docFieldLong("price");
        return Util.normalize(price);
    }
}