The function knn_filter(str vector_fieldname1, str vector_fieldname2, r32 min_score)allows to filter candidates based on vector distance (KNN) between document fields, according to the distance metric defined in the data schema config file.

if the distance score is below min_score, the function will return 0. Otherwise, it will return 1.

Any arithmetic combination (+, *, *, /) of knn_filter()and a variable or a constant is allowed.

min_score can be a dynamic value, included in the query parameters.


  • vector_fieldname1 (str) - the name of the query field to use in the KNN calculation. params[fieldname1] must be of type dense_vector.

  • vector_fieldname2 (str, default=fieldname1) - the name of the document field to use in the KNN calculation. params[fieldname1] must be of type dense_vector. By default vector_fieldname2 is set to vector_fieldname1.

  • min_score (float, default=0) - the score threshold. If the distance score is below this value, distance() will return 0.


  • result (float) - The returned value is 1.0 If the KNN distance between vector_fieldname1 to vector_fieldname2 is greater the min_thershold, and 0.0 otherwise.


def score_function_with_distance(params, doc):
    score = 0
    if match("color"):
        score += rarity_max("color") 
    return score * knn_filter("embedded_image",min_score=0.3)


  • params[vector_fieldname2] and doc[vector_fieldname2] must be indexed using the same metric.

  • The knn_filter function can only be used as part of a return statement. In addition, all other return statements must only return 0, False or none. For example, only return statements of the following types are allowed:

def score_function(params, doc):
    if match("genre"):
    else if match("countries"):
        return False
    score = rarity_max("tags")        
    if score < 1:
        return 0
    return score  + knn_filter("tagline_embedding", "overview_embedding")

The knn_filter() function allows to you to filter based on the KNN score, as part of Hybrid Search Score functions.

Last updated