usearch/javascript/dist/esm/usearch.d.ts

Smaller & Faster Single-File Vector Search Engine from Unum

type Vector = Float32Array | Float64Array | Int8Array;
type Matrix = Vector[];
type VectorOrMatrix = Vector | Matrix;
/**
 * Enumeration representing the various metric kinds used to measure the distance between vectors in the index.
 * @enum {string}
 * @readonly
 */
export declare enum MetricKind {
    Unknown = "unknown",
    Cos = "cos",
    IP = "ip",
    L2sq = "l2sq",
    Haversine = "haversine",
    Divergence = "divergence",
    Pearson = "pearson",
    Jaccard = "jaccard",
    Hamming = "hamming",
    Tanimoto = "tanimoto",
    Sorensen = "sorensen"
}
/**
 * Enumeration representing the various scalar kinds used to define the type of scalar values in vectors.
 * @enum {string}
 * @readonly
 */
export declare enum ScalarKind {
    Unknown = "unknown",
    F32 = "f32",
    F64 = "f64",
    F16 = "f16",
    BF16 = "bf16",
    I8 = "i8",
    B1 = "b1"
}
/**
 * Represents a set of search results.
 */
export declare class Matches {
    keys: BigUint64Array;
    distances: Float32Array;
    /**
     * Constructs a Matches object.
     *
     * @param {BigUint64Array} keys - The keys of the nearest neighbors found.
     * @param {Float32Array} distances - The distances of the nearest neighbors found.
     */
    constructor(keys: BigUint64Array, distances: Float32Array);
}
/**
 * Represents a set of batched search results.
 */
export declare class BatchMatches {
    keys: BigUint64Array;
    distances: Float32Array;
    counts: BigUint64Array;
    k: number;
    /**
     * Constructs a BatchMatches object.
     *
     * @param {BigUint64Array} keys - The keys of the nearest neighbors found in the batch.
     * @param {Float32Array} distances - The distances of the nearest neighbors found in the batch.
     * @param {BigUint64Array} counts - The number of neighbors found for each query in the batch.
     * @param {number} k - The limit for search results per query in the batch.
     */
    constructor(keys: BigUint64Array, distances: Float32Array, counts: BigUint64Array, k: number);
    /**
     * Retrieves a Matches object at the specified index in the batch.
     *
     * @param {number} i - The index at which to retrieve the Matches object.
     * @returns {Matches} - A Matches object representing the search results at the specified index in the batch.
     */
    get(i: number): Matches;
}
export interface IndexConfig {
    dimensions: number;
    metric: MetricKind;
    quantization: ScalarKind;
    connectivity: number;
    expansion_add: number;
    expansion_search: number;
    multi: boolean;
}
export declare class Index {
    #private;
    /**
     * Constructs a new index.
     *
     * @param {(number | {dimensions: number, metric: MetricKind = MetricKind.Cos, quantization: ScalarKind = ScalarKind.F32, connectivity: number = 0, expansion_add: number = 0, expansion_search: number = 0, multi: boolean = false})} dimensionsOrConfigs
     * @param {MetricKind} [metric=MetricKind.Cos] - Optional, default is 'cos'.
     * @param {ScalarKind} [quantization=ScalarKind.F32] - Optional, default is 'f32'.
     * @param {number} [connectivity=0] - Optional, default is 0.
     * @param {number} [expansion_add=0] - Optional, default is 0.
     * @param {number} [expansion_search=0] - Optional, default is 0.
     * @param {boolean} [multi=false] - Optional, default is false.
     * @throws Will throw an error if any of the parameters are of incorrect type or invalid value.
     */
    constructor(dimensionsOrConfigs: number | bigint | IndexConfig, metric?: MetricKind, quantization?: ScalarKind, connectivity?: number, expansion_add?: number, expansion_search?: number, multi?: boolean);
    /**
     * Add vectors to the index.
     *
     * This method accepts vectors and their corresponding keys for indexing.
     * Each key should correspond to a vector. If a single key is provided,
     * it is broadcasted to match the number of provided vectors.
     *
     * Vectors should be provided as a flat typed array representing a matrix
     * where each row is a vector to be indexed. The matrix should have a size
     * of n * d, where n is the number of vectors, and d is the dimensionality
     * of the vectors.
     *
     * Keys should be provided as a BigInt or an array-like object of BigInts
     * representing the unique identifier for each vector.
     *
     * @param {bigint|bigint[]|BigUint64Array} keys - Input identifiers for every vector.
     *        If a single key is provided, it is associated with all provided vectors.
     * @param {Float32Array|Float64Array|Int8Array} vectors - Input matrix representing vectors,
     *        matrix of size n * d, where n is the number of vectors, and d is their dimensionality.
     * @throws Will throw an error if the length of keys doesn't match the number of vectors
     *         or if it's not a single key.
     */
    add(keys: bigint | bigint[] | BigUint64Array, vectors: Vector): void;
    /**
     * Perform a k-nearest neighbor search on the index.
     *
     * This method accepts a matrix of query vectors and returns the closest vectors
     * from the index for each query. The method returns an object containing the keys,
     * distances, and counts of the matches found.
     *
     * Vectors should be provided as a flat typed array representing a matrix where
     * each row is a vector. The matrix should be of size n * d, where n is the
     * number of query vectors, and d is their dimensionality.
     *
     * The parameter `k` specifies the number of nearest neighbors to return for each
     * query vector. If there are not enough results for a query, the result array is
     * padded with -1s.
     *
     * @param {Float32Array|Float64Array|Int8Array|Array<Array<number>>} vectors - Input matrix representing query vectors, can be a TypedArray or an array of TypedArray.
     * @param {number} k - The number of nearest neighbors to search for each query vector.
     * @return {Matches|BatchMatches} - Search results for one or more queries, containing keys, distances, and counts of the matches found.
     * @throws Will throw an error if `k` is not a positive integer or if the size of the vectors is not a multiple of dimensions.
     * @throws Will throw an error if `vectors` is not a valid input type (TypedArray or an array of TypedArray) or if its flattened size is not a multiple of dimensions.
     */
    search(vectors: VectorOrMatrix, k: number): Matches | BatchMatches;
    /**
     * Verifies the presence of one or more keys in the index.
     *
     * This method accepts one or multiple keys as input and returns a boolean or
     * an array of booleans indicating whether each key is present in the index.
     *
     * @param {bigint|bigint[]|BigUint64Array} keys - The identifier(s) of the vector(s) to be checked for presence in the index.
     * @return {boolean|boolean[]} - Returns true if a single key is contained in the index, false otherwise. Returns an array of booleans corresponding to the presence of each key in the index when multiple keys are provided.
     * @throws Will throw an error if keys are not integers.
     */
    contains(keys: bigint | bigint[] | BigUint64Array): boolean | boolean[];
    /**
     * Counts the number of times keys shows up in the index.
     *
     * @param {bigint|bigint[]|BigUint64Array} keys - The identifier(s) of the vector(s) to be enumerated.
     * @return {number|number[]} - Returns the number of vectors found when a single key is provided. Returns an array of big integers corresponding to the number of vectors found for each key when multiple keys are provided.
     * @throws Will throw an error if keys are not integers.
     */
    count(keys: bigint | bigint[] | BigUint64Array): number | number[];
    /**
     * Removes one or multiple vectors from the index.
     *
     * This method accepts one or multiple keys as input and removes the corresponding vectors from the index.
     * It returns the number of vectors actually removed for each key provided.
     *
     * @param {bigint|bigint[]|BigUint64Array} keys - The identifier(s) of the vector(s) to be removed.
     * @return {number|number[]} - Returns the number of vectors deleted when a single key is provided. Returns an array of big integers corresponding to the number of vectors deleted for each key when multiple keys are provided.
     * @throws Will throw an error if keys are not integers.
     */
    remove(keys: bigint | bigint[] | BigUint64Array): number | number[];
    /**
     * Returns the dimensionality of vectors.
     * @return {number} The dimensionality of vectors.
     */
    dimensions(): number;
    /**
     * Returns connectivity.
     * @return {number} The connectivity of index.
     */
    connectivity(): number;
    /**
     * Returns the number of vectors currently indexed.
     * @return {number} The number of vectors currently indexed.
     */
    size(): number;
    /**
     * Returns index capacity.
     * @return {number} The capacity of index.
     */
    capacity(): number;
    /**
     * Write index to a file.
     * @param {string} path File path to write.
     * @throws Will throw an error if `path` is not a string.
     */
    save(path: string): void;
    /**
     * Load index from a file.
     * @param {string} path File path to read.
     * @throws Will throw an error if `path` is not a string.
     */
    load(path: string): void;
    /**
     * View index from a file, without loading into RAM.
     * @param {string} path File path to read.
     * @throws Will throw an error if `path` is not a string.
     */
    view(path: string): void;
}
/**
 * Performs an exact search on the given dataset to find the best matching vectors for each query.
 *
 * @param {Float32Array|Float64Array|Int8Array|Array<Array<number>>} dataset - The dataset containing vectors to be searched. It can be a TypedArray or an array of arrays.
 * @param {Float32Array|Float64Array|Int8Array|Array<Array<number>>} queries - The queries containing vectors to search for in the dataset. It can be a TypedArray or an array of arrays.
 * @param {number} dimensions - The dimensionality of the vectors in both the dataset and the queries. It defines the number of elements in each vector.
 * @param {number} count - The number of nearest neighbors to return for each query. If the dataset contains fewer vectors than the specified count, the result will contain only the available vectors.
 * @param {MetricKind} metric - The distance metric to be used for the search.
 * @return {Matches|BatchMatches} - Returns a `Matches` or `BatchMatches` object containing the results of the search.
 * @throws Will throw an error if `dimensions` and `count` are not positive integers.
 * @throws Will throw an error if `metric` is not a valid MetricKind.
 * @throws Will throw an error if `dataset` and `queries` are not valid input types (TypedArray or an array of arrays).
 * @throws Will throw an error if the sizes of the flattened `dataset` and `queries` are not multiples of `dimensions`.
 * @throws Will throw an error if `count` is greater than the number of vectors in the `dataset`.
 *
 * @example
 * const dataset = [[1.0, 2.0], [3.0, 4.0]]; // Two vectors: [1.0, 2.0] and [3.0, 4.0]
 * const queries = [[1.5, 2.5]]; // One vector: [1.5, 2.5]
 * const dimensions = 2; // The number of elements in each vector.
 * const count = 1; // The number of nearest neighbors to return for each query.
 * const metric = MetricKind.IP; // Using the Inner Product distance metric.
 *
 * const result = exactSearch(dataset, queries, dimensions, count, metric);
 * // result might be:
 * // {
 * //    keys: BigUint64Array [ 1n ],
 * //    distances: Float32Array [ some_value ],
 * // }
 */
declare function exactSearch(dataset: VectorOrMatrix, queries: VectorOrMatrix, dimensions: number, count: number, metric: MetricKind): Matches | BatchMatches;
declare const usearch: {
    Index: typeof Index;
    MetricKind: typeof MetricKind;
    ScalarKind: typeof ScalarKind;
    Matches: typeof Matches;
    BatchMatches: typeof BatchMatches;
    exactSearch: typeof exactSearch;
};
export default usearch;