search()
This operation conducts a vector similarity search with an optional scalar filtering expression.
public SearchResp search(SearchReq request)
Request Syntax
search(SearchReq.builder()
.collectionName(String collectionName)
.partitionNames(List<String> partitionNames)
.annsField(String annsField)
.topK(int topK)
.filter(String filter)
.outputFields(List<String> outputFields)
.data(List<BaseVector> data)
.offset(long offset)
.limit(long limit)
.roundDecimal(int roundDecimal)
.searchParams(String searchParams)
.guaranteeTimestamp(long guaranteeTimestamp)
.gracefulTime(long gracefulTime)
.consistencyLevel(ConsistencyLevel consistencyLevel)
.ignoreGrowing(boolean ignoreGrowing)
.build()
)
BUILDER METHODS:
collectionName(String collectionName)
The name of an existing collection.
partitionNames(List<String> partitionNames)
A list of partition names.
annsField(String annsField)
The name of the vector field, used when there is more than one vector field. If only one vector field exists, we will use it directly.
topK(int topK)
The number of records to return in the search result. This parameter uses the same syntax as the
limit
parameter, so you should only set one of them.You can use this parameter in combination with
offset
to enable pagination.The sum of this value and
offset
should be less than 16,384.filter(String filter)
A scalar filtering condition to filter matching entities.
You can set this parameter to an empty string to skip scalar filtering. To build a scalar filtering condition, refer to Boolean Expression Rules.
outputFields(List<String> outputFields)
A list of field names to include in each entity in return.
The value defaults to None. If left unspecified, all fields are selected as the output fields.
data(List<BaseVector> data)
A list of vector embeddings.
Milvus searches for the most similar vector embeddings to the specified ones.
BaseVector is a base class for abstract vector classes. The following classes are derived from BaseVector. Choose the correct class as input according to DataType of the vector field.
notes
In Java SDK v2.3.7 or earlier versions, this method is named
distance
. Since Java SDK v2.3.8, this method is renamed asscore
.Class Name
Constructors
Description
FloatVec
FloatVec(List<Float> data)FloatVec(float[] data)
For DataType.FloatVector type field.
BinaryVec
BinaryVec(ByteBuffer data)BinaryVec(byte[] data)
For DataType.BinaryVector type field.
offset(long offset)
The number of records to skip in the query result.
You can use this parameter in combination with
limit
to enable pagination.The sum of this value and
limit
should be less than 16,384.limit(long limit)
The number of records to return in the search result. This parameter uses the same syntax as the
topK
parameter, so you should only set one of them.You can use this parameter in combination with
offset
to enable pagination.The sum of this value and
offset
should be less than 16,384.roundDecimal(int roundDecimal)
The number of decimal places that Milvus rounds the calculated distances to.
The value defaults to -1, indicating that Milvus skips rounding the calculated distances and returns the raw value.
searchParams(Map<String,Object> searchParams)
The parameter settings specific to this operation.
metric_type (String)
The metric type applied to this operation. This should be the same as the one used when you index the vector field specified above.
Possible values are L2, IP, and COSINE.
radius (float)
Determines the threshold of least similarity. When setting
metric_type
toL2
, ensure that this value is greater than that of range_filter. Otherwise, this value should be lower than that of range_filter.range_filter (float)
Refines the search to vectors within a specific similarity range. When setting
metric_type
toIP
orCOSINE
, ensure that this value is greater than that of radius. Otherwise, this value should be lower than that of radius.
For details on other applicable search parameters, refer to In-memory Index and On-disk Index.
guaranteeTimestamp(long guaranteeTimestamp)
A valid timestamp.
If this parameter is set, MilvusZilliz Cloud executes the query only if all entities inserted before this timestamp are visible to query nodes.
notes
This parameter is valid when the default consistency level applies.
gracefulTime(long gracefulTime)
A period of time in ms.
The value defaults to 5000L. If this parameter is set, MilvusZilliz Cloud calculates the guarantee timestamp by subtracting this from the current timestamp.
notes
This parameter is valid when a consistency level other than the default one applies.
consistencyLevel(ConsistencyLevel consistencyLevel)
The consistency level of the target collection.
The value defaults to the one specified when you create the current collection, with options of Strong (0), Bounded (1), Session (2), and Eventually (3).
what is the consistency level?
Consistency in a distributed database specifically refers to the property that ensures every node or replica has the same view of data when writing or reading data at a given time.
Milvus supports four consistency levels: Strong, Bounded Staleness, Session, and Eventually. The default consistency level in Milvus is Bounded Staleness.
You can easily tune the consistency level when conducting a vector similarity search or query to make it best suit your application.
ignoreGrowing(boolean ignoreGrowing)
Whether to ignore growing segments during similarity searches.
RETURN TYPE:
SearchResp
RETURNS:
A **SearchResp object representing specific search results with the specified output fields and relevance score.
PARAMETERS:
searchResults(List<List<SearchResult>>)
A list of SearchResp.SearchResult, the size of searchResults equals the number of query vectors of the search. Each List\<SearchResult\> is a topK result of a query vector. Each SearchResult represents an entity hit by the search. Member of SearchResult:
EXCEPTIONS:
MilvusClientExceptions
This exception will be raised when any error occurs during this operation.
Example
SearchResp searchR = client.search(SearchReq.builder()
.collectionName(collectionName)
.data(Collections.singletonList(new FloatVec(new float[]{1.0f, 2.0f})))
.filter("id < 100")
.topK(10)
.outputFields(Collections.singletonList("*"))
.build());
List<List<SearchResp.SearchResult>> searchResults = searchR.getSearchResults();
System.out.println("\nSearch results:");
for (List<SearchResp.SearchResult> results : searchResults) {
for (SearchResp.SearchResult result : results) {
System.out.printf("ID: %d, Score: %f, %s\n", (long)result.getId(), result.getScore(), result.getEntity().toString());
}
}