milvus-logo
LFAI
Home
  • User Guide

Conduct a Vector Similarity Search

This topic describes how to search entities with Milvus.

A vector similarity search in Milvus calculates the distance between query vector(s) and vectors in the collection with specified similarity metrics, and returns the most similar results. You can perform a hybrid search by specifying a boolean expression that filters the scalar field or the primary key field.

The following example shows how to perform a vector similarity search on a 2000-row dataset of book ID (primary key), word count (scalar field), and book introduction (vector field), simulating the situation that you search for certain books based on their vectorized introductions. Milvus will return the most similar results according to the query vector and search parameters you have defined.

Load collection

All search and query operations within Milvus are executed in memory. Load the collection to memory before conducting a vector similarity search.

from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
collection.load()
await milvusClient.loadCollection({
  collection_name: "book",
});
err := milvusClient.LoadCollection(
  context.Background(),   // ctx
  "book",                 // CollectionName
  false                   // async
)
if err != nil {
  log.Fatal("failed to load collection:", err.Error())
}
milvusClient.loadCollection(
  LoadCollectionParam.newBuilder()
          .withCollectionName("book")
          .build()
);
load -c book
curl -X 'POST' \
  'http://localhost:9091/api/v1/collection/load' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "collection_name": "book"
  }'

Prepare search parameters

Prepare the parameters that suit your search scenario. The following example defines that the search will calculate the distance with Euclidean distance, and retrieve vectors from ten closest clusters built by the IVF_FLAT index.

search_params = {
    "metric_type": "L2", 
    "offset": 0, 
    "ignore_growing": False, 
    "params": {"nprobe": 10}
}
const searchParams = {
    params: { nprobe: 1024 }
};
sp, _ := entity.NewIndexIvfFlatSearchParam( // NewIndex*SearchParam func
    10,                                  // searchParam
)

opt := client.SearchQueryOptionFunc(func(option *client.SearchQueryOption) {
    option.Limit = 3
    option.Offset = 0
    option.ConsistencyLevel = entity.ClStrong
    option.IgnoreGrowing = false
})
final Integer SEARCH_K = 2;                       // TopK
final String SEARCH_PARAM = "{\"nprobe\":10, \"offset\":0}";    // Params
search

Collection name (book): book

The vectors of search data(the length of data is number of query (nq), the dim of every vector in data must be equal to vector field’s of collection. You can also import a csv file without headers): [[0.1, 0.2]]

The vector field used to search of collection (book_intro): book_intro

Metric type: L2

Search parameter nprobe's value: 10

The max number of returned record, also known as topk: 10

The boolean expression used to filter attribute []: 

The names of partitions to search (split by "," if multiple) ['_default'] []: 

timeout []:

Guarantee Timestamp(It instructs Milvus to see all operations performed before a provided timestamp. If no such timestamp is provided, then Milvus will search all operations performed to date) [0]: 

Travel Timestamp(Specify a timestamp in a search to get results based on a data view) [0]:
# Search entities based on a given vector.
curl --request POST \
     --url '${MILVUS_HOST}:${MILVUS_PORT}/v1/vector/search' \
     --header 'Authorization: Bearer <TOKEN>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{
        "collectionName": "collection1",
        "vector": [0.0128121, 0.029119, .... , 0.09121]
      }'

# Search entities and return specific fields.
curl --request POST \
     --url '${MILVUS_HOST}:${MILVUS_PORT}/v1/vector/search' \
     --header 'Authorization: Bearer <TOKEN>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{
       "collectionName": "collection1",
       "outputFields": ["id", "name", "feature", "distance"],
       "vector": [0.0128121, 0.029119, .... , 0.09121],
       "filter": "id in (1, 2, 3)",
       "limit": 100,
       "offset": 0
     }'

Output:

{
    "code": 200,
    "data": {}
}
Parameter Description
metric_type Method used to measure the distance between vectors during search. It should be the same as the one specified for the index-building process. See Simlarity Metrics for more information.
offset Number of entities to skip during the search. The sum of this value and limit of the search method should be less than 16384. For example, if you want the 9th and 10th nearest neighbors to the query vector, set limit to 2 and offset to 8.
ignore_growing Whether to ignore growing segments during similarity searches. The value defaults to False, indicating that searches involve growing segments.
params Search parameter(s) specific to the specified index type. See Vector Index for more information. Possible options are as follows:
  • nprobe Indicates the number of cluster units to search. This parameter is available only when index_type is set to IVF_FLAT, IVF_SQ8, or IVF_PQ. The value should be less than nlist specified for the index-building process.
  • ef Indicates the search scope. This parameter is available only when index_type is set to HNSW. The value should be within the range from top_k to 32768.
  • radius Indicates the angle where the vector with the least similarity resides.
  • range_filter Indicates the filter used to filter vector field values whose similarity to the query vector falls into a specific range.
Parameter Description
params Search parameter(s) specific to the index. See Vector Index for more information. Possible options are as follows:
  • nprobe Indicates the number of cluster units to search. This parameter is available only when index_type is set to IVF_FLAT, IVF_SQ8, or IVF_PQ. The value should be less than nlist specified for the index-building process.
  • ef Indicates the search scope. This parameter is available only when index_type is set to HNSW. The value should be within the range from top_k to 32768.
Parameter Description Options
NewIndex*SearchParam func Function to create entity.SearchParam according to different index types. For floating point vectors:
  • NewIndexFlatSearchParam() (FLAT)
  • NewIndexIvfFlatSearchParam(nprobe int) (IVF_FLAT)
  • NewIndexIvfSQ8SearchParam(nprobe int) (IVF_SQ8)
  • NewIndexIvfPQSearchParam(nprobe int) (RNSG)
  • NewIndexHNSWSearchParam(ef int) (HNSW)
For binary vectors:
  • NewIndexBinFlatSearchParam(nprobe int) (BIN_FLAT)
  • NewIndexBinIvfFlatSearchParam(nprobe int) (BIN_IVF_FLAT)
sp Search parameter(s) specific to the index returned by the preceding functions. See Vector Index for more information.
opt Options for ANN searches.
  • Limit Indicates the number of entities to return.
  • Offset Indicates the number of entities to skip during the search. The sum of this parameter and Limit should be less than 16384. For example, if you want the 9th and 10th nearest neighbors to the query vector, set limit to 2 and offset to 8.
  • ConsistencyLevel Indicates the consistency level applied during the search.
  • Ignore Growing Indicates whether to ignore growing segments during similarity searches. The value defaults to False, indicating that searches involve growing segments.
Parameter Description Options
SEARCH_K Number of the most similar results to return. N/A
SEARCH_PARAM Search parameter(s) specific to the index. See Vector Index for more information. Possible options are as follows:
  • nprobe Indicates the number of cluster units to search. This parameter is available only when index_type is set to IVF_FLAT, IVF_SQ8, or IVF_PQ. The value should be less than nlist specified for the index-building process.
  • ef Indicates the search scope. This parameter is available only when index_type is set to HNSW. The value should be within the range from top_k to 32768.
  • metric_type Indicates the metric type used in the search. It should be the same as the one specified when you index the collection.
  • limit Indicates the number of entities to return starting from the last skippped entity.
  • offset Indicates the number of entities to skip during the search. The sum of this value and topK of the withTopK() method should be less than 16384. For example, if you want the 9th and 10th nearest neighbors to the query vector, set topK to 2 and offset to 8.
Parameter Description
collectionName (Required) The name of the collection to which this operation applies.
filter The filter used to find matches for the search
limit The maximum number of entities to return.
The sum of this parameter value and offset should be less than 1024.
The value defaults to 100.
The value ranges from 1 to 100
offset The number of entities to skip in the search results.
The sum of this parameter value and limit should not be greater than 1024.
The maximum value is 1024. For example, if you want the 9th and 10th nearest neighbors to the query vector, set limit to 2 and offset to 8.
outputFields An array of fields to return along with the search results.
vector The query vector in the form of a list of floating numbers.

Search vectors with Milvus. To search in a specific partition, specify the list of partition names.

Milvus supports setting consistency level specifically for a search. The example in this topic sets the consistency level as Strong. You can also set the consistency level as Bounded, Session or Eventually. See Consistency for more information about the four consistency levels in Milvus.

When conducting vector searches using GPU-enabled Milvus, the number of returned entities should meet the following requirements:

  • GPU_IVF_FLAT: The number of returned entities should be less than 256.
  • GPU_IVF_PQ: The number of returned entities should be less than 1024.

For details, refer to In-memory Index

results = collection.search(
    data=[[0.1, 0.2]], 
    anns_field="book_intro", 
    # the sum of `offset` in `param` and `limit` 
    # should be less than 16384.
    param=search_params,
    limit=10,
    expr=None,
    # set the names of the fields you want to 
    # retrieve from the search result.
    output_fields=['title'],
    consistency_level="Strong"
)

# get the IDs of all returned hits
results[0].ids

# get the distances to the query vector from all returned hits
results[0].distances

# get the value of an output field specified in the search request.
hit = results[0][0]
hit.entity.get('title')
const results = await milvusClient.search({
    collection_name: "book",
    vector: [0.1, 0.2],
    filter: null,
    // the sum of `limit` and `offset` should be less than 16384.
    limit: 10,
    offset: 2,
    metric_type: MetricType.L2,
    param: searchParams,
    consistency_level: ConsistencyLevelEnum.Strong,
});
searchResult, err := milvusClient.Search(
    context.Background(),                    // ctx
    "book",                                  // CollectionName
    []string{},                              // partitionNames
    "",                                      // expr
    []string{"book_id"},                     // outputFields
    []entity.Vector{entity.FloatVector([]float32{0.1, 0.2})}, // vectors
    "book_intro",                            // vectorField
    entity.L2,                               // metricType
    10,                                      // topK
    sp,                                      // sp
    opt,
)
if err != nil {
    log.Fatal("fail to search collection:", err.Error())
}
List<String> search_output_fields = Arrays.asList("book_id");
List<List<Float>> search_vectors = Arrays.asList(Arrays.asList(0.1f, 0.2f));

SearchParam searchParam = SearchParam.newBuilder()
        .withCollectionName("book")
        .withConsistencyLevel(ConsistencyLevelEnum.STRONG)
        .withMetricType(MetricType.L2)
        .withOutFields(search_output_fields)
        .withTopK(SEARCH_K)
        .withVectors(search_vectors)
        .withVectorFieldName("book_intro")
        .withParams(SEARCH_PARAM)
        .build();
R<SearchResults> respSearch = milvusClient.search(searchParam);
# Follow the previous step.
# Follow the previous step.
Parameter Description
data Vectors to search with.
anns_field Name of the field to search on.
param Search parameter(s) specific to the index. See Vector Index for more information.
limit Number of the results to return. The sum of this value and offset in param should be less than 16384.
expr Boolean expression used to filter attribute. See Boolean Expression Rules for more information.
output_fields (optional) Name of the field to return. Milvus supports returning the vector field.
consistency_level (optional) Consistency level of the search.
Parameter Description
collection_name Name of the collection to search in.
search_params Parameters (as an object) used for search.
vector / vectors Vectors to search with. Note that you should provide a list of floats if you choose to use vector. Otherwise, you should provide a list of float lists.
vector_type Pre-check of binary or float vectors. 100 for binary vectors and 101 for float vectors.
limit (optional) Number of the results to return. The sum of this value and offset should be less than 16384.
offset (optional) Number of entities to skip. The sum of this value and limit should be less than 16384. For example, if you want the 9th and 10th nearest neighbors to the query vector, set limit to 2 and offset to 8.
filter (optional) Boolean expression used to filter attribute. See Boolean Expression Rules for more information.
output_fields (optional) Name of the field to return. Milvus supports returning the vector field.
Parameter Description Options
ctx Context to control API invocation process. N/A
CollectionName Name of the collection to load. N/A
partitionNames List of names of the partitions to load. All partitions will be searched if it is left empty. N/A
expr Boolean expression used to filter attribute. See Boolean Expression Rules for more information.
output_fields Name of the field to return. Milvus supports returning the vector field. N/A
vectors Vectors to search with. N/A
vectorField Name of the field to search on. N/A
metricType Metric type used for search. This parameter must be set identical to the metric type used for index building.
topK Number of the results to return. The sum of this value and that of offset in WithOffset of opts should be less than 16384. N/A
sp entity.SearchParam specific to the index. N/A
Parameter Description Options
CollectionName Name of the collection to load. N/A
MetricType Metric type used for search. This parameter must be set identical to the metric type used for index building.
OutFields Name of the field to return. N/A
Vectors Vectors to search with. N/A
VectorFieldName Name of the field to search on. N/A
Expr Boolean expression used to filter attribute. See Boolean Expression Rules for more information.
ConsistencyLevel The consistency level used in the query. STRONG, BOUNDED, andEVENTUALLY.

Check the primary key values of the most similar vectors and their distances.

results[0].ids
results[0].distances
console.log(results.results)
fmt.Printf("%#v\n", searchResult)
for _, sr := range searchResult {
    fmt.Println(sr.IDs)
    fmt.Println(sr.Scores)
}
SearchResultsWrapper wrapperSearch = new SearchResultsWrapper(respSearch.getData().getResults());
System.out.println(wrapperSearch.getIDScore(0));
System.out.println(wrapperSearch.getFieldData("book_id", 0));
# Milvus CLI automatically returns the primary key values of the most similar vectors and their distances.

Release the collection loaded in Milvus to reduce memory consumption when the search is completed.

collection.release()
await milvusClient.releaseCollection({  collection_name: "book",});
err := milvusClient.ReleaseCollection(
    context.Background(),                            // ctx
    "book",                                          // CollectionName
)
if err != nil {
    log.Fatal("failed to release collection:", err.Error())
}
milvusClient.releaseCollection(
        ReleaseCollectionParam.newBuilder()
                .withCollectionName("book")
                .build());
release -c book
curl -X 'DELETE' \
  'http://localhost:9091/api/v1/collection/load' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "collection_name": "book"
  }'

Limits

FeatureMaximum limit
Length of a collection name255 characters
Number of partitions in a collection4,096
Number of fields in a collection256
Number of shards in a collection256
Dimensions of a vector32,768
Top K16,384
Target input vectors16,384

What's next