Skip to main content

hybridSearch()

The MilvusClient interface. This method conducts an approximate nearest neighbor (ANN) search on multiple vector fields and returns search results after reranking.

R<SearchResults> hybridSearch(HybridSearchParam requestParam);

HybridSearchParam

Use the HybridSearchParam.Builder to construct a HybridSearchParam object.

import io.milvus.param.dml.HybridSearchParam;
HybridSearchParam.Builder builder = HybridSearchParam.newBuilder();

Methods of HybridSearchParam.Builder:

Method

Description

Parameters

withCollectionName(collectionName)

Set the collection name. Collection name cannot be empty or null.

collectionName: The target collection name.

withDatabaseName(String databaseName)

Sets the database name. database name can be null for default database.

databaseName: The database name.

withConsistencyLevel(ConsistencyLevelEnum consistencyLevel)

Sets the search consistency level(Optional).
If the level is not set, will use the default consistency level of the collection.

consistencyLevel: The consistency level used in the search.

withPartitionNames(List<String> partitionNames)

Sets partition names list to specify search scope (Optional).

partitionNames: The name list of partitions to be searched.

addPartitionName(String partitionName)

Adds a partition to specify search scope (Optional).

partitionName: A partition name to be searched.

withOutFields(List<String> outFields)

Specifies output scalar fields (Optional).


outFields: The name list of fields to be outputed.

addOutField(String fieldName)

Specifies an output scalar field (Optional).

fieldName: An output field name.

withTopK(Integer topK)

Set topK value of ANN search.
Avaiable range: [1, 16384]

topK: The topk value.

withRoundDecimal(Integer decimal)

Specifies the decimal place for returned distance.
Avaiable range: [-1, 6]
Default value is -1, return all digits.

decimal: How many digits reserved after the decimal point.

addSearchRequest(AnnSearchParam searchParam)

Adds a vector search request for a vector field. You can add

searchParam: An AnnSearchParam object.

withRanker(BaseRanker ranker)

Set a ranker for rearranging number of limit results.
Avaiable:
- RRFRanker
- WeightedRanker

ranker: The concrete ranker object.

build()

Construct a SearchParam object.

N/A

The HybridSearchParam.Builder.build() can throw the following exceptions:

  • ParamException: error if the parameter is invalid.

AnnSearchParam

The sub-request of hybridSearch().

Use the AnnSearchParam.Builder to construct an AnnSearchParam object.

import io.milvus.param.dml.AnnSearchParam;
AnnSearchParam.Builder builder = AnnSearchParam.newBuilder();

Methods of AnnSearchParam.Builder:

Method

Description

Parameters

withExpr(String expr)

Set the expression to filter scalar fields before searching(Optional).For more information please refer to this doc.

expr: The expression to filter scalar fields.

withMetricType(MetricType metricType)

Set metric type of ANN search.
Default value is MetricType.None, which means let the server determine the defaul metric type. Please refer to MetricType in Misc.

metricType: The metric type to search.

withVectorFieldName(String vectorFieldName)

Set target vector field by name. Field name cannot be empty or null.

vectorFieldName: The target vector field name to do ANN search.

withTopK(Integer topK)

Set topK value of ANN search.
Avaiable range: [1, 16384]

topK: The topk value.

withParams(String params)

Specifies the parameters of search in JSON format. The followings are valid keys of param:
1. special parameters for index, such as "nprobe", "ef", "search_k"
2. metric type with key "metric_type" and a string value such as "L2", "IP".
3. offset for pagination with key "offset" and an integer value

params: A JSON format string for extra parameters.

withFloatVectors(List<List<Float>gt; vectors)

Set the target vectors to search FloatVector field. Up to 16384 vectors allowed.
Note: this method will reset the target vectors of SearchParam. To input vectors, call it only once.

vectors: The target vectors

withBinaryVectors(List<ByteBuffer> vectors)

Set the target vectors to search BinaryVector field. Up to 16384 vectors allowed.
Note: this method will reset the target vectors of SearchParam. To input vectors, call it only once.

vectors: The target vectors

withFloat16Vectors(List<ByteBuffer> vectors)

Set the target vectors to search Float16Vector field. Up to 16384 vectors allowed.
Note: this method will reset the target vectors of SearchParam. To input vectors, call it only once.

vectors: The target vectors

withBFloat16Vectors(List<List<Float>gt; vectors)

Set the target vectors to search BFloat16Vector field. Up to 16384 vectors allowed.
Note: this method will reset the target vectors of SearchParam. To input vectors, call it only once.

vectors: The target vectors

withSparseFloatVectors(List<SortedMap<Long, Float>gt; vectors)

Set the target vectors to search SparseFloatVector field. Up to 16384 vectors allowed.
Note: this method will reset the target vectors of SearchParam. To input vectors, call it only once.

vectors: The target vectors

build()

Construct a SearchParam object.

N/A

RRFRanker

The RRF reranking strategy, which merges results from multiple searches, favoring items that consistently appear.

Use the RRFRanker.Builder to construct an RRFRanker object.

import io.milvus.param.dml.ranker.RRFRanker;
RRFRanker.Builder builder = RRFRanker.newBuilder();

Methods of RRFRanker.Builder:

Method

Description

Parameters

withK(Integer k)

Sets k factor for RRF. Value cannot be negative. Default value is 60.
score = 1 / (k + float32(rank_i+1))
rank_i is the rank in each field

k: The k factor value.

build()

Construct a RRFRanker object.

N/A

WeightedRanker

The average weighted scoring reranking strategy, which prioritizes vectors based on relevance, averaging their significance.

Use the WeightedRankerWeightedRanker.Builder to construct a WeightedRanker object.

import io.milvus.param.dml.ranker.WeightedRanker;
WeightedRanker.Builder builder = WeightedRanker.newBuilder();

Methods of WeightedRanker.Builder:

Method

Description

Parameters

withWeights(List<Float> weights)

Assign weights for each AnnSearchParam. The length of weights must be equal to number of AnnSearchParam.
You can assign any float value for weight, the sum of weight values can exceed 1.
The distance/similarity values of each field will be mapped into a range of [0,1],
and score = sum(weights[i] * distance_i_in_[0,1]).

weights: The weight values.

build()

Construct a WeightedRanker object.

N/A

Returns

This method catches all the exceptions and returns an R<SearchResults> object.

  • If the API fails on the server side, it returns the error code and message from the server.

  • If the API fails by RPC exception, it returns R.Status.Unknown and the error message of the exception.

  • If the API succeeds, it returns valid SearchResults held by the R template. You can use SearchResultsWrapper to get the results.

Example

import io.milvus.param.dml.*;
import io.milvus.param.dml.ranker.*;
import io.milvus.grpc.SearchResults;

AnnSearchParam req1 = AnnSearchParam.newBuilder()
.withVectorFieldName(FLOAT_VECTOR_FIELD)
.withFloatVectors(floatVectors)
.withMetricType(MetricType.IP)
.withParams("{\"nprobe\": 32}")
.withTopK(10)
.build();

AnnSearchParam req2 = AnnSearchParam.newBuilder()
.withVectorFieldName(BINARY_VECTOR_FIELD)
.withBinaryVectors(binaryVectors)
.withMetricType(MetricType.HAMMING)
.withTopK(15)
.build();

HybridSearchParam searchParam = HybridSearchParam.newBuilder()
.withCollectionName(COLLECTION_NAME)
.addOutField(FLOAT_VECTOR_FIELD)
.addSearchRequest(req1)
.addSearchRequest(req2)
.withTopK(5)
.withConsistencyLevel(ConsistencyLevelEnum.STRONG)
.withRanker(RRFRanker.newBuilder()
.withK(2)
.build())
.build();

R<SearchResults> response = milvusClient.hybridSearch(searchParam);
if (response.getStatus() != R.Status.Success.getCode()) {
System.out.println(response.getMessage());
}