Skip to main content

Range Search

A range search improves search result relevancy by restricting the distance or score of the returned entities within a specific range. This page helps you understand what range search is and the procedures to conduct a range search.

Overview​

When executing a Range Search request, Zilliz Cloud uses the most similar vectors to the query vector from the ANN Search results as the center, with the radius specified in the Search request as the outer circle's radius, and the range_filter as the inner circle's radius to draw two concentric circles. All vectors with similarity scores that fall within the annular region formed by these two concentric circles will be returned. Here, the range_filter can be set to 0, indicating that all entities within the specified similarity score (radius) will be returned.

Sewjwp5DShFgKAbC1Mwcrr7enOD

The above diagram shows that a range search request carries two parameters: radius and range_filter. Upon receiving a range search request, Zilliz Cloud does the following:

  • Use the specified metric type (COSINE) to find all vector embeddings most similar to the query vector.

  • Filter the vector embeddings whose distances or scores to the query vector fall within the range specified by the radius and range_filter parameters.

  • Return the top-K entities from the filtered ones.

The way to set radius and range_filter varies with the metric type of the search. The following table lists the requirements for setting these two parameters with different metric types.

Metric TypeDenotationsRequirements for Setting radius and range_filter
L2A smaller L2 distance indicates a higher similarity.To ignore the most similar vector embeddings, ensure that
range_filter <= distance < radius
IPA greater IP distance indicates a higher similarity.To ignore the most similar vector embeddings, ensure that
radius < distance <= range_filter
COSINEA greater COSINE distance indicates a higher similarity.To ignore the most similar vector embeddings, ensure that
radius < distance <= range_filter
JACCARDA smaller Jaccard distance indicates a higher similarity.To ignore the most similar vector embeddings, ensure that
range_filter <= distance < radius
HAMMINGA smaller Hamming distance indicates a higher similarity.To ignore the most similar vector embeddings, ensure that
range_filter <= distance < radius

Examples​

This section demonstrates how to conduct a range search. The search requests in the following code snippets do not carry a metric type, indicating the default metric type COSINE applies. In this case, ensure that the radius value is smaller than the range_filter value.

In the following code snippets, set radius to 0.4 and range_filter to 0.6 so that Zilliz Cloud returns all entities whose distances or scores to the query vector fall within 0.4 to 0.6.

python
from pymilvus import MilvusClient

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN"
)

query_vector = [0.3580376395471989, -0.6023495712049978, 0.18414012509913835, -0.26286205330961354, 0.9029438446296592]

res = client.search(
    collection_name="my_collection",
    data=[query_vector],
    limit=3,
    search_params={
        "params": {
            "radius": 0.4,
            "range_filter": 0.6
        }
    }
)

for hits in res:
    print("TopK results:")
    for hit in hits:
        print(hit)
📘Notes

If the query vectors already exist in the target collection, consider using ids instead of retrieving them before searches. For details, refer to Primary-Key Search.

Ctrl I