milvus-logo
LFAI
< Docs
  • Java
    • v2

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 as score.

    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 to L2, 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 to IP or COSINE, 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());
    }
}
Feedback

Was this page helpful?