[ENH] Dynamic ef_search

CMakeLists.txt

@@ -6,14 +6,15 @@ add_library(hnswlib INTERFACE)
 target_include_directories(hnswlib INTERFACE .) 
 
 if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
-    set(CMAKE_CXX_STANDARD 11)
+    set(CMAKE_CXX_STANDARD 17)
+    set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
     if (CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
-      SET( CMAKE_CXX_FLAGS "-Ofast -DNDEBUG -std=c++11 -DHAVE_CXX0X -openmp -march=native -fpic -ftree-vectorize")
+      SET( CMAKE_CXX_FLAGS "-Ofast -DNDEBUG -std=c++17 -DHAVE_CXX0X -openmp -march=native -fpic -ftree-vectorize")
     elseif (CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
-      SET( CMAKE_CXX_FLAGS  "-Ofast -lrt -DNDEBUG -std=c++11 -DHAVE_CXX0X -march=native -fpic -w -fopenmp -ftree-vectorize -ftree-vectorizer-verbose=0" )
+      SET( CMAKE_CXX_FLAGS  "-Ofast -lrt -DNDEBUG -std=c++17 -DHAVE_CXX0X -march=native -fpic -w -fopenmp -ftree-vectorize -ftree-vectorizer-verbose=0" )
     elseif (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC")
-      SET( CMAKE_CXX_FLAGS  "-Ofast -lrt -DNDEBUG -std=c++11 -DHAVE_CXX0X -openmp -march=native -fpic -w -fopenmp -ftree-vectorize" )
+      SET( CMAKE_CXX_FLAGS  "-Ofast -lrt -DNDEBUG -std=c++17 -DHAVE_CXX0X -openmp -march=native -fpic -w -fopenmp -ftree-vectorize" )
     endif()
 
     # examples

TESTING_RECALL.md

@@ -59,7 +59,7 @@ bf_index.init_index(max_elements=num_elements)
 
 # Controlling the recall for hnsw by setting ef:
 # higher ef leads to better accuracy, but slower search
-hnsw_index.set_ef(200)
+hnsw_index.set_ef_search_default(200)
 
 # Set number of threads used during batch search/construction in hnsw
 # By default using all available cores

examples/cpp/EXAMPLES.md

@@ -134,10 +134,11 @@ int main() {
     int M = 16;                 // Tightly connected with internal dimensionality of the data
                                 // strongly affects the memory consumption
     int ef_construction = 200;  // Controls index search speed/build speed tradeoff
+    int ef_search_default = 10  // Controls index search speed tradeoff
 
     // Initing index
     hnswlib::L2Space space(dim);
-    hnswlib::HierarchicalNSW<float>* alg_hnsw = new hnswlib::HierarchicalNSW<float>(&space, max_elements, M, ef_construction, 100, true);
+    hnswlib::HierarchicalNSW<float>* alg_hnsw = new hnswlib::HierarchicalNSW<float>(&space, max_elements, M, ef_construction, ef_search_default, 100, true);
 
     // Generate random data
     std::mt19937 rng;

examples/cpp/example_mt_replace_deleted.cpp

@@ -69,17 +69,18 @@ inline void ParallelFor(size_t start, size_t end, size_t numThreads, Function fn
 
 int main()
 {
-    int dim = 16;              // Dimension of the elements
-    int max_elements = 10000;  // Maximum number of elements, should be known beforehand
-    int M = 16;                // Tightly connected with internal dimensionality of the data
-                               // strongly affects the memory consumption
-    int ef_construction = 200; // Controls index search speed/build speed tradeoff
-    int num_threads = 20;      // Number of threads for operations with index
+    int dim = 16;               // Dimension of the elements
+    int max_elements = 10000;   // Maximum number of elements, should be known beforehand
+    int M = 16;                 // Tightly connected with internal dimensionality of the data
+                                // strongly affects the memory consumption
+    int ef_construction = 200;  // Controls index search speed/build speed tradeoff
+    int ef_search_default = 10; // Controls index search speed/recall tradeoff
+    int num_threads = 20;       // Number of threads for operations with index
 
     // Initing index with allow_replace_deleted=true
     int seed = 100;
     hnswlib::L2Space space(dim);
-    hnswlib::HierarchicalNSW<float> *alg_hnsw = new hnswlib::HierarchicalNSW<float>(&space, max_elements, M, ef_construction, seed, true);
+    hnswlib::HierarchicalNSW<float> *alg_hnsw = new hnswlib::HierarchicalNSW<float>(&space, max_elements, M, ef_construction, ef_search_default, seed, true);
 
     // Generate random data
     std::mt19937 rng;

examples/cpp/example_replace_deleted.cpp

@@ -7,11 +7,12 @@ int main()
     int M = 16;                // Tightly connected with internal dimensionality of the data
                                // strongly affects the memory consumption
     int ef_construction = 200; // Controls index search speed/build speed tradeoff
+    int ef_search_default = 10;
 
     // Initing index with allow_replace_deleted=true
     int seed = 100;
     hnswlib::L2Space space(dim);
-    hnswlib::HierarchicalNSW<float> *alg_hnsw = new hnswlib::HierarchicalNSW<float>(&space, max_elements, M, ef_construction, seed, true);
+    hnswlib::HierarchicalNSW<float> *alg_hnsw = new hnswlib::HierarchicalNSW<float>(&space, max_elements, M, ef_construction, ef_search_default, seed, true);
 
     // Generate random data
     std::mt19937 rng;

examples/python/EXAMPLES.md

@@ -23,7 +23,7 @@ p.init_index(max_elements = num_elements, ef_construction = 200, M = 16)
 p.add_items(data, ids)
 
 # Controlling the recall by setting ef:
-p.set_ef(50) # ef should always be > k
+p.set_ef_search_default(50) # ef should always be > k
 
 # Query dataset, k - number of the closest elements (returns 2 numpy arrays)
 labels, distances = p.knn_query(data, k = 1)
@@ -37,7 +37,7 @@ p_copy = pickle.loads(pickle.dumps(p)) # creates a copy of index p using pickle
 print(f"Parameters passed to constructor:  space={p_copy.space}, dim={p_copy.dim}") 
 print(f"Index construction: M={p_copy.M}, ef_construction={p_copy.ef_construction}")
 print(f"Index size is {p_copy.element_count} and index capacity is {p_copy.max_elements}")
-print(f"Search speed/quality trade-off parameter: ef={p_copy.ef}")
+print(f"Search speed/quality trade-off parameter: ef={p_copy.ef_search_default}")
 ```
 
 An example with updates after serialization/deserialization:
@@ -72,7 +72,7 @@ p.init_index(max_elements=num_elements//2, ef_construction=100, M=16)
 
 # Controlling the recall by setting ef:
 # higher ef leads to better accuracy, but slower search
-p.set_ef(10)
+p.set_ef_search_default(10)
 
 # Set number of threads used during batch search/construction
 # By default using all available cores
@@ -133,7 +133,7 @@ hnsw_index.init_index(max_elements=num_elements, ef_construction=100, M=16)
 
 # Controlling the recall by setting ef:
 # higher ef leads to better accuracy, but slower search
-hnsw_index.set_ef(10)
+hnsw_index.set_ef_search_default(10)
 
 # Set number of threads used during batch search/construction
 # By default using all available cores
@@ -185,7 +185,7 @@ hnsw_index.init_index(max_elements=max_num_elements, ef_construction=200, M=16,
 
 # Controlling the recall by setting ef:
 # higher ef leads to better accuracy, but slower search
-hnsw_index.set_ef(10)
+hnsw_index.set_ef_search_default(10)
 
 # Set number of threads used during batch search/construction
 # By default using all available cores

examples/python/example.py

@@ -34,7 +34,7 @@
 
 # Controlling the recall by setting ef:
 # higher ef leads to better accuracy, but slower search
-p.set_ef(10)
+p.set_ef_search_default(10)
 
 # Set number of threads used during batch search/construction
 # By default using all available cores

examples/python/example_filter.py

@@ -27,7 +27,7 @@
 
 # Controlling the recall by setting ef:
 # higher ef leads to better accuracy, but slower search
-hnsw_index.set_ef(10)
+hnsw_index.set_ef_search_default(10)
 
 # Set number of threads used during batch search/construction
 # By default using all available cores

examples/python/example_replace_deleted.py

@@ -36,7 +36,7 @@
 
 # Controlling the recall by setting ef:
 # higher ef leads to better accuracy, but slower search
-hnsw_index.set_ef(10)
+hnsw_index.set_ef_search_default(10)
 
 # Set number of threads used during batch search/construction
 # By default using all available cores

examples/python/example_search.py

@@ -24,7 +24,7 @@
 p.add_items(data, ids)
 
 # Controlling the recall by setting ef:
-p.set_ef(50)  # ef should always be > k
+p.set_ef_search_default(50)  # ef should always be > k
 
 # Query dataset, k - number of the closest elements (returns 2 numpy arrays)
 labels, distances = p.knn_query(data, k=1)
@@ -42,4 +42,4 @@
 print(
     f"Index size is {p_copy.element_count} and index capacity is {p_copy.max_elements}"
 )
-print(f"Search speed/quality trade-off parameter: ef={p_copy.ef}")
+print(f"Search speed/quality trade-off parameter: ef={p_copy.ef_search_default}")

examples/python/example_serialization.py

@@ -35,7 +35,7 @@
 
 # Controlling the recall by setting ef:
 # higher ef leads to better accuracy, but slower search
-p.set_ef(10)
+p.set_ef_search_default(10)
 
 # Set number of threads used during batch search/construction
 # By default using all available cores

examples/python/pyw_hnswlib.py

@@ -42,8 +42,8 @@ def add_items(self, data, ids=None):
                 start += 1
         self.index.add_items(data=data, ids=np.asarray(int_labels))
 
-    def set_ef(self, ef):
-        self.index.set_ef(ef)
+    def set_ef_search_default(self, ef):
+        self.index.set_ef_search_default(ef)
 
     def load_index(self, path):
         self.index.load_index(path)

hnswlib/bruteforce.h

@@ -103,7 +103,7 @@ namespace hnswlib
         }
 
         std::priority_queue<std::pair<dist_t, labeltype>>
-        searchKnn(const void *query_data, size_t k, BaseFilterFunctor *isIdAllowed = nullptr) const
+        searchKnn(const void *query_data, size_t k, BaseFilterFunctor *isIdAllowed = nullptr, const std::optional<size_t> ef_search = std::nullopt) const
         {
             assert(k <= cur_element_count);
             std::priority_queue<std::pair<dist_t, labeltype>> topResults;

hnswlib/hnswalg.h

@@ -9,6 +9,8 @@
 #include <unordered_set>
 #include <set>
 #include <list>
+#include <shared_mutex>
+#include <optional>
 
 namespace hnswlib
 {
@@ -32,7 +34,7 @@ namespace hnswlib
         size_t maxM_{0};
         size_t maxM0_{0};
         size_t ef_construction_{0};
-        size_t ef_{0};
+        size_t ef_search_default_{0};
 
         double mult_{0.0}, revSize_{0.0};
         int maxlevel_{0};
@@ -44,6 +46,7 @@ namespace hnswlib
 
         std::mutex global;
         std::vector<std::mutex> link_list_locks_;
+        mutable std::shared_mutex ef_search_default_lock_;
 
         tableint enterpoint_node_{0};
 
@@ -119,6 +122,7 @@ namespace hnswlib
             size_t max_elements,
             size_t M = 16,
             size_t ef_construction = 200,
+            size_t ef_search_default = 10,
             size_t random_seed = 100,
             bool allow_replace_deleted = false,
             bool normalize = false,
@@ -141,7 +145,7 @@ namespace hnswlib
             maxM_ = M_;
             maxM0_ = M_ * 2;
             ef_construction_ = std::max(ef_construction, M_);
-            ef_ = 10;
+            ef_search_default_ = ef_search_default;
 
             level_generator_.seed(random_seed);
             update_probability_generator_.seed(random_seed + 1);
@@ -208,9 +212,10 @@ namespace hnswlib
             }
         };
 
-        void setEf(size_t ef)
+        void setEfSearchDefault(size_t ef_search_default)
         {
-            ef_ = ef;
+            std::unique_lock<std::shared_mutex> lock(ef_search_default_lock_);
+            ef_search_default_ = ef_search_default;
         }
 
         inline std::mutex &getLabelOpMutex(labeltype label) const
@@ -374,7 +379,7 @@ namespace hnswlib
 
         template <bool has_deletions, bool collect_metrics = false>
         std::priority_queue<std::pair<dist_t, tableint>, std::vector<std::pair<dist_t, tableint>>, CompareByFirst>
-        searchBaseLayerST(tableint ep_id, const void *data_point, size_t ef, BaseFilterFunctor *isIdAllowed = nullptr) const
+        searchBaseLayerST(tableint ep_id, const void *data_point, size_t ef_search_default, BaseFilterFunctor *isIdAllowed = nullptr) const
         {
             VisitedList *vl = visited_list_pool_->getFreeVisitedList();
             vl_type *visited_array = vl->mass;
@@ -404,7 +409,7 @@ namespace hnswlib
                 std::pair<dist_t, tableint> current_node_pair = candidate_set.top();
 
                 if ((-current_node_pair.first) > lowerBound &&
-                    (top_candidates.size() == ef || (!isIdAllowed && !has_deletions)))
+                    (top_candidates.size() == ef_search_default || (!isIdAllowed && !has_deletions)))
                 {
                     break;
                 }
@@ -443,7 +448,7 @@ namespace hnswlib
                         char *currObj1 = (getDataByInternalId(candidate_id));
                         dist_t dist = fstdistfunc_(data_point, currObj1, dist_func_param_);
 
-                        if (top_candidates.size() < ef || lowerBound > dist)
+                        if (top_candidates.size() < ef_search_default || lowerBound > dist)
                         {
                             candidate_set.emplace(-dist, candidate_id);
 #ifdef USE_SSE
@@ -455,7 +460,7 @@ namespace hnswlib
                             if ((!has_deletions || !isMarkedDeleted(candidate_id)) && ((!isIdAllowed) || (*isIdAllowed)(getExternalLabel(candidate_id))))
                                 top_candidates.emplace(dist, candidate_id);
 
-                            if (top_candidates.size() > ef)
+                            if (top_candidates.size() > ef_search_default)
                                 top_candidates.pop();
 
                             if (!top_candidates.empty())
@@ -746,6 +751,7 @@ namespace hnswlib
             writeBinaryPOD(output, M_);
             writeBinaryPOD(output, mult_);
             writeBinaryPOD(output, ef_construction_);
+            writeBinaryPOD(output, ef_search_default_);
 
             output.write(data_level0_memory_, cur_element_count * size_data_per_element_);
             output.write(length_memory_, cur_element_count * sizeof(float));
@@ -1006,6 +1012,7 @@ namespace hnswlib
             readBinaryPOD(input_header, M_);
             readBinaryPOD(input_header, mult_);
             readBinaryPOD(input_header, ef_construction_);
+            readBinaryPOD(input_header, ef_search_default_);
             input_header.close();
 
             data_size_ = s->get_data_size();
@@ -1064,7 +1071,6 @@ namespace hnswlib
                 throw std::runtime_error("Not enough memory: loadPersistedIndex failed to allocate linklists");
             element_levels_ = std::vector<int>(max_elements_);
             revSize_ = 1.0 / mult_;
-            ef_ = 10;
             for (size_t i = 0; i < cur_element_count; i++)
             {
                 label_lookup_[getExternalLabel(i)] = i;
@@ -1130,6 +1136,7 @@ namespace hnswlib
             readBinaryPOD(input, M_);
             readBinaryPOD(input, mult_);
             readBinaryPOD(input, ef_construction_);
+            readBinaryPOD(input, ef_search_default_);
 
             data_size_ = s->get_data_size();
             fstdistfunc_ = s->get_dist_func();
@@ -1715,9 +1722,18 @@ namespace hnswlib
         }
 
         std::priority_queue<std::pair<dist_t, labeltype>>
-        searchKnn(const void *query_data, size_t k, BaseFilterFunctor *isIdAllowed = nullptr) const
+        searchKnn(const void *query_data, size_t k, BaseFilterFunctor *isIdAllowed = nullptr, const std::optional<size_t> ef_search = std::nullopt) const
         {
-            std::priority_queue<std::pair<dist_t, labeltype>> result;
+
+            auto get_ef_search_default = [this]()
+            {
+                std::shared_lock<std::shared_mutex> lock(ef_search_default_lock_);
+                return ef_search_default_;
+            };
+
+            const std::size_t this_ef_search = ef_search.has_value() ? ef_search.value() : get_ef_search_default();
+            std::priority_queue<std::pair<dist_t, labeltype>>
+                result;
             if (cur_element_count == 0)
                 return result;
 
@@ -1758,12 +1774,12 @@ namespace hnswlib
             if (num_deleted_)
             {
                 top_candidates = searchBaseLayerST<true, true>(
-                    currObj, query_data, std::max(ef_, k), isIdAllowed);
+                    currObj, query_data, std::max(this_ef_search, k), isIdAllowed);
             }
             else
             {
                 top_candidates = searchBaseLayerST<false, true>(
-                    currObj, query_data, std::max(ef_, k), isIdAllowed);
+                    currObj, query_data, std::max(this_ef_search, k), isIdAllowed);
             }
 
             while (top_candidates.size() > k)

hnswlib/hnswlib.h

@@ -122,7 +122,7 @@ static bool AVX512Capable()
 #include <vector>
 #include <iostream>
 #include <string.h>
-
+#include <optional>
 namespace hnswlib
 {
     typedef size_t labeltype;
@@ -180,7 +180,7 @@ namespace hnswlib
         virtual void addPoint(const void *datapoint, labeltype label, bool replace_deleted = false) = 0;
 
         virtual std::priority_queue<std::pair<dist_t, labeltype>>
-        searchKnn(const void *, size_t, BaseFilterFunctor *isIdAllowed = nullptr) const = 0;
+        searchKnn(const void *, size_t, BaseFilterFunctor *isIdAllowed = nullptr, const std::optional<size_t> ef_search = std::nullopt) const = 0;
 
         // Return k nearest neighbor in the order of closer fist
         virtual std::vector<std::pair<dist_t, labeltype>>

python_bindings/LazyIndex.py

@@ -44,11 +44,11 @@ def resize_index(self, size):
         else:
             return super().resize_index(size)
 
-    def set_ef(self, ef):
+    def set_ef_search_default(self, ef):
         if self.max_elements == 0:
             self.init_ef_construction = ef
             return
-        super().set_ef(ef)
+        super().set_ef_search_default(ef)
 
     def get_max_elements(self):
         return self.max_elements