Calculates the spherical distance between two geographic points. Use this class in custom scorers to rank or filter search results by proximity — for example, sorting nearby stores, restaurants, or service locations by distance from a user's current position.
Each Distance object represents a pair of points:
Point A — coordinates read from a field in the indexed document
Point B — coordinates supplied as a custom parameter in the search request, defined in the
kvpairsclause
Set custom parameters using an OpenSearch SDK or by constructing a kvpairs clause manually.
Functions
| Signature | Description |
|---|---|
Distance create(OpsScorerInitParams params, CString longitudeAFieldName, CString latitudeAFieldName, CString longitudeBRequestKeyName, CString latitudeBRequestKeyName) | Creates a Distance object from separate longitude and latitude fields (Point A) and request parameters (Point B). |
Distance create(OpsScorerInitParams params, CString longitudeAFieldName, CString latitudeAFieldName, CString longitudeBRequestKeyName, CString latitudeBRequestKeyName, CString outputName) | Same as above, and writes the calculated distance to a named field in the document. |
Distance create(OpsScorerInitParams params, CString geoPointAFieldName, CString geoPointBRequestKeyName) | Creates a Distance object from a GEO_POINT field (Point A) and a space-separated GEO_POINT request parameter (Point B). |
Distance create(OpsScorerInitParams params, CString geoPointAFieldName, CString geoPointBRequestKeyName, CString outputName) | Same as above, and writes the calculated distance to a named field in the document. |
Distance create(OpsScorerInitParams params, CString geoPointAFieldName, CString geoPointBRequestKeyName, CString outputName, float defaultValue) | Same as above, with a fallback value when coordinates are invalid. |
double evaluate(OpsScoreParams params) | Calculates and returns the spherical distance between the two points. |
Function details
Choose between separate fields and GEO_POINT
Two sets of create() overloads are available depending on how coordinates are stored in your index:
| Coordinate storage | Overloads to use |
|---|---|
Separate longitude and latitude attribute fields | First two overloads (with longitudeAFieldName, latitudeAFieldName) |
A single field of type GEO_POINT | Last three overloads (with geoPointAFieldName) |
Distance create(OpsScorerInitParams params, CString longitudeAFieldName, CString latitudeAFieldName, CString longitudeBRequestKeyName, CString latitudeBRequestKeyName)
Creates a Distance object using separate longitude and latitude fields for Point A and separate request parameters for Point B.
Parameters
| Parameter | Type | Constraint | Description |
|---|---|---|---|
params | OpsScorerInitParams | — | The parameters for score calculation. See OpsScoreParams. |
longitudeAFieldName | CString | Must be a constant | The name of the attribute field whose value is the longitude of Point A. |
latitudeAFieldName | CString | Must be a constant | The name of the attribute field whose value is the latitude of Point A. |
longitudeBRequestKeyName | CString | Must be a constant | The name of the custom request parameter whose value is the longitude of Point B. |
latitudeBRequestKeyName | CString | Must be a constant | The name of the custom request parameter whose value is the latitude of Point B. |
Example
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)
Same as the previous overload, and additionally writes the calculated distance to a new field in the document. Use outputName when a downstream pipeline step or a sort expression needs to read the distance value by field name.
Parameters
| Parameter | Type | Constraint | Description |
|---|---|---|---|
params | OpsScorerInitParams | — | The parameters for score calculation. See OpsScoreParams. |
longitudeAFieldName | CString | Must be a constant | The name of the attribute field whose value is the longitude of Point A. |
latitudeAFieldName | CString | Must be a constant | The name of the attribute field whose value is the latitude of Point A. |
longitudeBRequestKeyName | CString | Must be a constant | The name of the custom request parameter whose value is the longitude of Point B. |
latitudeBRequestKeyName | CString | Must be a constant | The name of the custom request parameter whose value is the latitude of Point B. |
outputName | CString | Must be a constant | The name of the field added to the document to store the calculation result. |
Example
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 using a GEO_POINT field for Point A and a space-separated coordinate pair in the request for Point B.
GEO_POINT request parameter format
The value of geoPointBRequestKeyName must be two numbers separated by a space: longitude first, then latitude.
12.0 34.5Parameters
| Parameter | Type | Constraint | Description |
|---|---|---|---|
params | OpsScorerInitParams | — | The parameters for score calculation. See OpsScoreParams. |
geoPointAFieldName | CString | Must be a constant | The name of the GEO_POINT field in the document, used as the coordinates of Point A. |
geoPointBRequestKeyName | CString | Must be a constant | The name of the custom request parameter whose value is the coordinates of Point B (format: <longitude> <latitude>). |
Example
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)
Same as the previous overload, and additionally writes the calculated distance to a new field in the document. Use outputName when a downstream pipeline step or a sort expression needs to read the distance value by field name.
Parameters
| Parameter | Type | Constraint | Description |
|---|---|---|---|
params | OpsScorerInitParams | — | The parameters for score calculation. See OpsScoreParams. |
geoPointAFieldName | CString | Must be a constant | The name of the GEO_POINT field in the document, used as the coordinates of Point A. |
geoPointBRequestKeyName | CString | Must be a constant | The name of the custom request parameter whose value is the coordinates of Point B (format: <longitude> <latitude>). |
outputName | CString | Must be a constant | The name of the field added to the document to store the calculation result. |
Example
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)
Same as the previous overload, with an additional defaultValue parameter. Use defaultValue to handle documents with missing or malformed GEO_POINT field values — for example, records imported before geo coordinates were populated. The default value is returned whenever Point A or Point B coordinates are invalid.
Parameters
| Parameter | Type | Constraint | Description |
|---|---|---|---|
params | OpsScorerInitParams | — | The parameters for score calculation. See OpsScoreParams. |
geoPointAFieldName | CString | Must be a constant | The name of the GEO_POINT field in the document, used as the coordinates of Point A. |
geoPointBRequestKeyName | CString | Must be a constant | The name of the custom request parameter whose value is the coordinates of Point B (format: <longitude> <latitude>). |
outputName | CString | Must be a constant | The name of the field added to the document to store the calculation result. |
defaultValue | float | — | The fallback value returned when Point A or Point B coordinates are invalid. |
Example
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 the two points configured in the Distance object.
Parameters
| Parameter | Type | Description |
|---|---|---|
params | OpsScoreParams | The parameters for score calculation. See OpsScoreParams. |
Return value
The spherical distance between Point A and Point B, as a double.