PyMilvus Documentation

In the context of L2_RERANK stages, Milvus provides special system names:

• Readable system inputs: $id, $score (used to access the original ID and the initial search score/distance).
• Writable system outputs: $score (used to overwrite the search score with a new calculated value).

Important Rules:

1. Do not request $score in output_fields: It is handled automatically. The final reranked value is returned in the standard distance or score field of the search result.
2. Temporary variables must NOT use the $ prefix: If you want to create a temporary variable, use a standard name. Using a $ prefix for a temporary variable in an L2 Search is invalid.

Valid Example:

# Using $score to read and then overwriting it
chain.map("tmp_val", fn.decay(col("ts"), ...))
    .map("$score", fn.num_combine(col("$score"), col("tmp_val"), mode="sum"))

# Using a custom name for a temporary variable
chain.map("my_temp_score", fn.num_combine(col("$score"), col("ts"), mode="sum"))

The Function Chain API allows you to describe score adjustment and rerank operations (like numeric combination, decay, model reranking, and sorting) as a typed, ordered plan. This plan is passed to the search method via the function_chains parameter.

Key Concepts:

• Stage: For ordinary L2 search, use FunctionChainStage.L2_RERANK.
• Builder Pattern: Use a fluent interface to chain operations like .map(), .sort(), and .limit().
• Arguments: Use col(name) to reference collection fields, temporary variables, or system values like $score.
• System Values: $score is a special system value representing the current search score, passed as a typed column reference.
• Temporary Variables: You can create temporary values by mapping an expression to a custom name (e.g., "freshness") and then referencing that name in subsequent steps of the chain.

from pymilvus import FunctionChain, FunctionChainStage, MilvusClient
from pymilvus.function_chain import col, fn

client = MilvusClient(uri="http://localhost:19530")

# Define a chain that combines scores and sorts
chain = (
    FunctionChain(stage=FunctionChainStage.L2_RERANK, name="l2_score_plus_ts")
    .map("$score", fn.num_combine(col("$score"), col("ts"), mode="sum"))
    .sort(col("$score"), desc=True)
)

# Execute search with the chain
res = client.search(
    collection_name="my_collection",
    data=[query_vector],
    anns_field="vector",
    search_params={},
    output_fields=["doctype"],
    function_chains=[chain],
)

A MilvusClient holds an alias to a Milvus server connection. Understanding how these connections are shared is critical for resource management and avoiding runtime errors.

Connection Sharing Rules

• Shared Connections: MilvusClient objects with the same uri and authentication reuse the same underlying connection to the Milvus server. This applies even if they use different db_name values; each client maintains its own database context, but they share the connection alias.
• Unique Connections: MilvusClient objects with different uri or different authentication credentials do not share connections.

The Impact of close()

Because multiple clients may share the same connection alias, calling .close() on one MilvusClient instance will close the underlying connection for all other client instances sharing that same alias. This will cause subsequent calls on the other clients to fail with an exception.

import threading
from pymilvus import MilvusClient

URI = "http://localhost:19530"
TEST_DB = "test_DB"

# Example: Sharing connections across different databases
c = MilvusClient(uri=URI)
c.create_database(TEST_DB)
c_testdb = MilvusClient(uri=URI, db_name=TEST_DB)

# c and c_testdb share the same connection (same alias), but use different databases
print(f"alias for c:        {c._using}, results of c.list_collections: {c.list_collections()}")
print(f"alias for c_testdb: {c_testdb._using}, results of c_testdb.list_collections: {c_testdb.list_collections()}")

# Closing c_testdb affects c because they share the same connection
c_testdb.close()
try:
    print(f"results of c.list_collections: {c.list_collections()}")
except Exception as ex:
    print(f"c is also affected because they share the same connection, exception: {ex}")

The Function Chain API allows you to perform complex operations on search results (like score manipulation, sorting, and limiting) directly within the Milvus server. This is achieved by chaining operators like map, sort, and limit onto a FunctionChain object, which is then passed to a SearchRequest.

Key Concepts

• Operators: Operations like map, sort, and limit that transform the result set.
• Column References: Use the col() helper to reference fields. Use col("$score") to reference the system-generated score.
• Function Factories: Use the fn module to create expressions for mathematical or logical operations (e.g., num_combine, decay, round_decimal).
• Chaining: The API uses a fluent builder pattern where method calls are chained to define the sequence of operations.

Constraints and Error Handling

• Ranker Conflict: You cannot use ranker (or function_score) and function_chains together in the same request. If you use function chains, the ranking logic is handled within the chain.
• Hybrid Search: Currently, function_chains is not supported for hybrid search.
• Error Types: Input validation errors (like invalid column names or unsupported types) will raise a ParamError.

To ensure stable and performant connection management in PyMilvus, follow these best practices:

When using default behavior (shared connections):

• Do not close shared clients: Since multiple MilvusClient objects might share the same connection, calling .close() on one can break all others. Avoid closing individual clients if they were initialized with the same uri and authentication unless you are certain no other part of your application is using that connection.

When using customized aliases (unique connections):

• Explicitly close clients: Ensure you call .close() when a client with a custom alias is no longer needed to free up resources.
• Check dependencies: Before closing a client, ensure no other active components require that specific connection.
• Reuse connections: Avoid creating short-lived connections. It is more efficient to reuse existing MilvusClient instances whenever possible.