Skip to main content

Use Large TopK

A Zilliz Cloud collection allows you to retrieve up to 16,384 entities in a search or query result. To retrieve more entities beyond the topK limit, you can set the query mode to allow Zilliz Cloud to include millions of entities in a single search or query result, instead of using complex and time-consuming iterators.

Notes

This feature is available for Zilliz Cloud clusters that are compatible with Milvus v2.6.x. If you would like to try this feature, please get in touch with us.

Overview​

By default, a Zilliz Cloud collection supports a maximum topK of 16,384 in search or query operations. When you need to retrieve more entities in a single request, such as batch similarity search or data mining scenarios, you can enable the Large TopK mode by setting the query_mode property to large_topk on your collection. This raises the topK limit to 1,000,000 (one million) entities.

Enabling Large TopK changes the underlying index strategy from the default Auto Index to IVF (Inverted File Index) with RaBitQ deep compression, which is optimized for high-recall, large-range retrieval at the cost of small-K query performance.

When to use Large TopK​

Large TopK is designed for scenarios where you need to retrieve a very large number of similar entities in a single search, such as:

  • Batch similarity search: Find the top 100,000 or 1,000,000 most similar items for a given query vector.

  • Data mining and analysis: Extract large candidate sets for downstream processing, filtering, or model training.

  • Regression testing preparation: Retrieve large result sets to build test corpora for simulation teams.

For interactive, latency-sensitive online queries with small topK (e.g., top 10 or top 100), the default query mode is recommended.

Prerequisites and trade-offs​

Before enabling Large TopK, be aware of the following trade-offs:

  • Small-K performance degradation: After switching to large_topk, small-K queries (K < 16,384) will experience increased latency and reduced recall compared to the default mode.

  • Query latency: Large TopK queries have significantly higher latency than standard queries. A topK of 100,000 may take several seconds, and a topK of 1,000,000 may take minutes.

  • Resource usage: A single large TopK query can consume several gigabytes of memory for result sorting. On Perf clusters, this may affect other queries running on the same cluster.

  • Offline preference: For batch workloads, consider using an On-demand Compute database. Databases use on-demand CUs and do not affect online services.

  • Index rebuild required: If your collection already has a vector index, you must release and drop the existing index before enabling Large TopK. Search will be unavailable during the rebuild.

Enable Large TopK​

If you know your collection will require Large TopK, specify it at creation time to avoid the cost of switching later:

python
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="your_uri", token="your_token")

schema = client.create_schema(auto_id=False)
schema.add_field("id", DataType.INT64, is_primary=True)
schema.add_field("scenario_id", DataType.VARCHAR, max_length=64)
schema.add_field("title", DataType.VARCHAR, max_length=128)
schema.add_field("vector", DataType.FLOAT_VECTOR, dim=4)

index_params = client.prepare_index_params()
index_params.add_index(field_name="vector", index_name="vector_idx", index_type="AUTOINDEX", metric_type="COSINE")

client.create_collection(
    collection_name="scenarios_corpus",
    schema=schema,
    index_params=index_params,
    properties={"query_mode": "large_topk"}
)

On an existing collection​

For an existing collection without a vector index, you can enable Large TopK directly:

python
from pymilvus import MilvusClient

client = MilvusClient(uri="your_uri", token="your_token")

# 1. Enable Large TopK
client.alter_collection_properties(
    collection_name="scenarios_corpus",
    properties={"query_mode": "large_topk"}
)

# 2. Create the vector index and load the collection
index_params = client.prepare_index_params()
index_params.add_index(field_name="vector", index_name="vector_idx", index_type="AUTOINDEX", metric_type="COSINE")
client.create_index(collection_name="scenarios_corpus", index_params=index_params)
client.load_collection(collection_name="scenarios_corpus")

For an existing collection with a vector index, you must first drop the index, then enable the mode, and finally recreate the index:

python
from pymilvus import MilvusClient

client = MilvusClient(uri="your_uri", token="your_token")

# 1. Release and drop the existing index
client.release_collection(collection_name="scenarios_corpus")
client.drop_index(collection_name="scenarios_corpus", index_name="vector_idx")

# 2. Enable Large TopK
client.alter_collection_properties(
    collection_name="scenarios_corpus",
    properties={"query_mode": "large_topk"}
)

# 3. Recreate the index and load the collection
index_params = client.prepare_index_params()
index_params.add_index(field_name="vector", index_name="vector_idx", index_type="AUTOINDEX", metric_type="COSINE")
client.create_index(collection_name="scenarios_corpus", index_params=index_params)
client.load_collection(collection_name="scenarios_corpus")

Check current query mode​

python
from pymilvus import MilvusClient

client = MilvusClient(uri="your_uri", token="your_token")
info = client.describe_collection(collection_name="scenarios_corpus")
query_mode = info["properties"].get("query_mode")  # None means default mode

Disable Large TopK​

To return to the default query mode, drop the query_mode property. Note that this also requires releasing and dropping the existing index first:

python
from pymilvus import MilvusClient

client = MilvusClient(uri="your_uri", token="your_token")

# 1. Release and drop the existing index
client.release_collection(collection_name="scenarios_corpus")
client.drop_index(collection_name="scenarios_corpus", index_name="vector_idx")

# 2. Drop query_mode to return to the default mode
client.drop_collection_properties(
    collection_name="scenarios_corpus",
    property_keys=["query_mode"]
)

# 3. Recreate the index and load the collection
index_params = client.prepare_index_params()
index_params.add_index(field_name="vector", index_name="vector_idx", index_type="AUTOINDEX", metric_type="COSINE")
client.create_index(collection_name="scenarios_corpus", index_params=index_params)
client.load_collection(collection_name="scenarios_corpus")

Once Large TopK is enabled, use the standard search method with a large limit value:

Online search (Serving Cluster)​

python
from pymilvus import MilvusClient

client = MilvusClient(uri="your_uri", token="your_token")
query_vector = [0.1, 0.2, 0.3, 0.4]

results = client.search(
    collection_name="scenarios_serving",
    data=[query_vector],
    limit=500000
)

Offline search (On-demand Compute)​

python
from pymilvus import MilvusClient

client = MilvusClient(uri="your_uri", token="your_token")
query_vector = [0.1, 0.2, 0.3, 0.4]

results = client.search(
    collection_name="scenarios_corpus",
    data=[query_vector],
    limit=500000
)

Export search results​

There is no dedicated export API for Large TopK results. You can compose existing capabilities to write results to a Managed Volume:

python
import pyarrow as pa
import pyarrow.parquet as pq

# Configure a Zilliz Cloud Managed Volume client as volume_file_manager.
writer = None
try:
    for i, qvec in enumerate(query_vectors):
        results = client.search(
            collection_name="scenarios_corpus",
            data=[qvec],
            limit=100000,
            output_fields=["scenario_id", "title"]
        )

        rows = [
            {
                "query_id": i,
                "rank": j,
                "scenario_id": hit["entity"].get("scenario_id"),
                "title": hit["entity"].get("title")
            }
            for j, hit in enumerate(results[0])
        ]
        table = pa.Table.from_pylist(rows)

        if writer is None:
            writer = pq.ParquetWriter("/tmp/results.parquet", table.schema)
        writer.write_table(table)
finally:
    if writer is not None:
        writer.close()

volume_file_manager.upload_file_to_volume(
    source_file_path="/tmp/results.parquet",
    target_volume_path="results/batch.parquet"
)

Performance expectations​

The following table summarizes the performance characteristics of Large TopK queries:

MetricDefault modeLarge TopK mode
TopK limit16,3841,000,000
Small-K latencyMillisecondsHigher (degraded)
Large-K latencyNot supportedSeconds to minutes
Memory per queryLowUp to several GB
ConcurrencyHighLimited (queued)
Best forOnline interactionBatch, data mining

Zilliz Cloud applies concurrency control to Large TopK queries to prevent resource exhaustion. Requests that exceed the concurrency limit are queued and processed when resources become available.

Limitations​

  • Switching query modes requires rebuilding the vector index. During the rebuild, search is unavailable for the collection.

  • Large TopK is a collection-level setting. All indexes on the collection are affected.

  • Three cluster types (Performance-optimized, Capacity-optimized, and Tiered Storage) all support Large TopK.

FAQ​

Q: Can I switch back and forth frequently?

Technically, yes, but it is not recommended. Each switch requires releasing, dropping, and recreating the index, during which search is unavailable. In an on-demand cluster, each rebuild also incurs Index Build CU charges.

Was this page helpful?
Ctrl I