Search()

This operation issues a search on a collection based on the given parameters and returns results.

Status Search(const SearchRequest& request, SearchResponse& response)

Request Syntax

auto request = SearchRequest()
    .WithDatabaseName(db_name)
    .WithCollectionName(collection_name)
    .WithPartitionNames(partition_names)
    .WithOutputFields(output_field_names)
    .WithConsistencyLevel(consistency_level)
    .WithBinaryVectors(vectors)
    .WithFloatVectors(vectors)
    .WithSparseVectors(vectors)
    .WithFloat16Vectors(vectors)
    .WithBFloat16Vectors(vectors)
    .WithEmbeddedTexts(texts)
    .WithInt8Vectors(vectors)
    .WithEmbeddingLists(emb_lists)
    .WithMetricType(metric_type)
    .WithExtraParams(std)
    .WithLimit(limit)
    .WithFilter(filter)
    .WithAnnsField(ann_field)
    .WithFilterTemplates(value)
    .WithOffset(offset)
    .WithRoundDecimal(round_decimal)
    .WithIgnoreGrowing(ignore_growing)
    .WithGroupByField(field_name)
    .WithGroupSize(group_size)
    .WithStrictGroupSize(strict_group_size)
    .WithRadius(radius)
    .WithRangeFilter(filter)
    .WithRerank(ranker)
    .WithTimezone(timezone);

REQUEST METHODS:

• WithDatabaseName(const std::string& db_name)

  Sets the target database name. The default database applies if it is empty.

• WithCollectionName(const std::string& collection_name)

  Sets the name of the collection.

• WithPartitionNames(std::set<std::string>&& partition_names)

  Sets the names of the partitions. If it is empty, the default partition applies.

• AddPartitionName(const std::string& partition_name)

  Adds a partition name.

• WithOutputFields(std::set<std::string>&& output_field_names)

  Sets the output field names.

• AddOutputField(const std::string& output_field)

  Adds an output field.

• WithConsistencyLevel(ConsistencyLevel consistency_level)

  Sets the consistency level.

• AddBinaryVector(const std::string& vector)

  Adds a binary vector to the search request. This method automatically converts the string array to a uint8 array.

• AddFloatVector(const FloatVecFieldData::ElementT& vector)

  Adds a float vector to the search request.

• AddSparseVector(const SparseFloatVecFieldData::ElementT& vector)

  Adds a sparse vector to the search request.

• AddFloat16Vector(const Float16VecFieldData::ElementT& vector)

  Adds a float16 vector to the search request.

• AddBFloat16Vector(const BFloat16VecFieldData::ElementT& vector)

  Adds a bfloat16 vector to the search request.

• AddEmbeddedText(const std::string& text)

  Adds a text to the search request. Only works for a BM25 function.

• AddInt8Vector(const Int8VecFieldData::ElementT& vector)

  Adds an int8 vector to the search request.

• AddEmbeddingList(EmbeddingList&& emb_list)

  Adds an embedding list to the search request on struct field.

• WithBinaryVectors(const std::vector<std::string>& vectors)

  Assigns binary vectors to the search request. This method automatically converts the string array to uint8 array. Note: this method resets the vector list for the request.

• WithFloatVectors(std::vector<FloatVecFieldData::ElementT>&& vectors)

  Assigns float vectors to the search request.

  This method resets the request’s vector list.

• WithSparseVectors(std::vector<SparseFloatVecFieldData::ElementT>&& vectors)

  Assigns sparse vectors to the search request.

  This method resets the request’s vector list.

• WithFloat16Vectors(std::vector<Float16VecFieldData::ElementT>&& vectors)

  Assigns float16 vectors to the search request.

  This method resets the request’s vector list.

• WithBFloat16Vectors(std::vector<BFloat16VecFieldData::ElementT>&& vectors)

  Assigns bfloat16 vectors to the search request.

  This method resets the request’s vector list.

• WithEmbeddedTexts(std::vector<std::string>&& texts)

  Assigns texts to the search request. Only works for a BM25 function.

  This method resets the request’s vector list.

• WithInt8Vectors(std::vector<Int8VecFieldData::ElementT>&& vectors)

  Assigns int8 vectors to the search request.

  This method resets the request’s vector list.

• WithEmbeddingLists(std::vector<EmbeddingList>&& emb_lists)

  Assigns embedding lists to the search request on a struct field.

  This method resets the request’s vector list.

• WithMetricType(::milvus::MetricType metric_type)

  Sets the metric type.

• AddExtraParam(const std::string& key, const std::string& value)

  Adds an additional parameter such as "nlist", "ef".

• WithExtraParams(const std::unordered_map<std::string, std::string>& params)

  Add a set of additional parameters, such as “nlist” and "ef".

• WithLimit(int64_t limit)

  Set search limit (topk).

• WithFilter(std::string filter)

  Sets a filter expression.

• WithAnnsField(const std::string& ann_field)

  Sets the target field of an ann search.

• AddFilterTemplate(std::string key, const nlohmann::json& filter_template)

  Adds a filter template. This takes effect only if WithFilter() is set. Read this page for more about filter templating.

• WithFilterTemplates(std::unordered_map<std::string, nlohmann::json>&& filter_templates)

  Sets filter templates. This takes effect only if WithFilter() is set. Read this page for more about filter templating.

• WithOffset(int64_t offset)

  Sets an offset value.

• WithRoundDecimal(int64_t round_decimal)

  Sets the round decimal value.

• WithIgnoreGrowing(bool ignore_growing)

  Sets whether to ignore growing segments.

• WithGroupByField(const std::string& field_name)

  Sets the group by field value.

• WithGroupSize(int64_t group_size)

  Sets the group size value.

• WithStrictGroupSize(bool strict_group_size)

  Sets the strict group size flag.

• WithRadius(double radius)

  Sets the range radius.

• WithRangeFilter(double filter)

  Sets the range filter.

• WithRerank(const FunctionScorePtr& ranker)

  Sets a reranker. For details, refer to Weighted Ranker, RRF Ranker, Boost Ranker, Decay Ranker, and Model Ranker.

• WithTimezone(const std::string& timezone)

  Sets the timezone. This applies only to the Timestamptz field. For details, refer to this page.

RETURNS:

Status with SearchResponse

Check status.IsOk() to confirm success.

EXCEPTIONS:

• StatusCode

  Check status.Code() and status.Message() for error details.

Example

#include "milvus/MilvusClientV2.h"
auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"http://localhost:19530", "root:Milvus"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

// generate two random query vectors
std::mt19937 rng(std::random_device{}());
std::uniform_real_distribution<float> dist(0.0f, 1.0f);
std::vector<float> q1(dimension), q2(dimension);
std::generate(q1.begin(), q1.end(), [&]() { return dist(rng); });
std::generate(q2.begin(), q2.end(), [&]() { return dist(rng); });
std::vector<std::vector<float>> query_vectors = {q1, q2};

std::string filter_expr = field_age + " > 40";
auto request =
    milvus::SearchRequest()
        .WithCollectionName(collection_name)
        .AddPartitionName(partition_name)
        .WithLimit(5)
        .WithAnnsField(field_face)
        .AddExtraParam(milvus::NPROBE, "10")
        .AddOutputField(field_name)
        .AddOutputField(field_age)
        .WithFilter(filter_expr)
        .WithFloatVectors(std::move(query_vectors))
        // set to BOUNDED level to accept data inconsistency within a time window (default is 5 seconds)
        .WithConsistencyLevel(milvus::ConsistencyLevel::BOUNDED);

milvus::SearchResponse response;
status = client->Search(request, response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

for (auto& result : response.Results().Results()) {
    std::cout << "Result of one target vector:" << std::endl;
    milvus::EntityRows output_rows;
    status = result.OutputRows(output_rows);
    if (!status.IsOk()) {
        std::cout << status.Message() << std::endl;
    }
    for (const auto& row : output_rows) {
        std::cout << "\t" << row << std::endl;
    }
}