The chapter introduces how to perform vector range search which will compare distances between vectors then get the result in specified distance range. Range search has the same API as vector similarity search, however, there are 2 additional items should be specified: radius and range_filter. The indexes available in range search currently are listed below:

FLAT
IVF_FLAT
IVF_SQ
IVF_PQ
HNSW
BIN_FLAT
BIN_IVF
BIN_HNSW
SPARSE_HNSW

In range search, radius and range_filter specify the distance filter range, which is listed below according to similarity metrics:

Similarity Metrics	radius (Float, required)	range_filter (Float, optional)
L2	Returns data with vector distance less than a give radius	Returns data with vector distances less than a given radius but greater than the range_filter; where the range_filter should be less than the radius
IP / Cosine	Returns data with vector distance greater than a give radius	Returns data with vector distances greater than a given radius but less than the range_filter; where the range_filter should be greater than the radius

Table 47 Filter Range for Vector Range Search (Restful API)

With Radius

curl -u shiva:shiva -XGET 'localhost:8902/hippo/v1/{table}/_search?pretty' -H 'Content-Type: application/json' -d'{
  "output_fields": ["book_id"],
  "search_params": {
    "anns_field": "book_intro",
    "topk": 2,
    "params": {
      "k_factor" : 100,
      "radius": 10
    }
  },
  "vectors": [ [0.1,0.2], [0.3, 0.4] ],
  "only_explain" : false
}';

Result:

{
  "num_queries" : 2,
  "top_k" : 2,
  "results" : [
    {
      "query" : 0,
      "fields_data" : [
        {
          "field_name" : "book_id",
          "field_values" : [1,2]
        }
      ],
      "scores" : [1.45,4.25]
    },
    {
      "query" : 1,
      "fields_data" : [
        {
          "field_name" : "book_id",
          "field_values" : [1,2]
        }
      ],
      "scores" : [0.85,3.25]
    }
  ]
}

With Radius and Range_filter

curl -u shiva:shiva -XGET 'localhost:8902/hippo/v1/{table}/_search?pretty' -H 'Content-Type: application/json' -d'{
  "output_fields": ["book_id"],
  "search_params": {
    "anns_field": "book_intro",
    "topk": 2,
    "params": {
      "k_factor" : 100,
      "radius": 10,
      "range_filter": 3
    }
  },
  "vectors": [ [0.1,0.2], [0.3, 0.4] ],
  "only_explain" : false
}';

Result:

{
  "num_queries" : 2,
  "top_k" : 2,
  "results" : [
    {
      "query" : 0,
      "fields_data" : [
        {
          "field_name" : "book_id",
          "field_values" : [2]
        }
      ],
      "scores" : [4.25]
    },
    {
      "query" : 1,
      "fields_data" : [
        {
          "field_name" : "book_id",
          "field_values" : [2]
        }
      ],
      "scores" : [3.25]
    }
  ]
}