Functions that can be used as both feature functions and functionality functions
Specific functions can be used as both feature functions and functionality functions. You can use such functions in filter clauses, sort clauses, and sort expressions.
The fields that you reference in parameters of such functions must be configured as index or attribute fields based on the description of each function.
distance: returns the spherical distance between two points, which is often used in a location-based service
longitude_a: the longitude value of Point a. The value of this parameter can be the name of a field of the FLOAT type.
latitude_a: the latitude value of Point a. The value of this parameter can be the name of a field of the FLOAT type.
longtitude_b: the longitude value of Point b. The value of this parameter can be the name of a field of the FLOAT type or a field that is specified in the kvpairs clause in the query string.
latitude_b: the latitude value of Point b. The value of this parameter can be the name of a field of the FLOAT type or a field that is specified in the kvpairs clause in the query string.
outputname: the return value. This parameter is optional. You can specify this parameter to obtain the calculated distance in the search results.
1. Syntax
distance(longitude_a, latitude_a, longtitude_b, latitude_b, output_name)
2. Parameters
3. Return value
The distance between Point a and Point b. Unit: kilometers. The return value is of the FLOAT type.
4. Scenarios
Scenario 1: Search for KFCs within 10 kilometers from the coordinates of a user. In this example, the longitude and latitude are 120.34256 and 30.56982. The lon and lat fields that specify the longitude and latitude of a KFC must be configured as attribute fields. The search results are sorted based on a near-to-far order.
# Use the distance function in a sort clause.
query=default:'KFC'&&
filter=distance(lon,lat,"120.34256","30.56982")<10&&
sort=+distance(lon,lat,"120.34256","30.56982")
# Use the distance function in a fine sort expression.
Alternatively, you can use the kvpairs clause to pass in the coordinates of the user and use the following fine sort expression to sort the search results by distance:
kvpairs=longtitude_in_query:120.34256, latitude_in_query:30.56982
distance(longitude_in_doc, latitude_in_doc, longtitude_in_query, latitude_in_query, distance_value)5. Usage notes
The fields that you reference in the parameters of the function must be configured as attribute fields.
The outputname parameter can be used only in fine sort expressions. This parameter cannot be used in a filter or sort clause. If you specify the outputname parameter, the actual distance value is returned in the variableValue node. The variableValue node is returned only when the response format is set to XML or full JSON. You can specify the format in a config clause by setting the format parameter.