usearch 2.10.5 → 2.11.1

package/c/lib.cpp

@@ -6,6 +6,13 @@ extern "C" {
 #include "usearch.h"
 }
 
+// Check if NDEBUG is defined to determine if it's a release build
+#ifdef NDEBUG
+#define USEARCH_ASSERT(expression) (void)(expression)
+#else
+#define USEARCH_ASSERT(expression) assert(expression)
+#endif
+
 using namespace unum::usearch;
 using namespace unum;
 
@@ -91,22 +98,38 @@ std::size_t get_(index_dense_t* index, usearch_key_t key, size_t count, void* ve
     }
 }
 
-search_result_t search_(index_dense_t* index, void const* vector, scalar_kind_t kind, size_t n) {
+template <typename predicate_at = dummy_predicate_t>
+search_result_t search_(index_dense_t* index, void const* vector, scalar_kind_t kind, size_t n,
+                        predicate_at&& predicate = predicate_at{}) {
     switch (kind) {
-    case scalar_kind_t::f32_k: return index->search((f32_t const*)vector, n);
-    case scalar_kind_t::f64_k: return index->search((f64_t const*)vector, n);
-    case scalar_kind_t::f16_k: return index->search((f16_t const*)vector, n);
-    case scalar_kind_t::i8_k: return index->search((i8_t const*)vector, n);
-    case scalar_kind_t::b1x8_k: return index->search((b1x8_t const*)vector, n);
+    case scalar_kind_t::f32_k:
+        return index->filtered_search((f32_t const*)vector, n, std::forward<predicate_at>(predicate));
+    case scalar_kind_t::f64_k:
+        return index->filtered_search((f64_t const*)vector, n, std::forward<predicate_at>(predicate));
+    case scalar_kind_t::f16_k:
+        return index->filtered_search((f16_t const*)vector, n, std::forward<predicate_at>(predicate));
+    case scalar_kind_t::i8_k:
+        return index->filtered_search((i8_t const*)vector, n, std::forward<predicate_at>(predicate));
+    case scalar_kind_t::b1x8_k:
+        return index->filtered_search((b1x8_t const*)vector, n, std::forward<predicate_at>(predicate));
     default: return search_result_t().failed("Unknown scalar kind!");
     }
 }
 
 extern "C" {
 
+USEARCH_EXPORT char const* usearch_version(void) {
+    int major = USEARCH_VERSION_MAJOR;
+    int minor = USEARCH_VERSION_MINOR;
+    int patch = USEARCH_VERSION_PATCH;
+    static char version[32];
+    sprintf(version, "%d.%d.%d", major, minor, patch);
+    return version;
+}
+
 USEARCH_EXPORT usearch_index_t usearch_init(usearch_init_options_t* options, usearch_error_t* error) {
 
-    assert(options && error && "Missing arguments");
+    USEARCH_ASSERT(options && error && "Missing arguments");
 
     index_dense_config_t config(options->connectivity, options->expansion_add, options->expansion_search);
     config.multi = options->multi;
@@ -114,11 +137,11 @@ USEARCH_EXPORT usearch_index_t usearch_init(usearch_init_options_t* options, use
     scalar_kind_t scalar_kind = scalar_kind_to_cpp(options->quantization);
 
     metric_punned_t metric = //
-        !options->metric ? metric_punned_t(options->dimensions, metric_kind, scalar_kind)
-                         : metric_punned_t(options->dimensions,                               //
-                                           reinterpret_cast<std::uintptr_t>(options->metric), //
-                                           metric_punned_signature_t::array_array_k,          //
-                                           metric_kind, scalar_kind);
+        !options->metric ? metric_punned_t::builtin(options->dimensions, metric_kind, scalar_kind)
+                         : metric_punned_t::stateless(options->dimensions,                               //
+                                                      reinterpret_cast<std::uintptr_t>(options->metric), //
+                                                      metric_punned_signature_t::array_array_k,          //
+                                                      metric_kind, scalar_kind);
     if (metric.missing()) {
         *error = "Unknown metric kind!";
         return NULL;
@@ -136,13 +159,13 @@ USEARCH_EXPORT void usearch_free(usearch_index_t index, usearch_error_t*) {
 }
 
 USEARCH_EXPORT size_t usearch_serialized_length(usearch_index_t index, usearch_error_t*) {
-    assert(index && "Missing arguments");
+    USEARCH_ASSERT(index && "Missing arguments");
     return reinterpret_cast<index_dense_t*>(index)->serialized_length();
 }
 
 USEARCH_EXPORT void usearch_save(usearch_index_t index, char const* path, usearch_error_t* error) {
 
-    assert(index && path && error && "Missing arguments");
+    USEARCH_ASSERT(index && path && error && "Missing arguments");
     serialization_result_t result = reinterpret_cast<index_dense_t*>(index)->save(path);
     if (!result)
         *error = result.error.release();
@@ -150,7 +173,7 @@ USEARCH_EXPORT void usearch_save(usearch_index_t index, char const* path, usearc
 
 USEARCH_EXPORT void usearch_load(usearch_index_t index, char const* path, usearch_error_t* error) {
 
-    assert(index && path && error && "Missing arguments");
+    USEARCH_ASSERT(index && path && error && "Missing arguments");
     serialization_result_t result = reinterpret_cast<index_dense_t*>(index)->load(path);
     if (!result)
         *error = result.error.release();
@@ -158,7 +181,7 @@ USEARCH_EXPORT void usearch_load(usearch_index_t index, char const* path, usearc
 
 USEARCH_EXPORT void usearch_view(usearch_index_t index, char const* path, usearch_error_t* error) {
 
-    assert(index && path && error && "Missing arguments");
+    USEARCH_ASSERT(index && path && error && "Missing arguments");
     serialization_result_t result = reinterpret_cast<index_dense_t*>(index)->view(path);
     if (!result)
         *error = result.error.release();
@@ -166,7 +189,7 @@ USEARCH_EXPORT void usearch_view(usearch_index_t index, char const* path, usearc
 
 USEARCH_EXPORT void usearch_metadata(char const* path, usearch_init_options_t* options, usearch_error_t* error) {
 
-    assert(path && options && error && "Missing arguments");
+    USEARCH_ASSERT(path && options && error && "Missing arguments");
     index_dense_metadata_result_t result = index_dense_metadata_from_path(path);
     if (!result)
         *error = result.error.release();
@@ -184,7 +207,7 @@ USEARCH_EXPORT void usearch_metadata(char const* path, usearch_init_options_t* o
 
 USEARCH_EXPORT void usearch_save_buffer(usearch_index_t index, void* buffer, size_t length, usearch_error_t* error) {
 
-    assert(index && buffer && length && error && "Missing arguments");
+    USEARCH_ASSERT(index && buffer && length && error && "Missing arguments");
     memory_mapped_file_t memory_map((byte_t*)buffer, length);
     serialization_result_t result = reinterpret_cast<index_dense_t*>(index)->save(std::move(memory_map));
     if (!result)
@@ -194,7 +217,7 @@ USEARCH_EXPORT void usearch_save_buffer(usearch_index_t index, void* buffer, siz
 USEARCH_EXPORT void usearch_load_buffer(usearch_index_t index, void const* buffer, size_t length,
                                         usearch_error_t* error) {
 
-    assert(index && buffer && length && error && "Missing arguments");
+    USEARCH_ASSERT(index && buffer && length && error && "Missing arguments");
     memory_mapped_file_t memory_map((byte_t*)buffer, length);
     serialization_result_t result = reinterpret_cast<index_dense_t*>(index)->load(std::move(memory_map));
     if (!result)
@@ -204,7 +227,7 @@ USEARCH_EXPORT void usearch_load_buffer(usearch_index_t index, void const* buffe
 USEARCH_EXPORT void usearch_view_buffer(usearch_index_t index, void const* buffer, size_t length,
                                         usearch_error_t* error) {
 
-    assert(index && buffer && length && error && "Missing arguments");
+    USEARCH_ASSERT(index && buffer && length && error && "Missing arguments");
     memory_mapped_file_t memory_map((byte_t*)buffer, length);
     serialization_result_t result = reinterpret_cast<index_dense_t*>(index)->view(std::move(memory_map));
     if (!result)
@@ -214,7 +237,7 @@ USEARCH_EXPORT void usearch_view_buffer(usearch_index_t index, void const* buffe
 USEARCH_EXPORT void usearch_metadata_buffer(void const* buffer, size_t length, usearch_init_options_t* options,
                                             usearch_error_t* error) {
 
-    assert(buffer && length && options && error && "Missing arguments");
+    USEARCH_ASSERT(buffer && length && options && error && "Missing arguments");
     index_dense_metadata_result_t result =
         index_dense_metadata_from_buffer(memory_mapped_file_t((byte_t*)(buffer), length));
     if (!result)
@@ -231,24 +254,80 @@ USEARCH_EXPORT void usearch_metadata_buffer(void const* buffer, size_t length, u
     options->metric = NULL;
 }
 
-USEARCH_EXPORT size_t usearch_size(usearch_index_t index, usearch_error_t*) { //
+USEARCH_EXPORT size_t usearch_size(usearch_index_t index, usearch_error_t* error) {
+    USEARCH_ASSERT(index && error && "Missing arguments");
     return reinterpret_cast<index_dense_t*>(index)->size();
 }
 
-USEARCH_EXPORT size_t usearch_capacity(usearch_index_t index, usearch_error_t*) {
+USEARCH_EXPORT size_t usearch_capacity(usearch_index_t index, usearch_error_t* error) {
+    USEARCH_ASSERT(index && error && "Missing arguments");
     return reinterpret_cast<index_dense_t*>(index)->capacity();
 }
 
-USEARCH_EXPORT size_t usearch_dimensions(usearch_index_t index, usearch_error_t*) {
+USEARCH_EXPORT size_t usearch_dimensions(usearch_index_t index, usearch_error_t* error) {
+    USEARCH_ASSERT(index && error && "Missing arguments");
     return reinterpret_cast<index_dense_t*>(index)->dimensions();
 }
 
-USEARCH_EXPORT size_t usearch_connectivity(usearch_index_t index, usearch_error_t*) {
+USEARCH_EXPORT size_t usearch_connectivity(usearch_index_t index, usearch_error_t* error) {
+    USEARCH_ASSERT(index && error && "Missing arguments");
     return reinterpret_cast<index_dense_t*>(index)->connectivity();
 }
 
+USEARCH_EXPORT size_t usearch_expansion_add(usearch_index_t index, usearch_error_t* error) {
+    USEARCH_ASSERT(index && error && "Missing arguments");
+    return reinterpret_cast<index_dense_t*>(index)->expansion_add();
+}
+
+USEARCH_EXPORT size_t usearch_expansion_search(usearch_index_t index, usearch_error_t* error) {
+    USEARCH_ASSERT(index && error && "Missing arguments");
+    return reinterpret_cast<index_dense_t*>(index)->expansion_search();
+}
+
+USEARCH_EXPORT size_t usearch_memory_usage(usearch_index_t index, usearch_error_t* error) {
+    USEARCH_ASSERT(index && error && "Missing arguments");
+    return reinterpret_cast<index_dense_t*>(index)->memory_usage();
+}
+
+USEARCH_EXPORT char const* usearch_hardware_acceleration(usearch_index_t index, usearch_error_t* error) {
+    USEARCH_ASSERT(index && error && "Missing arguments");
+    return reinterpret_cast<index_dense_t*>(index)->metric().isa_name();
+}
+
+USEARCH_EXPORT void usearch_change_expansion_add(usearch_index_t index, size_t expansion, usearch_error_t* error) {
+    USEARCH_ASSERT(index && error && "Missing arguments");
+    reinterpret_cast<index_dense_t*>(index)->change_expansion_add(expansion);
+}
+
+USEARCH_EXPORT void usearch_change_expansion_search(usearch_index_t index, size_t expansion, usearch_error_t* error) {
+    USEARCH_ASSERT(index && error && "Missing arguments");
+    reinterpret_cast<index_dense_t*>(index)->change_expansion_search(expansion);
+}
+
+USEARCH_EXPORT void usearch_change_metric_kind(usearch_index_t index, usearch_metric_kind_t kind,
+                                               usearch_error_t* error) {
+    USEARCH_ASSERT(index && error && "Missing arguments");
+    auto& index_dense = *reinterpret_cast<index_dense_t*>(index);
+    index_dense.change_metric(
+        metric_punned_t::builtin(index_dense.dimensions(), metric_kind_to_cpp(kind), index_dense.scalar_kind()));
+}
+
+USEARCH_EXPORT void usearch_change_metric(usearch_index_t index, usearch_metric_t metric, void* state,
+                                          usearch_metric_kind_t kind, usearch_error_t* error) {
+    USEARCH_ASSERT(index && error && "Missing arguments");
+    auto& index_dense = *reinterpret_cast<index_dense_t*>(index);
+    auto metric_punned =
+        state ? metric_punned_t::statefull(reinterpret_cast<std::uintptr_t>(metric),
+                                           reinterpret_cast<std::uintptr_t>(state), metric_kind_to_cpp(kind),
+                                           index_dense.scalar_kind())
+              : metric_punned_t::stateless(index_dense.dimensions(), reinterpret_cast<std::uintptr_t>(metric),
+                                           metric_punned_signature_t::array_array_k, metric_kind_to_cpp(kind),
+                                           index_dense.scalar_kind());
+    index_dense.change_metric(std::move(metric_punned));
+}
+
 USEARCH_EXPORT void usearch_reserve(usearch_index_t index, size_t capacity, usearch_error_t* error) {
-    assert(index && error && "Missing arguments");
+    USEARCH_ASSERT(index && error && "Missing arguments");
     if (!reinterpret_cast<index_dense_t*>(index)->reserve(capacity))
         *error = "Out of memory!";
 }
@@ -257,29 +336,47 @@ USEARCH_EXPORT void usearch_add(
     usearch_index_t index, usearch_key_t key, void const* vector, usearch_scalar_kind_t kind, //
     usearch_error_t* error) {
 
-    assert(index && vector && error && "Missing arguments");
+    USEARCH_ASSERT(index && vector && error && "Missing arguments");
     add_result_t result = add_(reinterpret_cast<index_dense_t*>(index), key, vector, scalar_kind_to_cpp(kind));
     if (!result)
         *error = result.error.release();
 }
 
 USEARCH_EXPORT bool usearch_contains(usearch_index_t index, usearch_key_t key, usearch_error_t*) {
-    assert(index && "Missing arguments");
+    USEARCH_ASSERT(index && "Missing arguments");
     return reinterpret_cast<index_dense_t*>(index)->contains(key);
 }
 
 USEARCH_EXPORT size_t usearch_count(usearch_index_t index, usearch_key_t key, usearch_error_t*) {
-    assert(index && "Missing arguments");
+    USEARCH_ASSERT(index && "Missing arguments");
     return reinterpret_cast<index_dense_t*>(index)->count(key);
 }
 
-USEARCH_EXPORT size_t usearch_search(                                                            //
-    usearch_index_t index, void const* vector, usearch_scalar_kind_t kind, size_t results_limit, //
+USEARCH_EXPORT size_t usearch_search(                                                                 //
+    usearch_index_t index, void const* query, usearch_scalar_kind_t query_kind, size_t results_limit, //
+    usearch_key_t* found_keys, usearch_distance_t* found_distances, usearch_error_t* error) {
+
+    USEARCH_ASSERT(index && query && error && "Missing arguments");
+    search_result_t result =
+        search_(reinterpret_cast<index_dense_t*>(index), query, scalar_kind_to_cpp(query_kind), results_limit);
+    if (!result) {
+        *error = result.error.release();
+        return 0;
+    }
+
+    return result.dump_to(found_keys, found_distances);
+}
+
+USEARCH_EXPORT size_t usearch_filtered_search(                                 //
+    usearch_index_t index,                                                     //
+    void const* query, usearch_scalar_kind_t query_kind, size_t results_limit, //
+    int (*filter)(usearch_key_t key, void* filter_state), void* filter_state,  //
     usearch_key_t* found_keys, usearch_distance_t* found_distances, usearch_error_t* error) {
 
-    assert(index && vector && error && "Missing arguments");
+    USEARCH_ASSERT(index && query && filter && error && "Missing arguments");
     search_result_t result =
-        search_(reinterpret_cast<index_dense_t*>(index), vector, scalar_kind_to_cpp(kind), results_limit);
+        search_(reinterpret_cast<index_dense_t*>(index), query, scalar_kind_to_cpp(query_kind), results_limit,
+                [=](usearch_key_t key) noexcept { return filter(key, filter_state); });
     if (!result) {
         *error = result.error.release();
         return 0;
@@ -292,13 +389,13 @@ USEARCH_EXPORT size_t usearch_get(                          //
     usearch_index_t index, usearch_key_t key, size_t count, //
     void* vectors, usearch_scalar_kind_t kind, usearch_error_t*) {
 
-    assert(index && vectors);
+    USEARCH_ASSERT(index && vectors);
     return get_(reinterpret_cast<index_dense_t*>(index), key, count, vectors, scalar_kind_to_cpp(kind));
 }
 
 USEARCH_EXPORT size_t usearch_remove(usearch_index_t index, usearch_key_t key, usearch_error_t* error) {
 
-    assert(index && error && "Missing arguments");
+    USEARCH_ASSERT(index && error && "Missing arguments");
     labeling_result_t result = reinterpret_cast<index_dense_t*>(index)->remove(key);
     if (!result)
         *error = result.error.release();
@@ -308,7 +405,7 @@ USEARCH_EXPORT size_t usearch_remove(usearch_index_t index, usearch_key_t key, u
 USEARCH_EXPORT size_t usearch_rename( //
     usearch_index_t index, usearch_key_t from, usearch_key_t to, usearch_error_t* error) {
 
-    assert(index && error && "Missing arguments");
+    USEARCH_ASSERT(index && error && "Missing arguments");
     labeling_result_t result = reinterpret_cast<index_dense_t*>(index)->rename(from, to);
     if (!result)
         *error = result.error.release();
@@ -334,7 +431,7 @@ USEARCH_EXPORT void usearch_exact_search(                             //
     usearch_distance_t* distances, size_t distances_stride,           //
     usearch_error_t* error) {
 
-    assert(dataset && queries && keys && distances && error && "Missing arguments");
+    USEARCH_ASSERT(dataset && queries && keys && distances && error && "Missing arguments");
 
     metric_punned_t metric(dimensions, metric_kind_to_cpp(metric_kind), scalar_kind_to_cpp(scalar_kind));
     executor_default_t executor(threads);

package/c/test.c

@@ -72,6 +72,8 @@ void test_init(size_t const collection_size, size_t const dimensions) {
     ASSERT(usearch_capacity(index, &error) == collection_size, error);
     ASSERT(usearch_dimensions(index, &error) == dimensions, error);
     ASSERT(usearch_connectivity(index, &error) == opts.connectivity, error);
+    ASSERT(usearch_hardware_acceleration(index, &error), error);
+    ASSERT(usearch_memory_usage(index, &error), error);
 
     usearch_free(index, &error);
     ASSERT(!error, error);
@@ -361,6 +363,8 @@ void test_view(size_t const collection_size, size_t const dimensions) {
 }
 
 int main(int argc, char const* argv[]) {
+    printf("Running tests...\n");
+    printf("USearch version: %s\n", usearch_version());
 
     size_t collection_sizes[] = {11, 512};
     size_t dimensions[] = {83, 2}; // Not all distance functions make sense for 1 dimensional data

package/c/usearch.h

@@ -97,6 +97,12 @@ USEARCH_EXPORT typedef struct usearch_init_options_t {
     bool multi;
 } usearch_init_options_t;
 
+/**
+ *  @brief Retrieves the version of the library.
+ *  @return The version of the library.
+ */
+USEARCH_EXPORT char const* usearch_version(void);
+
 /**
  *  @brief Initializes a new instance of the index.
  *  @param options Pointer to the `usearch_init_options_t` structure containing initialization options.
@@ -112,6 +118,22 @@ USEARCH_EXPORT usearch_index_t usearch_init(usearch_init_options_t* options, use
  */
 USEARCH_EXPORT void usearch_free(usearch_index_t index, usearch_error_t* error);
 
+/**
+ *  @brief Reports the memory usage of the index.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return Number of bytes used by the index.
+ */
+USEARCH_EXPORT size_t usearch_memory_usage(usearch_index_t index, usearch_error_t* error);
+
+/**
+ *  @brief Reports the SIMD capabilities used by the index on the current CPU.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return The codename of the SIMD instruction set used by the index.
+ */
+USEARCH_EXPORT char const* usearch_hardware_acceleration(usearch_index_t index, usearch_error_t* error);
+
 /**
  *  @brief Reports expected file size after serialization.
  *  @param[in] index The handle to the USearch index to be serialized.
@@ -227,6 +249,58 @@ USEARCH_EXPORT size_t usearch_connectivity(usearch_index_t index, usearch_error_
  */
 USEARCH_EXPORT void usearch_reserve(usearch_index_t index, size_t capacity, usearch_error_t* error);
 
+/**
+ *  @brief Retrieves the expansion value used during index creation.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return The expansion value used during index creation.
+ */
+USEARCH_EXPORT size_t usearch_expansion_add(usearch_index_t index, usearch_error_t* error);
+
+/**
+ *  @brief Retrieves the expansion value used during search.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return The expansion value used during search.
+ */
+USEARCH_EXPORT size_t usearch_expansion_search(usearch_index_t index, usearch_error_t* error);
+
+/**
+ *  @brief Updates the expansion value used during index creation. Rarely used.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[in] expansion The new expansion value.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_change_expansion_add(usearch_index_t index, size_t expansion, usearch_error_t* error);
+
+/**
+ *  @brief Updates the expansion value used during search. Rarely used.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[in] expansion The new expansion value.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_change_expansion_search(usearch_index_t index, size_t expansion, usearch_error_t* error);
+
+/**
+ *  @brief Updates the metric kind used for distance calculation between vectors.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[in] kind The metric kind used for distance calculation between vectors.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_change_metric_kind(usearch_index_t index, usearch_metric_kind_t kind,
+                                               usearch_error_t* error);
+
+/**
+ *  @brief Updates the custom metric function used for distance calculation between vectors.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[in] metric The custom metric function used for distance calculation between vectors.
+ *  @param[in] state The @b optional state pointer to be passed to the custom metric function.
+ *  @param[in] kind The metric kind used for distance calculation between vectors. Needed for serialization.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_change_metric(usearch_index_t index, usearch_metric_t metric, void* state,
+                                          usearch_metric_kind_t kind, usearch_error_t* error);
+
 /**
  *  @brief Adds a vector with a key to the index.
  *  @param[inout] index The handle to the USearch index to be populated.
@@ -268,10 +342,31 @@ USEARCH_EXPORT size_t usearch_count(usearch_index_t index, usearch_key_t, usearc
  *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
  *  @return Number of found matches.
  */
-USEARCH_EXPORT size_t usearch_search(                           //
-    usearch_index_t index,                                      //
-    void const* query_vector, usearch_scalar_kind_t query_kind, //
-    size_t count, usearch_key_t* keys, usearch_distance_t* distances, usearch_error_t* error);
+USEARCH_EXPORT size_t usearch_search(                                         //
+    usearch_index_t index,                                                    //
+    void const* query_vector, usearch_scalar_kind_t query_kind, size_t count, //
+    usearch_key_t* keys, usearch_distance_t* distances, usearch_error_t* error);
+
+/**
+ *  @brief  Performs k-Approximate Nearest Neighbors (kANN) Search for closest vectors to query,
+ *          predicated on a custom function that returns `true` for vectors to be included.
+ *
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[in] query_vector Pointer to the query vector data.
+ *  @param[in] query_kind The scalar type used in the query vector data.
+ *  @param[in] count Upper bound on the number of neighbors to search, the "k" in "kANN".
+ *  @param[in] filter The custom filter function that returns `true` for vectors to be included.
+ *  @param[in] filter_state The @b optional state pointer to be passed to the custom filter function.
+ *  @param[out] keys Output buffer for up to `count` nearest neighbors keys.
+ *  @param[out] distances Output buffer for up to `count` distances to nearest neighbors.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return Number of found matches.
+ */
+USEARCH_EXPORT size_t usearch_filtered_search(                                //
+    usearch_index_t index,                                                    //
+    void const* query_vector, usearch_scalar_kind_t query_kind, size_t count, //
+    int (*filter)(usearch_key_t key, void* filter_state), void* filter_state, //
+    usearch_key_t* keys, usearch_distance_t* distances, usearch_error_t* error);
 
 /**
  *  @brief Retrieves the vector associated with the given key from the index.

package/cpp/README.md

@@ -71,8 +71,19 @@ Instead of spawning additional threads within USearch, we focus on the thread sa
 
 During initialization, we allocate enough temporary memory for all the cores on the machine.
 On the call, the user can supply the identifier of the current thread, making this library easy to integrate with OpenMP and similar tools.
+Here is how parallel indexing may look like, when dealing with the low-level engine:
 
-Moreover, you can take advantage of one of the provided "executors" to parallelize the search:
+```cpp
+std::size_t executor_threads = std::thread::hardware_concurrency() * 4;
+executor_default_t executor(executor_threads);
+
+index.reserve(index_limits_t {vectors.size(), executor.size()});
+executor.fixed(vectors.size(), [&](std::size_t thread, std::size_t task) {
+    index.add(task, vectors[task + 3].data(), index_update_config_t { .thread = thread });
+});
+```
+
+Aside from the `executor_default_t`, you can take advantage of one of the provided "executors" to parallelize the search:
 
 - `executor_openmp_t`, that would use OpenMP under the hood.
 - `executor_stl_t`, that will spawn `std::thread` instances.

package/cpp/test.cpp

@@ -65,6 +65,17 @@ void test_cosine(index_at& index, std::vector<std::vector<scalar_at>> const& vec
 
     // Perform exact search
     matched_count = index.search(vector_first, 5, args...).dump_to(matched_keys, matched_distances);
+    expect(matched_count != 0);
+
+    // Perform filtered exact search, keeping only odd values
+    if constexpr (punned_ak) {
+        auto is_odd = [](vector_key_t key) -> bool { return (key & 1) != 0; };
+        matched_count =
+            index.filtered_search(vector_first, 5, is_odd, args...).dump_to(matched_keys, matched_distances);
+        expect(matched_count != 0);
+        for (std::size_t i = 0; i < matched_count; i++)
+            expect(is_odd(matched_keys[i]));
+    }
 
     // Validate scans
     std::size_t count = 0;
@@ -103,8 +114,9 @@ void test_cosine(index_at& index, std::vector<std::vector<scalar_at>> const& vec
         expect(std::equal(vector_second, vector_second + dimensions, vec_recovered_from_load.data()));
     }
 
-    // Try batch requests
-    executor_default_t executor;
+    // Try batch requests, heavily obersubscribing the CPU cores
+    std::size_t executor_threads = std::thread::hardware_concurrency() * 4;
+    executor_default_t executor(executor_threads);
     index.reserve({vectors.size(), executor.size()});
     executor.fixed(vectors.size() - 3, [&](std::size_t thread, std::size_t task) {
         if constexpr (punned_ak) {

package/include/usearch/index.hpp

@@ -10,8 +10,8 @@
 #define UNUM_USEARCH_HPP
 
 #define USEARCH_VERSION_MAJOR 2
-#define USEARCH_VERSION_MINOR 10
-#define USEARCH_VERSION_PATCH 5
+#define USEARCH_VERSION_MINOR 11
+#define USEARCH_VERSION_PATCH 1
 
 // Inferring C++ version
 // https://stackoverflow.com/a/61552074
@@ -3497,9 +3497,12 @@ class index_gt {
 
         distance_t radius = context.measure(query, citerator_at(start_slot), metric);
         next.insert_reserved({-radius, static_cast<compressed_slot_t>(start_slot)});
-        top.insert_reserved({radius, static_cast<compressed_slot_t>(start_slot)});
         visits.set(static_cast<compressed_slot_t>(start_slot));
 
+        // Don't populate the top list if the predicate is not satisfied
+        if (is_dummy<predicate_at>() || predicate(member_cref_t{node_at_(start_slot).ckey(), start_slot}))
+            top.insert_reserved({radius, static_cast<compressed_slot_t>(start_slot)});
+
         while (!next.empty()) {
 
             candidate_t candidate = next.top();
@@ -3529,12 +3532,9 @@ class index_gt {
                 if (top.size() < top_limit || successor_dist < radius) {
                     // This can substantially grow our priority queue:
                     next.insert({-successor_dist, successor_slot});
-                    if (!is_dummy<predicate_at>())
-                        if (!predicate(member_cref_t{node_at_(successor_slot).ckey(), successor_slot}))
-                            continue;
-
-                    // This will automatically evict poor matches:
-                    top.insert({successor_dist, successor_slot}, top_limit);
+                    if (is_dummy<predicate_at>() ||
+                        predicate(member_cref_t{node_at_(successor_slot).ckey(), successor_slot}))
+                        top.insert({successor_dist, successor_slot}, top_limit);
                     radius = top.top().distance;
                 }
             }