API Reference#

usearch/usearch.h#

Defines

USEARCH_EXPORT#

Typedefs

USEARCH_EXPORT enum usearch_metric_kind_t usearch_metric_kind_t: Enumerator for the most common kinds of usearch_metric_t. Those are supported out of the box, with SIMD-optimizations for most common hardware.

USEARCH_EXPORT enum usearch_scalar_kind_t usearch_scalar_kind_t

USEARCH_EXPORT struct usearch_init_options_t usearch_init_options_t

Enums

enum usearch_metric_kind_t#

Enumerator for the most common kinds of usearch_metric_t. Those are supported out of the box, with SIMD-optimizations for most common hardware.

Values:

enumerator usearch_metric_unknown_k#

enumerator usearch_metric_cos_k#

enumerator usearch_metric_ip_k#

enumerator usearch_metric_l2sq_k#

enumerator usearch_metric_haversine_k#

enumerator usearch_metric_divergence_k#

enumerator usearch_metric_pearson_k#

enumerator usearch_metric_jaccard_k#

enumerator usearch_metric_hamming_k#

enumerator usearch_metric_tanimoto_k#

enumerator usearch_metric_sorensen_k#

enum usearch_scalar_kind_t#

Values:

enumerator usearch_scalar_unknown_k#

enumerator usearch_scalar_f32_k#

enumerator usearch_scalar_f64_k#

enumerator usearch_scalar_f16_k#

enumerator usearch_scalar_i8_k#

enumerator usearch_scalar_b1_k#

Functions

USEARCH_EXPORT char const * usearch_version (void)

Retrieves the version of the library.

Returns:: The version of the library.

USEARCH_EXPORT usearch_index_t usearch_init (usearch_init_options_t *options, usearch_error_t *error)

Initializes a new instance of the index.

Parameters:

options – Pointer to the usearch_init_options_t structure containing initialization options.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

A handle to the initialized USearch index, or NULL on failure.

USEARCH_EXPORT void usearch_free (usearch_index_t index, usearch_error_t *error)

Frees the resources associated with the index.

Parameters:

index – [inout] The handle to the USearch index to be freed.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

USEARCH_EXPORT size_t usearch_memory_usage (usearch_index_t index, usearch_error_t *error)

Reports the memory usage of the index.

Parameters:

index – [in] The handle to the USearch index to be queried.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

Number of bytes used by the index.

USEARCH_EXPORT char const * usearch_hardware_acceleration (usearch_index_t index, usearch_error_t *error)

Reports the SIMD capabilities used by the index on the current CPU.

Parameters:

index – [in] The handle to the USearch index to be queried.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

The codename of the SIMD instruction set used by the index.

USEARCH_EXPORT size_t usearch_serialized_length (usearch_index_t index, usearch_error_t *error)

Reports expected file size after serialization.

Parameters:

index – [in] The handle to the USearch index to be serialized.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

USEARCH_EXPORT void usearch_save (usearch_index_t index, char const *path, usearch_error_t *error)

Saves the index to a file.

Parameters:

index – [in] The handle to the USearch index to be serialized.
path – [in] The file path where the index will be saved.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

USEARCH_EXPORT void usearch_load (usearch_index_t index, char const *path, usearch_error_t *error)

Loads the index from a file.

Parameters:

index – [inout] The handle to the USearch index to be populated from path.
path – [in] The file path from where the index will be loaded.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

USEARCH_EXPORT void usearch_view (usearch_index_t index, char const *path, usearch_error_t *error)

Creates a view of the index from a file without copying it into memory.

Parameters:

index – [inout] The handle to the USearch index to be populated with a file view.
path – [in] The file path from where the view will be created.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

USEARCH_EXPORT void usearch_metadata (char const *path, usearch_init_options_t *options, usearch_error_t *error)

Loads index metadata from a file.

Parameters:

path – [in] The file path from where the index will be loaded.
options – [out] Pointer to the usearch_init_options_t structure to be populated.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

A handle to the initialized USearch index, or NULL on failure.

USEARCH_EXPORT void usearch_save_buffer (usearch_index_t index, void *buffer, size_t length, usearch_error_t *error)

Saves the index to an in-memory buffer.

Parameters:

index – [in] The handle to the USearch index to be serialized.
buffer – [in] The in-memory continuous buffer where the index will be saved.
length – [in] The length of the buffer in bytes.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

USEARCH_EXPORT void usearch_load_buffer (usearch_index_t index, void const *buffer, size_t length, usearch_error_t *error)

Loads the index from an in-memory buffer.

Parameters:

index – [inout] The handle to the USearch index to be populated from buffer.
buffer – [in] The in-memory continuous buffer from where the index will be loaded.
length – [in] The length of the buffer in bytes.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

USEARCH_EXPORT void usearch_view_buffer (usearch_index_t index, void const *buffer, size_t length, usearch_error_t *error)

Creates a view of the index from an in-memory buffer without copying it into memory.

Parameters:

index – [inout] The handle to the USearch index to be populated with a buffer view.
buffer – [in] The in-memory continuous buffer from where the view will be created.
length – [in] The length of the buffer in bytes.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

USEARCH_EXPORT void usearch_metadata_buffer (void const *buffer, size_t length, usearch_init_options_t *options, usearch_error_t *error)

Loads index metadata from an in-memory buffer.

Parameters:

buffer – [in] The in-memory continuous buffer from where the view will be created.
options – [out] Pointer to the usearch_init_options_t structure to be populated.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

A handle to the initialized USearch index, or NULL on failure.

USEARCH_EXPORT size_t usearch_size (usearch_index_t index, usearch_error_t *error)

Reports the current size (number of vectors) of the index.

Parameters:

index – [in] The handle to the USearch index to be queried.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

USEARCH_EXPORT size_t usearch_capacity (usearch_index_t index, usearch_error_t *error)

Reports the current capacity (number of vectors) of the index.

Parameters:

index – [in] The handle to the USearch index to be queried.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

USEARCH_EXPORT size_t usearch_dimensions (usearch_index_t index, usearch_error_t *error)

Reports the current dimensions of the vectors in the index.

Parameters:

index – [in] The handle to the USearch index to be queried.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

USEARCH_EXPORT size_t usearch_connectivity (usearch_index_t index, usearch_error_t *error)

Reports the current connectivity of the index.

Parameters:

index – [in] The handle to the USearch index to be queried.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

USEARCH_EXPORT void usearch_reserve (usearch_index_t index, size_t capacity, usearch_error_t *error)

Reserves memory for a specified number of incoming vectors.

Parameters:

index – [inout] The handle to the USearch index to be resized.
capacity – [in] The desired total capacity including current size.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

USEARCH_EXPORT size_t usearch_expansion_add (usearch_index_t index, usearch_error_t *error)

Retrieves the expansion value used during index creation.

Parameters:

index – [in] The handle to the USearch index to be queried.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

The expansion value used during index creation.

USEARCH_EXPORT size_t usearch_expansion_search (usearch_index_t index, usearch_error_t *error)

Retrieves the expansion value used during search.

Parameters:

index – [in] The handle to the USearch index to be queried.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

The expansion value used during search.

USEARCH_EXPORT void usearch_change_expansion_add (usearch_index_t index, size_t expansion, usearch_error_t *error)

Updates the expansion value used during index creation. Rarely used.

Parameters:

index – [in] The handle to the USearch index to be queried.
expansion – [in] The new expansion value.
error – [out] 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)

Updates the expansion value used during search. Rarely used.

Parameters:

index – [in] The handle to the USearch index to be queried.
expansion – [in] The new expansion value.
error – [out] 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)

Updates the metric kind used for distance calculation between vectors.

Parameters:

index – [in] The handle to the USearch index to be queried.
kind – [in] The metric kind used for distance calculation between vectors.
error – [out] 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)

Updates the custom metric function used for distance calculation between vectors.

Parameters:

index – [in] The handle to the USearch index to be queried.
metric – [in] The custom metric function used for distance calculation between vectors.
state – [in] The optional state pointer to be passed to the custom metric function.
kind – [in] The metric kind used for distance calculation between vectors. Needed for serialization.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

USEARCH_EXPORT void usearch_add (usearch_index_t index, usearch_key_t key, void const *vector, usearch_scalar_kind_t vector_kind, usearch_error_t *error)

Adds a vector with a key to the index.

Parameters:

index – [inout] The handle to the USearch index to be populated.
key – [in] The key associated with the vector.
vector – [in] Pointer to the vector data.
vector_kind – [in] The scalar type used in the vector data.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

USEARCH_EXPORT bool usearch_contains (usearch_index_t index, usearch_key_t key, usearch_error_t *error)

Checks if the index contains a vector with a specific key.

Parameters:

index – [in] The handle to the USearch index to be queried.
key – [in] The key to be checked.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

true if the index contains the vector with the given key, false otherwise.

USEARCH_EXPORT size_t usearch_count (usearch_index_t index, usearch_key_t, usearch_error_t *error)

Counts the number of entries in the index under a specific key.

Parameters:

index – [in] The handle to the USearch index to be queried.
key – [in] The key to be checked.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

Number of vectors found under that key.

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)

Performs k-Approximate Nearest Neighbors (kANN) Search for closest vectors to query.

Parameters:

index – [in] The handle to the USearch index to be queried.
query_vector – [in] Pointer to the query vector data.
query_kind – [in] The scalar type used in the query vector data.
count – [in] Upper bound on the number of neighbors to search, the “k” in “kANN”.
keys – [out] Output buffer for up to count nearest neighbors keys.
distances – [out] Output buffer for up to count distances to nearest neighbors.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

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)

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.

Parameters:

index – [in] The handle to the USearch index to be queried.
query_vector – [in] Pointer to the query vector data.
query_kind – [in] The scalar type used in the query vector data.
count – [in] Upper bound on the number of neighbors to search, the “k” in “kANN”.
filter – [in] The custom filter function that returns true for vectors to be included.
filter_state – [in] The optional state pointer to be passed to the custom filter function.
keys – [out] Output buffer for up to count nearest neighbors keys.
distances – [out] Output buffer for up to count distances to nearest neighbors.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

Number of found matches.

USEARCH_EXPORT size_t usearch_get (usearch_index_t index, usearch_key_t key, size_t count, void *vector, usearch_scalar_kind_t vector_kind, usearch_error_t *error)

Retrieves the vector associated with the given key from the index.

Parameters:

index – [in] The handle to the USearch index to be queried.
key – [in] The key of the vector to retrieve.
vector – [out] Pointer to the memory where the vector data will be copied.
count – [in] Number of vectors that can be fitted into vector for multi-vector entries.
vector_kind – [in] The scalar type used in the vector data.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

Number of vectors found under that name and exported to vector.

USEARCH_EXPORT size_t usearch_remove (usearch_index_t index, usearch_key_t key, usearch_error_t *error)

Removes the vector associated with the given key from the index.

Parameters:

index – [inout] The handle to the USearch index to be modified.
key – [in] The key of the vector to be removed.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

Number of vectors found under that name and dropped from the index.

USEARCH_EXPORT size_t usearch_rename (usearch_index_t index, usearch_key_t from, usearch_key_t to, usearch_error_t *error)

Renames the vector to map to a different key.

Parameters:

index – [inout] The handle to the USearch index to be modified.
from – [in] The key of the vector to be renamed.
to – [in] New key for found entry.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

Number of vectors found under that name and renamed.

USEARCH_EXPORT usearch_distance_t usearch_distance (void const *vector_first, void const *vector_second, usearch_scalar_kind_t scalar_kind, size_t dimensions, usearch_metric_kind_t metric_kind, usearch_error_t *error)

Computes the distance between two equi-dimensional vectors.

Parameters:

vector_first – [in] The first vector for comparison.
vector_second – [in] The second vector for comparison.
scalar_kind – [in] The scalar type used in the vectors.
dimensions – [in] The number of dimensions in each vector.
metric_kind – [in] The metric kind used for distance calculation between vectors.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

Distance between given vectors.

USEARCH_EXPORT void usearch_exact_search (void const *dataset, size_t dataset_size, size_t dataset_stride, void const *queries, size_t queries_size, size_t queries_stride, usearch_scalar_kind_t scalar_kind, size_t dimensions, usearch_metric_kind_t metric_kind, size_t count, size_t threads, usearch_key_t *keys, size_t keys_stride, usearch_distance_t *distances, size_t distances_stride, usearch_error_t *error)

Multi-threaded exact nearest neighbors search for equi-dimensional vectors.

Parameters:

dataset – [in] Pointer to the first scalar of the dataset matrix.
queries – [in] Pointer to the first scalar of the queries matrix.
dataset_size – [in] Number of vectors in the dataset.
queries_size – [in] Number of vectors in the queries set.
dataset_stride – [in] Number of bytes between starts of consecutive vectors in dataset.
queries_stride – [in] Number of bytes between starts of consecutive vectors in queries.
scalar_kind – [in] The scalar type used in the vectors.
dimensions – [in] The number of dimensions in each vector.
metric_kind – [in] The metric kind used for distance calculation between vectors.
count – [in] Upper bound on the number of neighbors to search, the “k” in “kANN”.
threads – [in] Upper bound for the number of CPU threads to use.
keys – [out] Output buffer for up to count nearest neighbors keys.
distances – [out] Output buffer for up to count distances to nearest neighbors.
error – [out] Pointer to a string where the error message will be stored, if an error occurs.

Returns:

Number of found matches.

Variables

USEARCH_EXPORT typedef void * usearch_index_t

USEARCH_EXPORT typedef uint64_t usearch_key_t

USEARCH_EXPORT typedef float usearch_distance_t

USEARCH_EXPORT typedef char const * usearch_error_t: Pointer to a null-terminated error message. Returned error messages don’t need to be deallocated.

USEARCH_EXPORT typedef usearch_distance_t(* usearch_metric_t )(void const *, void const *): Type-punned callback for “metrics” or “distance functions”, that accepts pointers to two vectors and measures their dis-similarity.

struct usearch_init_options_t#

#include <usearch.h>

Public Members

usearch_metric_kind_t metric_kind#: The metric kind used for distance calculation between vectors.

usearch_metric_t metric#: The optional custom distance metric function used for distance calculation between vectors. If the metric_kind is set to usearch_metric_unknown_k, this function pointer mustn’t be NULL.

usearch_scalar_kind_t quantization#: The scalar kind used for quantization of vector data during indexing.

size_t dimensions#: The number of dimensions in the vectors to be indexed. Must be defined for most metrics, but can be avoided for usearch_metric_haversine_k.

size_t connectivity#: The optional connectivity parameter that limits connections-per-node in graph.

size_t expansion_add#: The optional expansion factor used for index construction when adding vectors.

size_t expansion_search#: The optional expansion factor used for index construction during search operations.

bool multi#: When set allows multiple vectors to map to the same key.