All Products
Search
Document Center

Vector Retrieval Service for Milvus:Perform vector range searches with DiskANN indexes

Last Updated:Oct 22, 2026

Vector Retrieval Service for Milvus (Milvus) supports range searches on DiskANN indexes. Range searches on DiskANN follow the range search semantics of Milvus: the query vector is the center, radius defines the outer boundary, and range_filter defines the inner boundary. Only vectors within this band are retained, and the most similar limit results are returned. This topic describes how to configure these three parameters, select a value for search_list, and interpret the expected results.

Prerequisites

  • A Milvus instance that supports DiskANN indexes is created. For more information, see Quick start: Create a Milvus instance.

  • A collection containing data is prepared, and a DiskANN index is built on the vector field to search.

  • The instance endpoint, username, and password are available, and the environment in which you run Python can access the endpoint.

  • PyMilvus is installed.

pip install pymilvus
Note

The DiskANN implementation and parameters in Alibaba Cloud Milvus may differ from those in open-source Milvus. For more information, see Capacity-oriented disk index (DiskANN). Examples with small datasets illustrate parameters and results. To evaluate search window tuning, use a dataset comparable in size to your production data.

How range search works

A search with radius specified consists of three steps:

  1. Use the metric of the collection to search for candidate vectors in order of similarity to the query vector, from nearest to farthest. DiskANN performs a graph search in this step rather than a brute-force scan of the entire database.

  2. Retain only vectors whose distance or score falls between radius and range_filter.

  3. Return the K most similar vectors among those retained. K is the value of limit in the request.

If the band contains fewer than K vectors, fewer than K results can be returned. With limit = 3, at most 3 results are returned; the search does not guarantee that all vectors in the band are returned.

By default, filtering and search termination use exact distances calculated from the original vectors. Vectors closer than the inner boundary are excluded, and the search continues. Vectors within the band are retained. The search stops when K results are collected or the next exact distance reaches or exceeds the outer boundary.

Metrics and inequalities

DiskANN supports only the L2, IP, and COSINE metrics.

For a metric in which a smaller distance means greater similarity (L2), the outer boundary value is greater than the inner boundary value:

range_filter <= distance < radius

For metrics in which a larger distance or score means greater similarity (IP and COSINE), the outer boundary value is smaller than the inner boundary value, and radius must be less than range_filter:

radius < distance <= range_filter

Metric

Greater similarity

Band

Without an inner boundary

L2

Smaller distance

range_filter <= d < radius

Set range_filter = 0 or omit the parameter. L2 distances are greater than or equal to 0, so no neighbors within the radius are excluded by the inner boundary.

IP

Larger score

radius < d <= range_filter

Omit range_filter; do not set it to 0.

COSINE

Larger score

radius < d <= range_filter

Omit range_filter; do not set it to 0.

Setting range_filter to 0 to include all entities within the radius applies to metrics such as L2, in which a smaller distance means a closer neighbor. For COSINE and IP, setting range_filter to 0 produces the interval radius < d <= 0, which may return no results. For example, with COSINE, radius = 0.4 and range_filter = 0 exclude vectors with positive similarity scores. The inner boundary is inclusive, and the outer boundary is exclusive: for L2, a distance equal to range_filter is retained, and a distance equal to radius is excluded; for IP and COSINE, a score equal to range_filter is retained, and a score equal to radius is excluded.

Parameters

Parameter

Purpose

Recommendation

radius

Outer boundary

Set the value based on the metric and the preceding table. Ensure that its relationship to range_filter is correct.

range_filter

Inner boundary. Omit this parameter if no inner boundary is required.

For L2, you can set this parameter to 0. For IP and COSINE, the value must be greater than radius if an inner boundary is specified.

limit

Maximum number of results to return; also one of the search termination conditions.

Set K to the number of results your business requires. Increasing this value does not expand the radius.

search_list

Candidate window for graph search; controls search breadth.

For recommended values, see the next section. This parameter does not specify the number of results per page.

search_list does not limit the number of results returned. With limit = 500 and search_list = 100, the search continues along the graph until it collects 500 results within the band, the exact distance exceeds the outer boundary, or graph traversal ends. It does not stop after returning the 100th result. If search_list is omitted or set to a value less than 100, range search adjusts the window to 100. The maximum number of results returned is still limit.

Recommended usage

Keep refinement enabled

Filtering and search termination in a range search depend on original-vector distances. Keep the default refinement configuration:

  • Do not set the query parameter to use_refine = false.

Set search_list based on the neighbor depth of the band

The candidate window should cover the neighbor depth at which the target band lies. Use the following guidelines:

  • If the band includes the nearest neighbors (L2 with range_filter = 0, or IP/COSINE with range_filter omitted), set search_list to at least max(100, limit). When limit is small, from a few dozen to one hundred, a window of 100 provides recall comparable to a standard TopK search.

  • If the inner boundary excludes many nearest neighbors, meaning that range_filter excludes a large number of the closest vectors and the target band lies farther away, increase search_list to the same order of magnitude as the target neighbor depth. If the window is only 100 while the band lies around the several-thousandth nearest neighbors, graph search often fails to reach the band and returns fewer results.

When limit is greater than search_list, results are not truncated, but the candidate window is relatively small, reducing the probability of reaching the Kth neighbor within the band. To improve the stability of recalling K results, set search_list to at least K.

limit controls the number of results

limit specifies the maximum number of results, not the search depth. Once the radius determines the search range, increasing limit only allows more results to be returned from the same band, until all results in the band have been retrieved. If the band contains only 10 vectors, limit = 1000 still yields only about 10 valid results. PyMilvus returns a list of actual hits and does not pad the list to limit entries.

When limit is 16384 or greater, range search still uses graph search rather than the large TopK scan path. A large K and a wide band significantly increase latency. If your business requires only a few dozen results, do not set limit to this order of magnitude.

Fewer than limit results may be returned

Fewer results than requested may be returned in the following two cases:

  • The number of vectors in the band is less than limit.

  • The exact distance has exceeded the outer boundary, and subsequent candidate vectors are farther away.

With PyMilvus, iterate directly over the list of returned hits and use len(res[0]) to count the actual hits. You do not need to reserve a fixed number of result slots based on limit.

If graph search does not cover the target band, fewer results may also be returned. In this case, increase search_list without expanding the radius. When search_list is of the same order of magnitude as the band depth, recall is comparable to that of a standard TopK search with the same window. Within this window, minor ordering differences between estimated and exact distances do not cause results that satisfy the interval conditions to violate them, nor do they consistently cause an entire page of results to be missing.

Examples

The following examples use existing collections: my_collection_cosine, my_collection_l2, and my_collection_ip, with DiskANN indexes that use the COSINE, L2, and IP metrics, respectively. The vector field is named vector, and the sample query vector has 8 dimensions. Replace the endpoint, credentials, collection names, vector field name, and vector dimensions with your actual values, and ensure that the search metric matches the index metric.

COSINE: Retrieve the top 3 results with scores between 0.4 and 0.6

When the default metric is COSINE, radius must be less than range_filter. The following request returns at most 3 results whose scores satisfy 0.4 < score <= 0.6, in descending order of score.

from pymilvus import MilvusClient

client = MilvusClient(uri="http://<your-endpoint>:19530", token="<your-username>:<your-password>")

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

res = client.search(
    collection_name="my_collection_cosine",
    anns_field="vector",
    data=[query_vector],
    limit=3,
    search_params={
        "metric_type": "COSINE",
        "params": {
            "radius": 0.4,
            "range_filter": 0.6,
            "search_list": 100,
        },
    },
)

for hits in res:
    for hit in hits:
        print(hit["id"], hit["distance"])

For limit = 3, you can use search_list = 100. If you change the request to limit = 200, set search_list to at least 200.

L2: Retrieve the top 10 results within radius 100, without an inner boundary

res = client.search(
    collection_name="my_collection_l2",
    anns_field="vector",
    data=[query_vector],
    limit=10,
    search_params={
        "metric_type": "L2",
        "params": {
            "radius": 100.0,
            "range_filter": 0.0,
            "search_list": 100,
        },
    },
)

Returns at most the 10 nearest results that satisfy 0 <= distance < 100.

L2: Exclude close neighbors and retrieve results with distances between 20 and 100

res = client.search(
    collection_name="my_collection_l2",
    anns_field="vector",
    data=[query_vector],
    limit=10,
    search_params={
        "metric_type": "L2",
        "params": {
            "radius": 100.0,
            "range_filter": 20.0,
            "search_list": 100,
        },
    },
)

The returned results satisfy 20 <= distance < 100. If many neighbors have a distance less than 20, increase search_list so that the candidate window covers the neighbor depth excluded by the inner boundary.

IP: Retrieve results with scores between 0.2 and 0.8

res = client.search(
    collection_name="my_collection_ip",
    anns_field="vector",
    data=[query_vector],
    limit=10,
    search_params={
        "metric_type": "IP",
        "params": {
            "radius": 0.2,
            "range_filter": 0.8,
            "search_list": 100,
        },
    },
)

Returns at most the 10 highest-scoring results that satisfy 0.2 < score <= 0.8.

Validate results

The returned results must meet the following conditions:

  • L2: range_filter <= distance < radius

  • IP / COSINE: radius < distance <= range_filter

  • The number of results does not exceed limit.

  • For each query, L2 results are sorted in ascending order of distance, and IP/COSINE results are sorted in descending order of score.

If fewer than limit results are returned, check the interval and the search_list setting. These two factors alone do not confirm that all vectors within the interval have been returned.

Usage notes

  • For COSINE and IP, ensure that the relative values of radius and range_filter are correct. If no inner boundary is required, omit range_filter rather than setting it to 0.

  • search_list controls the candidate window for graph search, not the number of results. The number of results returned is determined by limit and the actual number of hits within the band.

  • Setting use_refine = false in a range search filters the band boundaries using estimated distances, which may reduce recall near the boundaries.

  • Increasing limit does not expand the search range.

  • Range search does not guarantee that every vector in the database within the band is returned. DiskANN uses approximate nearest neighbor (ANN) search to retrieve the top K vectors from nearest to farthest. More distant neighbors that are not reached due to K and search_list are not returned.

Related topics