Change Summary

• add decay functions for sortby
• add validation tests

Decay Functions

Decay functions supplied with sortby params provides functionality to simulate gaussian, linear, and exponential curve behavior and scores the results accordingly.

Usage

Decay functions are used with sortby params and syntax for same can be found below,

sort_by=timestamp(origin: 1728386250, func: exp, scale: -1000, offset: 0, decay: 0.4): asc

Here,

• timestamp is the sort field to be searched,
• origin is the pivot point from where the curve will originate as per param
• func is the decay function name. Currently Typesense supports only gauss, linear, exp, and diff functions.
• scale is non zero integral value by which decay will be applied
• offset is the value from which origin point will be offsetted
• decay is the the rate between [0.0,1.0] at which scores will be decayed.

origin and scale are mandatory params with func name.

decay value if not supplied is defaulted to 0.5

Example

Let's assume following schema,

{
            "name": "products",
            "fields":[
                {"name": "product_name","type": "string"},
                {"name": "timestamp","type": "int64"}
            ]
    }

with the records,

{"product_name": "Samsung Smartphone", "timestamp": 1728383250}
{"product_name": "Vivo Smartphone", "timestamp": 1728384250}
{"product_name": "Oneplus Smartphone", "timestamp": 1728385250}
{"product_name": "Pixel Smartphone", "timestamp": 1728386250}
{"product_name": "Moto Smartphone", "timestamp": 1728387250}

Now we will search with following query

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
"http://localhost:8108/collections/products/documents/search\
?q=smartphone&query_by=product_name&sort_by=timestamp(origin: 1728385250, func: gauss, scale: 1000, decay: 0.5):desc"

we will get response as below,

  {"hits":[{"document":{"id":"2","product_name":"Oneplus Smartphone","timestamp":1728385250}},{"document":{"id":"3","product_name":"Pixel Smartphone","timestamp":1728386250}},{"document":{"id":"1","product_name":"Vivo SmartPhone","timestamp":1728384250}},{"document":{"id":"4","product_name":"Moto Smartphone","timestamp":1728387250}},{"document":{"id":"0","product_name":"Samsung Smartphone","timestamp":1728383250}}]}

Here, we've supplied origin point 1728385250 so it'll get highest score(viz 1.0). Later at every scale value interval (viz 1000), score get reduced by decay value (viz 0.5) and accordingly results are sorted.

PR Checklist

• I have read and signed the Contributor License Agreement.