usearch 2.3.2 → 2.4.1

package/docs/format.md

@@ -1,48 +1,71 @@
-# USearch Format Specification
+# USearch File Format Specification
 
-> ⚠️ **Note**: The format is expected to change in the 3.0 release to support sparse indexes and offer even faster startup times when `view`-ing large indexes from disk.
+> ⚠️ __Important Note__: The file format is slated for updates in the upcoming 3.0 release. These changes aim to support sparse indexes and enhance startup performance when loading large indexes from disk using the `view` command.
 
-## Table of Contents
+## Upcoming Version: v3
 
-- [Dense Indexes](#dense-indexes)
-- [Core](#core)
-- [Fragmented Storage](#fragmented-storage)
+The v3 file format is designed for compatibility with Apache Arrow arrays and consists of an array of variable-length binary strings. The structure for a file with `N` entries is as follows:
 
-## Dense Indexes
+### File Structure
+
+1. __File Header__: Metadata and other essential information.
+2. __Offset Array__: An array of `N+1` eight-byte unsigned integers (`uint64_t`).
+    - The entry at index `0 <= i < N` indicates the byte-level offset of the `i-th` vector in the file.
+    - The entry at index `N` specifies the total length of the binary file.
+3. __Data Chunks__: `N` binary data chunks, each starting with the vector itself, followed by index system data.
+
+### Data Retrieval
+
+To retrieve the Binary Large Object (BLOB) corresponding to a specific vector, subtract the consecutive offsets indicated in the Offset Array.
+
+### Advantages of the v3 Format
+
+The v3 format offers several benefits, making it more future-proof:
+
+- __Flexibility__: Easily accommodates variable-length strings.
+- __Performance__: Co-locates vectors with proximity graph entries for optimized data access.
+- __Compatibility__: Simplifies memory-mapping and casting to an Apache Arrow array of vectors or strings.
+- __Extensibility__: Enables external storage systems to reuse the underlying `index_gt` more extensively, particularly in database systems.
+
+---
+
+## Current: v2
+
+### Dense Indexes
 
 Dense index files consist of two main parts: [a binary matrix of all vectors](#matrix-blob) and the [index](#index-blob) itself.
 
-### Matrix BLOB
+#### Matrix BLOB
 
 The matrix BLOB is optionally prepended to the index file. It starts with the number of `rows` and `columns`, which can be either 32-bit or 64-bit unsigned integers.
 
 - The number of `rows` corresponds to the number of vectors in the index.
 - The number of `columns` corresponds to the number of bytes in a single vector.
 
-### Index BLOB
+#### Index BLOB
 
 The index BLOB is composed of three main sections:
 
-1. **Metadata**: Occupies 64 bytes and contains the following fields:
+1. __Metadata__: Occupies 64 bytes and contains the following fields:
     1. 7-byte magic string `usearch` to infer the MIME type of the file.
     2. 3-byte version number, containing the `major`, `minor`, and `patch` release numbers.
     3. 1-byte enums for `metric`, `scalar`, `key`, and `compressed_slot` types.
     4. 8-byte integers for the number of present vectors, number of deleted vectors, and number of dimensions.
     5. 1-byte flags for multi-vector support.
 
-2. **Levels**: Contains 1-byte integers representing the level each node occupies. This information is used to estimate memory requirements and to enable memory-mapping of the entire file.
+2. __Levels__: Contains 1-byte integers representing the level each node occupies. This information is used to estimate memory requirements and to enable memory-mapping of the entire file.
 
-3. **Core**: Detailed in the [Core section](#core). This format is consistent across all types of indexes.
+3. __Core__: Detailed in the [Core section](#core). This format is consistent across all types of indexes.
 
-## Fragmented Storage
+### Fragmented Storage
 
 The matrix BLOB can be stored separately and is not required to successfully open the file.
 
-## Core
+### Core
 
 The core section of the index is serialized as a sequence of nodes, each representing a point in the index. This section immediately follows the `levels` block in the serialized format.
 
-### Header
+#### Header
 
 The core section begins with a header containing the following fields:
 
@@ -54,10 +77,10 @@ The core section begins with a header containing the following fields:
 
 These fields are serialized in a contiguous block of bytes, in the order listed.
 
-### Levels
+#### Levels
 
 Following the header, the `levels` block contains a sequence of 1-byte integers. Each integer represents the level of a node in the index. The number of levels is equal to the `size` field in the header.
 
-### Nodes
+#### Nodes
 
 After the `levels` block, the nodes are serialized. Each node is represented as a contiguous block of bytes. The size and format of these blocks are implementation-specific. Nodes are serialized in the same order as their corresponding levels in the `levels` block.

package/include/usearch/index.hpp

@@ -10,8 +10,8 @@
 #define UNUM_USEARCH_HPP
 
 #define USEARCH_VERSION_MAJOR 2
-#define USEARCH_VERSION_MINOR 3
-#define USEARCH_VERSION_PATCH 2
+#define USEARCH_VERSION_MINOR 4
+#define USEARCH_VERSION_PATCH 1
 
 // Inferring C++ version
 // https://stackoverflow.com/a/61552074

package/include/usearch/index_dense.hpp

@@ -1,12 +1,11 @@
 #pragma once
 #include <stdlib.h> // `aligned_alloc`
 
-#include <functional>    // `std::function`
-#include <numeric>       // `std::iota`
-#include <shared_mutex>  // `std::shared_mutex`
-#include <thread>        // `std::thread`
-#include <unordered_set> // `std::unordered_multiset`
-#include <vector>        // `std::vector`
+#include <functional>   // `std::function`
+#include <numeric>      // `std::iota`
+#include <shared_mutex> // `std::shared_mutex`
+#include <thread>       // `std::thread`
+#include <vector>       // `std::vector`
 
 #include <usearch/index.hpp>
 #include <usearch/index_plugins.hpp>
@@ -93,6 +92,17 @@ struct index_dense_config_t : public index_config_t {
     bool exclude_vectors = false;
     bool multi = false;
 
+    /**
+     *  @brief  Allows you to reduce RAM consumption by avoiding
+     *          reverse-indexing keys-to-vectors, and only keeping
+     *          the vectors-to-keys mappings.
+     *
+     *  ! This configuration parameter doesn't affect the serialized file,
+     *  ! and is not preserved between runs. Makes sense for small vector
+     *  ! representations that fit ina  single cache line.
+     */
+    bool enable_key_lookups = true;
+
     index_dense_config_t(index_config_t base) noexcept : index_config_t(base) {}
 
     index_dense_config_t(                                  //
@@ -399,7 +409,7 @@ class index_dense_gt {
     };
 
     /// @brief Multi-Map from keys to IDs, and allocated vectors.
-    std::unordered_multiset<key_and_slot_t, lookup_key_hash_t, lookup_key_same_t> slot_lookup_;
+    flat_hash_multi_set_gt<key_and_slot_t, lookup_key_hash_t, lookup_key_same_t> slot_lookup_;
 
     /// @brief Mutex, controlling concurrent access to `slot_lookup_`.
     mutable shared_mutex_t slot_lookup_mutex_;
@@ -1149,7 +1159,7 @@ class index_dense_gt {
      */
     bool contains(key_t key) const {
         shared_lock_t lock(slot_lookup_mutex_);
-        return slot_lookup_.find(key_and_slot_t::any_slot(key)) != slot_lookup_.end();
+        return slot_lookup_.contains(key_and_slot_t::any_slot(key));
     }
 
     /**
@@ -1203,7 +1213,7 @@ class index_dense_gt {
             free_keys_.push(slot);
             typed_->at(slot).key = free_key_;
         }
-        slot_lookup_.erase(matching_slots.first, matching_slots.second);
+        slot_lookup_.erase(key);
         result.completed = matching_count;
 
         return result;
@@ -1239,14 +1249,15 @@ class index_dense_gt {
             // - present in `free_keys_`
             // - missing in the `slot_lookup_`
             // - marked in the `typed_` index with a `free_key_`
+            matching_count = 0;
             for (auto slots_it = matching_slots.first; slots_it != matching_slots.second; ++slots_it) {
                 compressed_slot_t slot = (*slots_it).slot;
                 free_keys_.push(slot);
                 typed_->at(slot).key = free_key_;
+                ++matching_count;
             }
 
-            matching_count = std::distance(matching_slots.first, matching_slots.second);
-            slot_lookup_.erase(matching_slots.first, matching_slots.second);
+            slot_lookup_.erase(key);
             result.completed += matching_count;
         }
 
@@ -1265,20 +1276,18 @@ class index_dense_gt {
         labeling_result_t result;
         unique_lock_t lookup_lock(slot_lookup_mutex_);
 
-        if (!multi() && slot_lookup_.count(key_and_slot_t::any_slot(to)))
+        if (!multi() && slot_lookup_.contains(key_and_slot_t::any_slot(to)))
             return result.failed("Renaming impossible, the key is already in use");
 
         // The `from` may map to multiple entries
         while (true) {
-            auto slots_it = slot_lookup_.find(key_and_slot_t::any_slot(from));
-            if (slots_it == slot_lookup_.end())
+            key_and_slot_t key_and_slot_removed;
+            if (!slot_lookup_.pop_first(key_and_slot_t::any_slot(from), key_and_slot_removed))
                 break;
 
-            compressed_slot_t slot = (*slots_it).slot;
-            key_and_slot_t key_and_slot{to, slot};
-            slot_lookup_.erase(slots_it);
-            slot_lookup_.insert(key_and_slot);
-            typed_->at(slot).key = to;
+            key_and_slot_t key_and_slot_replacing{to, key_and_slot_removed.slot};
+            slot_lookup_.try_emplace(key_and_slot_replacing); // This can't fail
+            typed_->at(key_and_slot_removed.slot).key = to;
             ++result.completed;
         }
 
@@ -1293,11 +1302,18 @@ class index_dense_gt {
      */
     void export_keys(key_t* keys, std::size_t offset, std::size_t limit) const {
         shared_lock_t lock(slot_lookup_mutex_);
-        auto it = slot_lookup_.begin();
         offset = (std::min)(offset, slot_lookup_.size());
-        std::advance(it, offset);
-        for (; it != slot_lookup_.end() && limit; ++it, ++keys, --limit)
-            *keys = (*it).key;
+        slot_lookup_.for_each([&](key_and_slot_t const& key_and_slot) {
+            if (offset) {
+                --offset;
+                return;
+            }
+            if (limit) {
+                *keys = key_and_slot.key;
+                ++keys;
+                --limit;
+            }
+        });
     }
 
     struct copy_result_t {
@@ -1720,7 +1736,7 @@ class index_dense_gt {
         bool reuse_node = free_slot != default_free_value<compressed_slot_t>();
         auto on_success = [&](member_ref_t member) {
             unique_lock_t slot_lock(slot_lookup_mutex_);
-            slot_lookup_.insert(key_and_slot_t{key, static_cast<compressed_slot_t>(member.slot)});
+            slot_lookup_.try_emplace(key_and_slot_t{key, static_cast<compressed_slot_t>(member.slot)});
             if (copy_vector) {
                 if (!reuse_node)
                     vectors_lookup_[member.slot] = vectors_tape_allocator_.allocate(metric_.bytes_per_vector());
@@ -1842,19 +1858,23 @@ class index_dense_gt {
             count_removed += member.key == free_key_;
         }
 
+        if (!count_removed && !config_.enable_key_lookups)
+            return;
+
         // Pull entries from the underlying `typed_` into either
         // into `slot_lookup_`, or `free_keys_` if they are unused.
         unique_lock_t lock(slot_lookup_mutex_);
         slot_lookup_.clear();
-        slot_lookup_.reserve(count_total - count_removed);
+        if (config_.enable_key_lookups)
+            slot_lookup_.reserve(count_total - count_removed);
         free_keys_.clear();
         free_keys_.reserve(count_removed);
         for (std::size_t i = 0; i != typed_->size(); ++i) {
             member_cref_t member = typed_->at(i);
             if (member.key == free_key_)
                 free_keys_.push(static_cast<compressed_slot_t>(i));
-            else
-                slot_lookup_.insert(key_and_slot_t{key_t(member.key), static_cast<compressed_slot_t>(i)});
+            else if (config_.enable_key_lookups)
+                slot_lookup_.try_emplace(key_and_slot_t{key_t(member.key), static_cast<compressed_slot_t>(i)});
         }
     }