Overview
The Distance class is used to calculate the spherical distance between two points. This class applies to the scenarios of distance-based sorting or processing. A Distance object contains two points. The coordinates of one point are obtained from a document and those of the other are specified as custom parameters in a search request. Custom parameters are those defined in the kvpairs clause of a search request. You can define custom parameters by using OpenSearch SDKs or manually constructing a kvpairs clause.
Functions
Function | Description |
Distance create(OpsScorerInitParams params,CString longitudeAFieldName, CString latitudeAFieldName, CString longitudeBRequestKeyName,CString latitudeBRequestKeyName) | Creates a Distance object based on the coordinates of two points A and B. |
Distance create(OpsScorerInitParams params,CString longitudeAFieldName, CString latitudeAFieldName, CString longitudeBRequestKeyName, CString latitudeBRequestKeyName, CString outputName) | Creates a Distance object based on the coordinates of two points A and B, and returns the distance to the document as the value of the field that you specify by using the outputName parameter. |
Distance create(OpsScorerInitParams params,CString geoPointAFieldName, CString geoPointBRequestKeyName) | Creates a Distance object based on two points A and B of the GEO_POINT type. |
Distance create(OpsScorerInitParams params,CString geoPointAFieldName, CString geoPointBRequestKeyName, CString outputName) | Creates a Distance object based on two points A and B of the GEO_POINT type, and returns the distance to the document as the value of the field that you specify by using the outputName parameter. |
Distance create(OpsScorerInitParams params,CString geoPointAFieldName, CString geoPointBRequestKeyName, CString outputName, float defaultValue) | Creates a Distance object based on two points A and B of the GEO_POINT type, and returns the distance to the document as the value of the field that you specify by using the outputName parameter. |
double evaluate(OpsScoreParams params) | Calculates the spherical distance between two points. |
Function details
Distance create(OpsScorerInitParams params, CString longitudeAFieldName, CString latitudeAFieldName, CString longitudeBRequestKeyName, CString latitudeBRequestKeyName)
Creates a Distance object based on the coordinates of two points A and B. The longitude and latitude of Point A are obtained from specified fields in a document. The longitude and latitude of Point B are specified as custom parameters in a search request. Parameters: params: the parameters that are used for score calculation. For more information, see OpsScoreParams. longitudeAFieldName: the name of an attribute field, whose value is to be used as the longitude of Point A and must be a constant. latitudeAFieldName: the name of an attribute field, whose value is to be used as the latitude of Point A and must be a constant. longitudeBRequestKeyName: the name of a custom parameter, whose value is to be used as the longitude of Point B and must be a constant. latitudeBRequestKeyName: the name of a custom parameter, whose value is to be used as the latitude of Point B and must be a constant.
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.Distance;
class BasicSimilarityScorer {
Distance _distance;
boolean init(OpsScorerInitParams params) {
_distance = Distance.create(params, "longitudeInDoc", "latitudeInDoc",
"longitudeInRequest", "latitudeInRequest");
return true;
}
double score(OpsScoreParams params) {
return _distance.evaluate(params);
}
}Distance create(OpsScorerInitParams params, CString longitudeAFieldName, CString latitudeAFieldName, CString longitudeBRequestKeyName, CString latitudeBRequestKeyName, CString outputName)
Creates a Distance object based on the coordinates of two points A and B. The longitude and latitude of Point A are obtained from specified fields in a document. The longitude and latitude of Point B are specified as custom parameters in a search request. This function adds a field to the document to store the calculation result. You can specify the outputName parameter to name the field to be added. After this function calculates the spherical distance between the two points, it returns the calculation result as the value of the specified field. Parameters: params: the parameters that are used for score calculation. For more information, see OpsScoreParams. longitudeAFieldName: the name of an attribute field, whose value is to be used as the longitude of Point A and must be a constant. latitudeAFieldName: the name of an attribute field, whose value is to be used as the latitude of Point A and must be a constant. longitudeBRequestKeyName: the name of a custom parameter, whose value is to be used as the longitude of Point B and must be a constant. latitudeBRequestKeyName: the name of a custom parameter, whose value is to be used as the latitude of Point B and must be a constant. outputName: the name of the field to be added in the document to store the calculation result. The name must be a constant.
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.Distance;
class BasicSimilarityScorer {
Distance _distance;
boolean init(OpsScorerInitParams params) {
_distance = Distance.create(params, "longitudeInDoc", "latitudeInDoc",
"longitudeInRequest", "latitudeInRequest", "output");
return true;
}
double score(OpsScoreParams params) {
return _distance.evaluate(params);
}
}Distance create(OpsScorerInitParams params, CString geoPointAFieldName, CString geoPointBRequestKeyName)
Creates a Distance object based on two points A and B of the GEO_POINT type. The coordinates of Point A are obtained from a field of the GEO_POINT type in a document. The coordinates of Point B are obtained from a custom parameter in a search request. The values of the custom parameter to be used as the coordinates of Point B must be separated with a space. The first value is used as the longitude. The second value is used as the latitude. Example: 12.0 34.5. Parameters: params: the parameters that are used for score calculation. For more information, see OpsScoreParams. geoPointAFieldName: the name of a field of the GEO_POINT type, whose values are to be used as the coordinates of Point A and must be constants. geoPointBRequestKeyName: the name of a custom parameter in a search request. The values of the custom parameter are to be used as the coordinates of Point B and must be constants. 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.Distance;
class BasicSimilarityScorer {
Distance _distance;
boolean init(OpsScorerInitParams params) {
_distance = Distance.create(params, "location", "locationInRequest");
return true;
}
double score(OpsScoreParams params) {
return _distance.evaluate(params);
}
}Distance create(OpsScorerInitParams params, CString geoPointAFieldName, CString geoPointBRequestKeyName, CString outputName)
Creates a Distance object based on two points A and B of the GEO_POINT type. The coordinates of Point A are obtained from a field of the GEO_POINT type in a document. The coordinates of Point B are obtained from a custom parameter in a search request. The values of the custom parameter to be used as the coordinates of Point B must be separated with a space. The first value is used as the longitude. The second value is used as the latitude. Example: 12.0 34.5. This function adds a field to the document to store the calculation result. You can specify the outputName parameter to name the field to be added. After this function calculates the spherical distance between the two points, it returns the calculation result as the value of the specified field. Parameters: params: the parameters that are used for score calculation. For more information, see OpsScoreParams. geoPointAFieldName: the name of a field of the GEO_POINT type, whose values are to be used as the coordinates of Point A and must be constants. geoPointBRequestKeyName: the name of a custom parameter in a search request. The values of the custom parameter are to be used as the coordinates of Point B and must be constants. outputName: the name of the field to be added in the document to store the calculation result. The name must be a constant. 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.Distance;
class BasicSimilarityScorer {
Distance _distance;
boolean init(OpsScorerInitParams params) {
_distance = Distance.create(params, "location", "locationInRequest", "output");
return true;
}
double score(OpsScoreParams params) {
return _distance.evaluate(params);
}
}Distance create(OpsScorerInitParams params, CString geoPointAFieldName, CString geoPointBRequestKeyName, CString outputName, float defaultValue)
Creates a Distance object based on two points A and B of the GEO_POINT type. The coordinates of Point A are obtained from a field of the GEO_POINT type in a document. The coordinates of Point B are obtained from a custom parameter in a search request. The values of the custom parameter to be used as the coordinates of Point B must be separated with a space. The first value is used as the longitude. The second value is used as the latitude. Example: 12.0 34.5. This function adds a field to the document to store the calculation result. You can specify the outputName parameter to name the field to be added. After this function calculates the spherical distance between the two points, it returns the calculation result as the value of the specified field. Parameters: params: the parameters that are used for score calculation. For more information, see OpsScoreParams. geoPointAFieldName: the name of a field of the GEO_POINT type, whose values are to be used as the coordinates of Point A and must be constants. geoPointBRequestKeyName: the name of a custom parameter in a search request. The values of the custom parameter are to be used as the coordinates of Point B and must be constants. outputName: the name of the field to be added in the document to store the calculation result. The name must be a constant. defaultValue: the value to be returned if the coordinates of Point A or B are invalid.
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.Distance;
class BasicSimilarityScorer {
Distance _distance;
boolean init(OpsScorerInitParams params) {
_distance = Distance.create(params, "location", "locationInRequest", "output", 100.0);
return true;
}
double score(OpsScoreParams params) {
return _distance.evaluate(params);
}
}double evaluate(OpsScoreParams params)
Calculates the spherical distance between two points. Parameter: params: the parameters that are used for score calculation. For more information, see OpsScoreParams. Return value: the spherical distance between the two points.