version 0.5.0 (#260)

* 0.5.0

* Epsilon runtime parameter MOD-4165 (#257)

* Extend query result API (#261)

* add required api's for metirc iterator

* Multi-Value - HNSW - enable range queries (#255)

* implement and test results_container wrapper

* added support for range query on HNSW multi-value

* adjusted tests

* added flow test

* flow test improvement

* review fixes

* small improvements

* uses smart pointers

* add range support to multi-value flat index

* fixed timeout return

* fixed memory leak

* rebase with unique_ptr and fix

* review fixes

Co-authored-by: meiravgri <meirav.grimberg@redis.com>

Co-authored-by: alonre24 <alonreshef24@gmail.com>
Co-authored-by: GuyAv46 <47632673+GuyAv46@users.noreply.github.com>
Co-authored-by: meiravgri <meirav.grimberg@redis.com>

Author: 4 people

src/VecSim/algorithms/brute_force/brute_force.h

@@ -4,6 +4,7 @@
 #include "VecSim/vec_sim_index.h"
 #include "VecSim/spaces/spaces.h"
 #include "VecSim/utils/vecsim_stl.h"
+#include "VecSim/utils/vecsim_results_container.h"
 #include "VecSim/algorithms/brute_force/brute_force_factory.h"
 #include "VecSim/spaces/spaces.h"
 #include "VecSim/query_result_struct.h"
@@ -67,6 +68,10 @@ class BruteForceIndex : public VecSimIndexAbstract<DistType> {
     virtual inline vecsim_stl::abstract_priority_queue<DistType, labelType> *
     getNewMaxPriorityQueue() = 0;
 
+    // inline label to id setters that need to be implemented by derived class
+    virtual inline std::unique_ptr<vecsim_stl::abstract_results_container>
+    getNewResultsContainer(size_t cap) const = 0;
+
     // inline label to id setters that need to be implemented by derived class
     virtual inline void replaceIdOfLabel(labelType label, idType new_id, idType old_id) = 0;
     virtual inline void setVectorId(labelType label, idType id) = 0;
@@ -291,26 +296,27 @@ BruteForceIndex<DataType, DistType>::rangeQuery(const void *queryBlob, double ra
     }
 
     // Compute scores in every block and save results that are within the range.
-    rl.results =
-        array_new<VecSimQueryResult>(10); // Use 10 as the initial capacity for the dynamic array.
+    auto res_container =
+        getNewResultsContainer(10); // Use 10 as the initial capacity for the dynamic array.
 
     DistType radius_ = DistType(radius);
     idType curr_id = 0;
+    rl.code = VecSim_QueryResult_OK;
     for (auto vectorBlock : this->vectorBlocks) {
         auto scores = computeBlockScores(vectorBlock, queryBlob, timeoutCtx, &rl.code);
         if (VecSim_OK != rl.code) {
-            return rl;
+            break;
         }
         for (size_t i = 0; i < scores.size(); i++) {
             if (scores[i] <= radius_) {
-                auto res = VecSimQueryResult{getVectorLabel(curr_id), scores[i]};
-                rl.results = array_append(rl.results, res);
+                res_container->emplace(getVectorLabel(curr_id), scores[i]);
             }
             ++curr_id;
         }
     }
-    assert(curr_id == this->count);
-    rl.code = VecSim_QueryResult_OK;
+    // assert only if the loop finished iterating all the ids (we didn't get rl.code != VecSim_OK).
+    assert((rl.code != VecSim_OK || curr_id == this->count));
+    rl.results = res_container->get_results();
     return rl;
 }
 

src/VecSim/algorithms/brute_force/brute_force_multi.h

@@ -19,9 +19,14 @@ class BruteForceIndex_Multi : public BruteForceIndex<DataType, DistType> {
     int addVector(const void *vector_data, labelType label) override;
     int deleteVector(labelType labelType) override;
     double getDistanceFrom(labelType label, const void *vector_data) const override;
-
     inline size_t indexLabelCount() const override { return this->labelToIdsLookup.size(); }
 
+    inline std::unique_ptr<vecsim_stl::abstract_results_container>
+    getNewResultsContainer(size_t cap) const override {
+        return std::unique_ptr<vecsim_stl::abstract_results_container>(
+            new (this->allocator) vecsim_stl::unique_results_container(cap, this->allocator));
+    }
+
 private:
     // inline definitions
 

src/VecSim/algorithms/brute_force/brute_force_single.h

@@ -18,6 +18,12 @@ class BruteForceIndex_Single : public BruteForceIndex<DataType, DistType> {
     int deleteVector(labelType label) override;
     double getDistanceFrom(labelType label, const void *vector_data) const override;
 
+    inline std::unique_ptr<vecsim_stl::abstract_results_container>
+    getNewResultsContainer(size_t cap) const override {
+        return std::unique_ptr<vecsim_stl::abstract_results_container>(
+            new (this->allocator) vecsim_stl::default_results_container(cap, this->allocator));
+    }
+
     inline size_t indexLabelCount() const override { return this->count; }
 
 protected:

src/VecSim/algorithms/hnsw/hnsw.h

@@ -6,6 +6,7 @@
 #include "VecSim/memory/vecsim_malloc.h"
 #include "VecSim/utils/vecsim_stl.h"
 #include "VecSim/utils/vec_utils.h"
+#include "VecSim/utils/vecsim_results_container.h"
 #include "VecSim/query_result_struct.h"
 #include "VecSim/vec_sim_common.h"
 #include "VecSim/vec_sim_index.h"
@@ -119,11 +120,10 @@ class HNSWIndex : public VecSimIndexAbstract<DistType> {
                      tag_t visited_tag,
                      vecsim_stl::abstract_priority_queue<DistType, Identifier> &top_candidates,
                      candidatesMaxHeap<DistType> &candidates_set, DistType lowerBound) const;
-    inline void processCandidate_RangeSearch(idType curNodeId, const void *data_point, size_t layer,
-                                             double epsilon, tag_t visited_tag,
-                                             VecSimQueryResult **top_candidates,
-                                             candidatesMaxHeap<DistType> &candidate_set,
-                                             DistType lowerBound, double radius) const;
+    inline void processCandidate_RangeSearch(
+        idType curNodeId, const void *data_point, size_t layer, double epsilon, tag_t visited_tag,
+        std::unique_ptr<vecsim_stl::abstract_results_container> &top_candidates,
+        candidatesMaxHeap<DistType> &candidate_set, DistType lowerBound, double radius) const;
     candidatesMaxHeap<DistType> searchLayer(idType ep_id, const void *data_point, size_t layer,
                                             size_t ef) const;
     candidatesLabelsMaxHeap<DistType> *
@@ -192,6 +192,8 @@ class HNSWIndex : public VecSimIndexAbstract<DistType> {
 
 protected:
     // inline label to id setters that need to be implemented by derived class
+    virtual inline std::unique_ptr<vecsim_stl::abstract_results_container>
+    getNewResultsContainer(size_t cap) const = 0;
     virtual inline void replaceIdOfLabel(labelType label, idType new_id, idType old_id) = 0;
     virtual inline void setVectorId(labelType label, idType id) = 0;
     virtual inline void resizeLabelLookup(size_t new_max_elements) = 0;
@@ -453,8 +455,8 @@ DistType HNSWIndex<DataType, DistType>::processCandidate(
 template <typename DataType, typename DistType>
 void HNSWIndex<DataType, DistType>::processCandidate_RangeSearch(
     idType curNodeId, const void *query_data, size_t layer, double epsilon, tag_t visited_tag,
-    VecSimQueryResult **results, candidatesMaxHeap<DistType> &candidate_set, DistType dyn_range,
-    double radius) const {
+    std::unique_ptr<vecsim_stl::abstract_results_container> &results,
+    candidatesMaxHeap<DistType> &candidate_set, DistType dyn_range, double radius) const {
 
 #ifdef ENABLE_PARALLELIZATION
     std::unique_lock<std::mutex> lock(link_list_locks_[curNodeId]);
@@ -488,10 +490,7 @@ void HNSWIndex<DataType, DistType>::processCandidate_RangeSearch(
 
             // If the new candidate is in the requested radius, add it to the results set.
             if (candidate_dist <= radius_) {
-                auto new_result = VecSimQueryResult{};
-                VecSimQueryResult_SetId(new_result, getExternalLabel(candidate_id));
-                VecSimQueryResult_SetScore(new_result, candidate_dist);
-                *results = array_append(*results, new_result);
+                results->emplace(getExternalLabel(candidate_id), candidate_dist);
             }
         }
     }
@@ -1415,7 +1414,8 @@ VecSimQueryResult *HNSWIndex<DataType, DistType>::searchRangeBottomLayer_WithTim
     idType ep_id, const void *data_point, double epsilon, double radius, void *timeoutCtx,
     VecSimQueryResult_Code *rc) const {
 
-    auto *results = array_new<VecSimQueryResult>(10); // arbitrary initial cap.
+    *rc = VecSim_QueryResult_OK;
+    auto res_container = getNewResultsContainer(10); // arbitrary initial cap.
 
 #ifdef ENABLE_PARALLELIZATION
     this->visited_nodes_handler =
@@ -1431,10 +1431,7 @@ VecSimQueryResult *HNSWIndex<DataType, DistType>::searchRangeBottomLayer_WithTim
 
     if (ep_dist <= radius) {
         // Entry-point is within the radius - add it to the results.
-        auto new_result = VecSimQueryResult{};
-        VecSimQueryResult_SetId(new_result, getExternalLabel(ep_id));
-        VecSimQueryResult_SetScore(new_result, ep_dist);
-        results = array_append(results, new_result);
+        res_container->emplace(getExternalLabel(ep_id), ep_dist);
         dynamic_range = radius; // to ensure that dyn_range >= radius.
     }
 
@@ -1453,7 +1450,7 @@ VecSimQueryResult *HNSWIndex<DataType, DistType>::searchRangeBottomLayer_WithTim
         }
         if (__builtin_expect(VecSimIndexAbstract<DistType>::timeoutCallback(timeoutCtx), 0)) {
             *rc = VecSim_QueryResult_TimedOut;
-            return results;
+            break;
         }
         candidate_set.pop();
 
@@ -1468,15 +1465,14 @@ VecSimQueryResult *HNSWIndex<DataType, DistType>::searchRangeBottomLayer_WithTim
         // requested radius.
         // Here we send the radius as double to match the function arguments type.
         processCandidate_RangeSearch(curr_el_pair.second, data_point, 0, epsilon, visited_tag,
-                                     &results, candidate_set, dynamic_range_search_boundaries,
+                                     res_container, candidate_set, dynamic_range_search_boundaries,
                                      radius);
     }
+
 #ifdef ENABLE_PARALLELIZATION
     visited_nodes_handler_pool->returnVisitedNodesHandlerToPool(this->visited_nodes_handler);
 #endif
-
-    *rc = VecSim_QueryResult_OK;
-    return results;
+    return res_container->get_results();
 }
 
 template <typename DataType, typename DistType>

src/VecSim/algorithms/hnsw/hnsw_multi.h

@@ -32,6 +32,11 @@ class HNSWIndex_Multi : public HNSWIndex<DataType, DistType> {
         return new (this->allocator)
             vecsim_stl::updatable_max_heap<DistType, labelType>(this->allocator);
     }
+    inline std::unique_ptr<vecsim_stl::abstract_results_container>
+    getNewResultsContainer(size_t cap) const override {
+        return std::unique_ptr<vecsim_stl::abstract_results_container>(
+            new (this->allocator) vecsim_stl::unique_results_container(cap, this->allocator));
+    }
 
     inline size_t indexLabelCount() const override;
     VecSimBatchIterator *newBatchIterator(const void *queryBlob,
@@ -40,8 +45,6 @@ class HNSWIndex_Multi : public HNSWIndex<DataType, DistType> {
     int deleteVector(labelType label) override;
     int addVector(const void *vector_data, labelType label) override;
     double getDistanceFrom(labelType label, const void *vector_data) const override;
-    VecSimQueryResult_List rangeQuery(const void *query_data, double radius,
-                                      VecSimQueryParams *queryParams) override;
 };
 
 /**
@@ -124,15 +127,6 @@ int HNSWIndex_Multi<DataType, DistType>::addVector(const void *vector_data, cons
     return this->appendVector(vector_data, label);
 }
 
-// TODO: support range queries
-template <typename DataType, typename DistType>
-VecSimQueryResult_List
-HNSWIndex_Multi<DataType, DistType>::rangeQuery(const void *query_data, double radius,
-                                                VecSimQueryParams *queryParams) {
-    this->last_mode = RANGE_QUERY;
-    return {array_new<VecSimQueryResult>(0), VecSim_QueryResult_OK};
-}
-
 template <typename DataType, typename DistType>
 VecSimBatchIterator *
 HNSWIndex_Multi<DataType, DistType>::newBatchIterator(const void *queryBlob,

src/VecSim/algorithms/hnsw/hnsw_single.h

@@ -29,6 +29,11 @@ class HNSWIndex_Single : public HNSWIndex<DataType, DistType> {
         return new (this->allocator)
             vecsim_stl::max_priority_queue<DistType, labelType>(this->allocator);
     }
+    inline std::unique_ptr<vecsim_stl::abstract_results_container>
+    getNewResultsContainer(size_t cap) const override {
+        return std::unique_ptr<vecsim_stl::abstract_results_container>(
+            new (this->allocator) vecsim_stl::default_results_container(cap, this->allocator));
+    }
 
     inline size_t indexLabelCount() const override;
     VecSimBatchIterator *newBatchIterator(const void *queryBlob,

src/VecSim/query_results.cpp

@@ -4,21 +4,33 @@
 #include "VecSim/batch_iterator.h"
 
 struct VecSimQueryResult_Iterator {
-    VecSimQueryResult *curr_result;
+    VecSimQueryResult *results_arr;
     size_t index;
     size_t results_len;
 
     explicit VecSimQueryResult_Iterator(VecSimQueryResult_List results_array)
-        : curr_result(results_array.results), index(0),
+        : results_arr(results_array.results), index(0),
           results_len(array_len(results_array.results)) {}
 };
 
 extern "C" size_t VecSimQueryResult_Len(VecSimQueryResult_List rl) { return array_len(rl.results); }
 
+extern "C" VecSimQueryResult *VecSimQueryResult_GetArray(VecSimQueryResult_List rl) {
+    return rl.results;
+}
+
+extern "C" size_t VecSimQueryResult_ArrayLen(VecSimQueryResult *rl) { return array_len(rl); }
+
 extern "C" void VecSimQueryResult_Free(VecSimQueryResult_List rl) {
     if (rl.results) {
         array_free(rl.results);
-        rl.results = NULL;
+        rl.results = nullptr;
+    }
+}
+
+extern "C" void VecSimQueryResult_FreeArray(VecSimQueryResult *rl) {
+    if (rl) {
+        array_free(rl);
     }
 }
 
@@ -35,7 +47,7 @@ extern "C" VecSimQueryResult *VecSimQueryResult_IteratorNext(VecSimQueryResult_I
     if (iterator->index == iterator->results_len) {
         return nullptr;
     }
-    VecSimQueryResult *item = iterator->curr_result++;
+    VecSimQueryResult *item = iterator->results_arr + iterator->index;
     iterator->index++;
 
     return item;
@@ -52,13 +64,17 @@ extern "C" double VecSimQueryResult_GetScore(const VecSimQueryResult *res) {
     if (res == nullptr) {
         return INVALID_SCORE; // "NaN"
     }
-    return (double)res->score;
+    return res->score;
 }
 
 extern "C" void VecSimQueryResult_IteratorFree(VecSimQueryResult_Iterator *iterator) {
     delete iterator;
 }
 
+extern "C" void VecSimQueryResult_IteratorReset(VecSimQueryResult_Iterator *iterator) {
+    iterator->index = 0;
+}
+
 /********************** batch iterator API ***************************/
 VecSimQueryResult_List VecSimBatchIterator_Next(VecSimBatchIterator *iterator, size_t n_results,
                                                 VecSimQueryResult_Order order) {

src/VecSim/query_results.h

@@ -48,6 +48,16 @@ typedef struct VecSimQueryResult_Iterator VecSimQueryResult_Iterator;
  */
 size_t VecSimQueryResult_Len(VecSimQueryResult_List results);
 
+/**
+ * @brief Get the underline array of result from the opaque list object.
+ */
+VecSimQueryResult *VecSimQueryResult_GetArray(VecSimQueryResult_List rl);
+
+/**
+ * @brief Get the length of the result list from the underline array.
+ */
+size_t VecSimQueryResult_ArrayLen(VecSimQueryResult *rl);
+
 /**
  * @brief Create an iterator for going over the list of results. The iterator needs to be free
  * with VecSimQueryResult_IteratorFree.
@@ -65,6 +75,11 @@ VecSimQueryResult *VecSimQueryResult_IteratorNext(VecSimQueryResult_Iterator *it
  */
 bool VecSimQueryResult_IteratorHasNext(VecSimQueryResult_Iterator *iterator);
 
+/**
+ * @brief Rewind the iterator to the beginning of the result list
+ */
+void VecSimQueryResult_IteratorReset(VecSimQueryResult_Iterator *iterator);
+
 /**
  * @brief Release the iterator
  */
@@ -75,6 +90,11 @@ void VecSimQueryResult_IteratorFree(VecSimQueryResult_Iterator *iterator);
  */
 void VecSimQueryResult_Free(VecSimQueryResult_List results);
 
+/**
+ * @brief Release the query results array.
+ */
+void VecSimQueryResult_FreeArray(VecSimQueryResult *rl);
+
 /**
  * @brief Iterator for running the same query over an index, getting the in each iteration
  * the best results that hasn't returned in the previous iterations.

src/VecSim/utils/vec_utils.cpp

@@ -4,6 +4,7 @@
 #include <cassert>
 #include <cerrno>
 #include <climits>
+#include <float.h>
 
 #ifndef __COMPAR_FN_T
 #define __COMPAR_FN_T
@@ -77,6 +78,19 @@ VecSimResolveCode validate_positive_integer_param(VecSimRawParam rawParam, long
     return VecSimParamResolver_OK;
 }
 
+VecSimResolveCode validate_positive_double_param(VecSimRawParam rawParam, double *val) {
+    char *ep; // For checking that strtold used all rawParam.valLen chars.
+    errno = 0;
+    *val = strtod(rawParam.value, &ep);
+    // Here we verify that val is positive and strtod was successful.
+    // The last test checks that the entire rawParam.value was used.
+    // We catch here inputs like "-3.14", "123text" and so on.
+    if (*val <= 0 || *val == DBL_MAX || errno != 0 || (rawParam.value + rawParam.valLen) != ep) {
+        return VecSimParamResolverErr_BadValue;
+    }
+    return VecSimParamResolver_OK;
+}
+
 const char *VecSimAlgo_ToString(VecSimAlgo vecsimAlgo) {
     switch (vecsimAlgo) {
     case VecSimAlgo_BF:

src/VecSim/utils/vec_utils.h

@@ -56,6 +56,8 @@ void sort_results_by_score(VecSimQueryResult_List results);
 
 VecSimResolveCode validate_positive_integer_param(VecSimRawParam rawParam, long long *val);
 
+VecSimResolveCode validate_positive_double_param(VecSimRawParam rawParam, double *val);
+
 const char *VecSimAlgo_ToString(VecSimAlgo vecsimAlgo);
 
 const char *VecSimType_ToString(VecSimType vecsimType);