usearch 2.4.0 → 2.5.0

package/rust/lib.rs

@@ -33,198 +33,331 @@ pub mod ffi {
         connectivity: usize,
         expansion_add: usize,
         expansion_search: usize,
+        multi: bool,
     }
 
     // C++ types and signatures exposed to Rust.
     unsafe extern "C++" {
         include!("lib.hpp");
 
-        /// Represents the USearch index.
-        type Index;
-
-        /// Initializes a new instance of the index with the provided options.
-        ///
-        /// # Arguments
-        ///
-        /// * `options` - A reference to the `IndexOptions` structure containing initialization options.
-        ///
-        /// # Returns
-        ///
-        /// A `Result` which is `Ok` if the index is successfully initialized, or `Err` if an error occurs.
-        pub fn new_index(options: &IndexOptions) -> Result<UniquePtr<Index>>;
-
-        /// Reserves memory for a specified number of incoming vectors.
-        ///
-        /// # Arguments
-        ///
-        /// * `capacity` - The desired total capacity including the current size.
-        pub fn reserve(self: &Index, capacity: usize) -> Result<()>;
-
-        /// Retrieves the number of dimensions in the vectors indexed.
-        pub fn dimensions(self: &Index) -> usize;
-
-        /// Retrieves the connectivity parameter that limits connections-per-node in the graph.
-        pub fn connectivity(self: &Index) -> usize;
-
-        /// Retrieves the current number of vectors in the index.
-        pub fn size(self: &Index) -> usize;
-
-        /// Retrieves the total capacity of the index, including reserved space.
-        pub fn capacity(self: &Index) -> usize;
-
-        /// Reports expected file size after serialization.
-        pub fn serialized_length(self: &Index) -> usize;
-
-        /// Adds a vector with a specified key to the index.
-        ///
-        /// # Arguments
-        ///
-        /// * `key` - The key associated with the vector.
-        /// * `vector` - A slice containing the vector data.
-        fn add<T>(self: &Index, key: u64, vector: &[T]) -> Result<()> {
-            // Use type-based dispatch
-            if std::any::TypeId::of::<T>() == std::any::TypeId::of::<i8>() {
-                add_i8(key, unsafe { std::mem::transmute::<&[T], &[i8]>(vector) })
-            } else if std::any::TypeId::of::<T>() == std::any::TypeId::of::<f32>() {
-                add_f32(key, unsafe { std::mem::transmute::<&[T], &[f32]>(vector) })
-            } else if std::any::TypeId::of::<T>() == std::any::TypeId::of::<f64>() {
-                add_f64(key, unsafe { std::mem::transmute::<&[T], &[f64]>(vector) })
-            } else {
-                Err(Box::new("Unsupported type"))
-            }
+        /// Low-level C++ interface, that is further wrapped into the high-level `Index`
+        type NativeIndex;
+
+        pub fn new_native_index(options: &IndexOptions) -> Result<UniquePtr<NativeIndex>>;
+        pub fn reserve(self: &NativeIndex, capacity: usize) -> Result<()>;
+        pub fn dimensions(self: &NativeIndex) -> usize;
+        pub fn connectivity(self: &NativeIndex) -> usize;
+        pub fn size(self: &NativeIndex) -> usize;
+        pub fn capacity(self: &NativeIndex) -> usize;
+        pub fn serialized_length(self: &NativeIndex) -> usize;
+
+        pub fn add_i8(self: &NativeIndex, key: u64, vector: &[i8]) -> Result<()>;
+        pub fn add_f16(self: &NativeIndex, key: u64, vector: &[u16]) -> Result<()>;
+        pub fn add_f32(self: &NativeIndex, key: u64, vector: &[f32]) -> Result<()>;
+        pub fn add_f64(self: &NativeIndex, key: u64, vector: &[f64]) -> Result<()>;
+
+        pub fn search_i8(self: &NativeIndex, query: &[i8], count: usize) -> Result<Matches>;
+        pub fn search_f16(self: &NativeIndex, query: &[u16], count: usize) -> Result<Matches>;
+        pub fn search_f32(self: &NativeIndex, query: &[f32], count: usize) -> Result<Matches>;
+        pub fn search_f64(self: &NativeIndex, query: &[f64], count: usize) -> Result<Matches>;
+
+        pub fn get_i8(self: &NativeIndex, key: u64, buffer: &mut [i8]) -> Result<usize>;
+        pub fn get_f16(self: &NativeIndex, key: u64, buffer: &mut [u16]) -> Result<usize>;
+        pub fn get_f32(self: &NativeIndex, key: u64, buffer: &mut [f32]) -> Result<usize>;
+        pub fn get_f64(self: &NativeIndex, key: u64, buffer: &mut [f64]) -> Result<usize>;
+
+        pub fn remove(self: &NativeIndex, key: u64) -> Result<usize>;
+        pub fn rename(self: &NativeIndex, from: u64, to: u64) -> Result<usize>;
+        pub fn contains(self: &NativeIndex, key: u64) -> bool;
+        pub fn count(self: &NativeIndex, key: u64) -> usize;
+
+        pub fn save(self: &NativeIndex, path: &str) -> Result<()>;
+        pub fn load(self: &NativeIndex, path: &str) -> Result<()>;
+        pub fn view(self: &NativeIndex, path: &str) -> Result<()>;
+        pub fn save_to_buffer(self: &NativeIndex, buffer: &mut [u8]) -> Result<()>;
+        pub fn load_from_buffer(self: &NativeIndex, buffer: &[u8]) -> Result<()>;
+        pub fn view_from_buffer(self: &NativeIndex, buffer: &[u8]) -> Result<()>;
+    }
+}
+
+pub struct Index {
+    inner: cxx::UniquePtr<ffi::NativeIndex>,
+}
+
+impl Default for ffi::IndexOptions {
+    fn default() -> Self {
+        use crate::ffi::MetricKind;
+        use crate::ffi::ScalarKind;
+        Self {
+            dimensions: 128,
+            metric: MetricKind::IP,
+            quantization: ScalarKind::F32,
+            connectivity: 32,
+            expansion_add: 2,
+            expansion_search: 3,
+            multi: false,
         }
+    }
+}
 
-        pub fn add_i8(self: &Index, key: u64, vector: &[i8]) -> Result<()>;
-        pub fn add_f16(self: &Index, key: u64, vector: &[u16]) -> Result<()>;
-        pub fn add_f32(self: &Index, key: u64, vector: &[f32]) -> Result<()>;
-        pub fn add_f64(self: &Index, key: u64, vector: &[f64]) -> Result<()>;
-
-        /// Performs k-Approximate Nearest Neighbors (kANN) Search for closest vectors to the provided query.
-        ///
-        /// # Arguments
-        ///
-        /// * `query` - A slice containing the query vector data.
-        /// * `count` - The maximum number of neighbors to search for.
-        ///
-        /// # Returns
-        ///
-        /// A `Result` containing the matches found.
-        pub fn search<T>(self: &Index, query: &[T], count: usize) -> Result<Matches> {
-            // Use type-based dispatch
-            if std::any::TypeId::of::<T>() == std::any::TypeId::of::<i8>() {
-                search_i8(unsafe { std::mem::transmute::<&[T], &[i8]>(query) }, count)
-            } else if std::any::TypeId::of::<T>() == std::any::TypeId::of::<f32>() {
-                search_f32(unsafe { std::mem::transmute::<&[T], &[f32]>(query) }, count)
-            } else if std::any::TypeId::of::<T>() == std::any::TypeId::of::<f64>() {
-                search_f64(unsafe { std::mem::transmute::<&[T], &[f64]>(query) }, count)
-            } else {
-                Err(Box::new("Unsupported type"))
-            }
+pub trait VectorType {
+    fn add(index: &Index, key: u64, vector: &[Self]) -> Result<(), cxx::Exception>
+    where
+        Self: Sized;
+    fn get(index: &Index, key: u64, buffer: &mut [Self]) -> Result<usize, cxx::Exception>
+    where
+        Self: Sized;
+    fn search(index: &Index, query: &[Self], count: usize) -> Result<ffi::Matches, cxx::Exception>
+    where
+        Self: Sized;
+}
+
+impl VectorType for i8 {
+    fn search(index: &Index, query: &[Self], count: usize) -> Result<ffi::Matches, cxx::Exception> {
+        index.inner.search_i8(query, count)
+    }
+    fn get(index: &Index, key: u64, vector: &mut [Self]) -> Result<usize, cxx::Exception> {
+        index.inner.get_i8(key, vector)
+    }
+    fn add(index: &Index, key: u64, vector: &[Self]) -> Result<(), cxx::Exception> {
+        index.inner.add_i8(key, vector)
+    }
+}
+
+impl VectorType for f32 {
+    fn search(index: &Index, query: &[Self], count: usize) -> Result<ffi::Matches, cxx::Exception> {
+        index.inner.search_f32(query, count)
+    }
+    fn get(index: &Index, key: u64, vector: &mut [Self]) -> Result<usize, cxx::Exception> {
+        index.inner.get_f32(key, vector)
+    }
+    fn add(index: &Index, key: u64, vector: &[Self]) -> Result<(), cxx::Exception> {
+        index.inner.add_f32(key, vector)
+    }
+}
+
+impl VectorType for f64 {
+    fn search(index: &Index, query: &[Self], count: usize) -> Result<ffi::Matches, cxx::Exception> {
+        index.inner.search_f64(query, count)
+    }
+    fn get(index: &Index, key: u64, vector: &mut [Self]) -> Result<usize, cxx::Exception> {
+        index.inner.get_f64(key, vector)
+    }
+    fn add(index: &Index, key: u64, vector: &[Self]) -> Result<(), cxx::Exception> {
+        index.inner.add_f64(key, vector)
+    }
+}
+
+impl Index {
+    pub fn new(options: &ffi::IndexOptions) -> Result<Self, cxx::Exception> {
+        match ffi::new_native_index(options) {
+            Ok(inner) => Result::Ok(Self { inner }),
+            Err(err) => Err(err),
         }
+    }
+
+    /// Performs k-Approximate Nearest Neighbors (kANN) Search for closest vectors to the provided query.
+    ///
+    /// # Arguments
+    ///
+    /// * `query` - A slice containing the query vector data.
+    /// * `count` - The maximum number of neighbors to search for.
+    ///
+    /// # Returns
+    ///
+    /// A `Result` containing the matches found.
+    pub fn search<T: VectorType>(
+        self: &Index,
+        query: &[T],
+        count: usize,
+    ) -> Result<ffi::Matches, cxx::Exception> {
+        T::search(self, query, count)
+    }
+
+    /// Adds a vector with a specified key to the index.
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - The key associated with the vector.
+    /// * `vector` - A slice containing the vector data.
+    pub fn add<T: VectorType>(self: &Index, key: u64, vector: &[T]) -> Result<(), cxx::Exception> {
+        T::add(self, key, vector)
+    }
+
+    /// Extracts one or more vectors matching specified key.
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - The key associated with the vector.
+    /// * `vector` - A slice containing the vector data.
+    pub fn get<T: VectorType>(
+        self: &Index,
+        key: u64,
+        vector: &mut [T],
+    ) -> Result<usize, cxx::Exception> {
+        T::get(self, key, vector)
+    }
 
-        pub fn search_i8(self: &Index, query: &[i8], count: usize) -> Result<Matches>;
-        pub fn search_f16(self: &Index, query: &[u16], count: usize) -> Result<Matches>;
-        pub fn search_f32(self: &Index, query: &[f32], count: usize) -> Result<Matches>;
-        pub fn search_f64(self: &Index, query: &[f64], count: usize) -> Result<Matches>;
-
-        /// Removes the vector associated with the given key from the index.
-        ///
-        /// # Arguments
-        ///
-        /// * `key` - The key of the vector to be removed.
-        ///
-        /// # Returns
-        ///
-        /// `true` if the vector is successfully removed, `false` otherwise.
-        pub fn remove(self: &Index, key: u64) -> Result<bool>;
-
-        /// Renames the vector under a certain key.
-        ///
-        /// # Arguments
-        ///
-        /// * `from` - The key of the vector to be renamed.
-        /// * `to` - The new name.
-        ///
-        /// # Returns
-        ///
-        /// `true` if the vector is successfully renamed, `false` otherwise.
-        pub fn rename(self: &Index, from: u64, to: u64) -> Result<bool>;
-
-        /// Checks if the index contains a vector with a specified key.
-        ///
-        /// # Arguments
-        ///
-        /// * `key` - The key to be checked.
-        ///
-        /// # Returns
-        ///
-        /// `true` if the index contains the vector with the given key, `false` otherwise.
-        pub fn contains(self: &Index, key: u64) -> bool;
-
-        /// Saves the index to a specified file.
-        ///
-        /// # Arguments
-        ///
-        /// * `path` - The file path where the index will be saved.
-        pub fn save(self: &Index, path: &str) -> Result<()>;
-
-        /// Loads the index from a specified file.
-        ///
-        /// # Arguments
-        ///
-        /// * `path` - The file path from where the index will be loaded.
-        pub fn load(self: &Index, path: &str) -> Result<()>;
-
-        /// Creates a view of the index from a file without loading it into memory.
-        ///
-        /// # Arguments
-        ///
-        /// * `path` - The file path from where the view will be created.
-        pub fn view(self: &Index, path: &str) -> Result<()>;
-
-        /// Saves the index to a specified file.
-        ///
-        /// # Arguments
-        ///
-        /// * `path` - The file path where the index will be saved.
-        pub fn save_to_buffer(self: &Index, buffer: &mut [u8]) -> Result<()>;
-
-        /// Loads the index from a specified file.
-        ///
-        /// # Arguments
-        ///
-        /// * `path` - The file path from where the index will be loaded.
-        pub fn load_from_buffer(self: &Index, buffer: &[u8]) -> Result<()>;
-
-        /// Creates a view of the index from a file without loading it into memory.
-        ///
-        /// # Arguments
-        ///
-        /// * `path` - The file path from where the view will be created.
-        pub fn view_from_buffer(self: &Index, buffer: &[u8]) -> Result<()>;
+    /// Reserves memory for a specified number of incoming vectors.
+    ///
+    /// # Arguments
+    ///
+    /// * `capacity` - The desired total capacity including the current size.
+    pub fn reserve(self: &Index, capacity: usize) -> Result<(), cxx::Exception> {
+        self.inner.reserve(capacity)
+    }
 
+    /// Retrieves the number of dimensions in the vectors indexed.
+    pub fn dimensions(self: &Index) -> usize {
+        self.inner.dimensions()
+    }
+
+    /// Retrieves the connectivity parameter that limits connections-per-node in the graph.
+    pub fn connectivity(self: &Index) -> usize {
+        self.inner.connectivity()
+    }
+
+    /// Retrieves the current number of vectors in the index.
+    pub fn size(self: &Index) -> usize {
+        self.inner.size()
+    }
+
+    /// Retrieves the total capacity of the index, including reserved space.
+    pub fn capacity(self: &Index) -> usize {
+        self.inner.capacity()
+    }
+
+    /// Reports expected file size after serialization.
+    pub fn serialized_length(self: &Index) -> usize {
+        self.inner.serialized_length()
+    }
+
+    /// Removes the vector associated with the given key from the index.
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - The key of the vector to be removed.
+    ///
+    /// # Returns
+    ///
+    /// `true` if the vector is successfully removed, `false` otherwise.
+    pub fn remove(self: &Index, key: u64) -> Result<usize, cxx::Exception> {
+        self.inner.remove(key)
+    }
+
+    /// Renames the vector under a certain key.
+    ///
+    /// # Arguments
+    ///
+    /// * `from` - The key of the vector to be renamed.
+    /// * `to` - The new name.
+    ///
+    /// # Returns
+    ///
+    /// `true` if the vector is successfully renamed, `false` otherwise.
+    pub fn rename(self: &Index, from: u64, to: u64) -> Result<usize, cxx::Exception> {
+        self.inner.rename(from, to)
+    }
+
+    /// Checks if the index contains a vector with a specified key.
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - The key to be checked.
+    ///
+    /// # Returns
+    ///
+    /// `true` if the index contains the vector with the given key, `false` otherwise.
+    pub fn contains(self: &Index, key: u64) -> bool {
+        self.inner.contains(key)
+    }
+
+    /// Count the count of vector with the same specified key.
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - The key to be checked.
+    ///
+    /// # Returns
+    ///
+    /// Number of vectors found.
+    pub fn count(self: &Index, key: u64) -> usize {
+        self.inner.count(key)
+    }
+
+    /// Saves the index to a specified file.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The file path where the index will be saved.
+    pub fn save(self: &Index, path: &str) -> Result<(), cxx::Exception> {
+        self.inner.save(path)
+    }
+
+    /// Loads the index from a specified file.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The file path from where the index will be loaded.
+    pub fn load(self: &Index, path: &str) -> Result<(), cxx::Exception> {
+        self.inner.load(path)
+    }
+
+    /// Creates a view of the index from a file without loading it into memory.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The file path from where the view will be created.
+    pub fn view(self: &Index, path: &str) -> Result<(), cxx::Exception> {
+        self.inner.view(path)
+    }
+
+    /// Saves the index to a specified file.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The file path where the index will be saved.
+    pub fn save_to_buffer(self: &Index, buffer: &mut [u8]) -> Result<(), cxx::Exception> {
+        self.inner.save_to_buffer(buffer)
+    }
+
+    /// Loads the index from a specified file.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The file path from where the index will be loaded.
+    pub fn load_from_buffer(self: &Index, buffer: &[u8]) -> Result<(), cxx::Exception> {
+        self.inner.load_from_buffer(buffer)
+    }
+
+    /// Creates a view of the index from a file without loading it into memory.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The file path from where the view will be created.
+    pub fn view_from_buffer(self: &Index, buffer: &[u8]) -> Result<(), cxx::Exception> {
+        self.inner.view_from_buffer(buffer)
     }
 }
 
+pub fn new_index(options: &ffi::IndexOptions) -> Result<Index, cxx::Exception> {
+    Index::new(options)
+}
+
 #[cfg(test)]
 mod tests {
-    use crate::ffi::new_index;
     use crate::ffi::IndexOptions;
     use crate::ffi::MetricKind;
-    use crate::ffi::ScalarKind;
+
+    use crate::new_index;
+    use crate::Index;
 
     #[test]
     fn integration() {
-        let mut options = IndexOptions {
-            dimensions: 5,
-            metric: MetricKind::IP,
-            quantization: ScalarKind::F16,
-            connectivity: 0,
-            expansion_add: 0,
-            expansion_search: 0,
-        };
+        let mut options = IndexOptions::default();
+        options.dimensions = 5;
 
-        let index = new_index(&options).unwrap();
+        let index = Index::new(&options).unwrap();
 
         assert!(index.reserve(10).is_ok());
         assert!(index.capacity() >= 10);

package/wasmer.toml

@@ -1,6 +1,6 @@
 [package]
 name="unum/usearch"
-version="2.4.0"
+version="2.5.0"
 description="Smaller & Faster Single-File Vector Search Engine from Unum"
 license="Apache-2.0"
 readme="README.md"