Skip to main content
Version: User Guides (Cloud)

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 Type

Denotations

Requirements for Setting radius and range_filter

L2

A smaller L2 distance indicates a higher similarity.

To ignore the most similar vector embeddings, ensure that

range_filter <= distance < radius

IP

A greater IP distance indicates a higher similarity.

To ignore the most similar vector embeddings, ensure that

radius < distance <= range_filter

COSINE

A greater COSINE distance indicates a higher similarity.

To ignore the most similar vector embeddings, ensure that

radius < distance <= range_filter

JACCARD

A smaller Jaccard distance indicates a higher similarity.

To ignore the most similar vector embeddings, ensure that

range_filter <= distance < radius

HAMMING

A 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.

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)