All Products
Search

This Product

    OpenSearch:Sort expression

    Document Center

    OpenSearch:Sort expression

    Last Updated:Apr 01, 2026

    Sort expressions let you define custom scoring logic that controls how OpenSearch Retrieval Engine Edition ranks search results. Use attribute fields from your schema, built-in math functions, and feature functions to build expressions that match your ranking strategy — for example, boosting products by sales volume, penalizing older documents with a time-decay function, or weighting results by geo-distance for location-based services (LBS).

    An expression can run at two stages:

    • Rough sort: First-pass filtering over a large candidate set. Uses the first_formula parameter.

    • Fine sort: Precise re-ranking of the filtered set. Uses the formula parameter.

    You can use both stages in the same query. When combined, the rough sort narrows the candidate set first, then the fine sort re-ranks the result.

    Rough sort expressions process a large number of documents. If you query a large number of documents, specify a suitable number of documents in a rough sort expression. If an expression takes too long to evaluate, the query may time out. Use compute-heavy functions in the fine sort stage.

    Expression elements

    Sort expressions can combine three types of elements:

    TypeDescription
    OperatorsArithmetic, relational, logical, bitwise, conditional, and set operators
    Built-in functionsGeneral-purpose math functions such as ln, pow, sqrt, and now
    Feature functionsDomain-specific ranking signals such as gauss_decay, distance, and text_relevance — see Feature functions

    Operators

    OperationOperatorDescription
    Unary-Negates an expression value. Example: -1, -max(width)
    Arithmetic+, -, *, /Standard arithmetic. Example: width/10
    Relational==, !=, >, <, >=, <=Comparison. Example: width >= 400
    Logicaland, or, !Boolean logic. Examples: width >= 400 and height >= 300, !(a > 1 and b < 2)
    Bitwise&, |, ^Bitwise AND, OR, XOR. Example: 3 & (price ^ pubtime) + (price | pubtime)
    Conditionalif(cond, thenValue, elseValue)Returns thenValue if cond is non-zero; returns elseValue if cond is zero. Example: if(2, 3, 5) returns 3; if(0, 3, 5) returns 5. The cond value cannot be a string (LITERAL or TEXT type); its value range must be the same as INT32.
    INi in [value1, value2, …, valuen]Returns 1 if i is in the set; returns 0 otherwise. Example: 2 in [2, 4, 6] returns 1; 3 in [2, 4, 6] returns 0.

    Built-in functions

    FunctionDescription
    max(a, b)Returns the larger value between a and b.
    min(a, b)Returns the smaller value between a and b.
    ln(a)Returns the natural logarithm of a (log base e).
    log2(a)Returns the logarithm of a with base 2.
    log10(a)Returns the logarithm of a with base 10.
    sin(a)Returns the sine of a.
    cos(a)Returns the cosine of a.
    tan(a)Returns the tangent of a.
    asin(a)Returns the arcsine of a.
    acos(a)Returns the arccosine of a.
    atan(a)Returns the arctangent of a.
    ceil(a)Returns the smallest integer >= a. Example: ceil(4.2) returns 5.
    floor(a)Returns the greatest integer <= a. Example: floor(4.6) returns 4.
    sqrt(a)Returns the square root of a. Example: sqrt(4) returns 2.
    pow(a, b)Returns a raised to the power of b. Example: pow(2, 3) returns 8.
    now()Returns the number of seconds elapsed since 1970-01-01 00:00:00 UTC.
    random()Returns a random value from 0 to 1.

    Feature functions

    Feature functions provide domain-specific ranking signals. Each function is documented on its own page; the table below shows which sort stage each function supports.

    FunctionDescriptionRough sortFine sort
    static_bm25Static text relevance score between a query and a document.SupportedNot supported
    exact_match_boostMaximum weight of a specific search query.SupportedSupported
    timelinessTimeliness score of a document.SupportedSupported
    timeliness_msTimeliness score of a document.SupportedSupported
    normalizeNormalizes a numeric value to the [0, 1] range.SupportedSupported
    distanceSpherical distance between two points. Commonly used for LBS ranking.SupportedSupported
    gauss_decayGaussian decay score based on distance from a reference point.SupportedSupported
    linear_decayLinear decay score based on distance from a reference point.SupportedSupported
    exp_decayExponential decay score based on distance from a reference point.SupportedSupported
    kvpairs_valueValue of a field specified in the kvpairs clause.SupportedSupported
    in/notinReturns whether field values are in or not in a specified value set.SupportedSupported
    tag_matchMatches query keywords against document tags and scores by tag weight.SupportedSupported
    first_phase_scoreScore produced by the rough sort expression. Use in fine sort to build on the first-stage result.Not supportedSupported
    text_relevanceRelevance score between query keywords and a specified field.Not supportedSupported
    field_match_ratioRatio of matched terms to total terms in a field.Not supportedSupported
    query_match_ratioRatio of matched field terms to total query keywords.Not supportedSupported
    fieldterm_proximityProximity between query keywords and field terms.Not supportedSupported
    field_lengthNumber of terms in a field.Not supportedSupported
    query_term_countNumber of terms after the analyzer tokenizes the query.Not supportedSupported
    query_term_match_countNumber of query terms that match document terms.Not supportedSupported
    field_term_match_countNumber of field terms that match the search query.Not supportedSupported
    query_min_slide_windowRatio of matched field terms to the minimum window containing those terms.Not supportedSupported

    Apply a sort expression

    Both expression types use parameters in the kvpairs clause. Add rank_trace:DEBUG to the config clause to inspect the scoring logic in the response.

    Rough sort expression

    Set the expression in the first_formula parameter:

    config=start:0,hit:10,rank_trace:DEBUG,format:json&&query=default:'Search'&&kvpairs=first_formula:price*0.1

    Fine sort expression

    Set the expression in the formula parameter:

    config=start:0,hit:10,rank_trace:DEBUG,format:json&&query=default:'Search'&&kvpairs=formula:price*0.1