search_with_masks

void search_with_masks(idx_t n, const int8_t *x, idx_t k, float *distances, idx_t *labels, const void *mask) const;

Queries feature vectors of AscendIndexInt8, and returns the distance and IDs of the most similar k features based on the input feature vectors and mask. The mask is a bit string consisting of 0 and 1. Each bit indicates whether the feature of the corresponding sequence in the database is involved in distance calculation. 1 indicates that it is involved, and 0 indicates that it is not involved.

idx_t n: number of query vectors.

const int8_t *x: feature vector data.

idx_t k: number of the most similar results to be returned.

const void* mask: filter mask.

float *distances: distance between query vectors and the first k nearest vectors.

idx_t *labels: IDs of the first k nearest vectors that are queried.

N/A

• Range of n: 0 < n < 1e9.
• The value of k cannot be greater than 4096.
• x must be a non-null pointer with a length of dims × n. Otherwise, an out-of-bounds read/write error may occur, causing program breakdown.
• distances and labels must be non-null pointers with a length of k × n. Otherwise, an out-of-bounds read/write error may occur, causing program breakdown.
• mask must be a non-null pointer. Ensure that the length of the input mask is (ntotal/8)× n (ntotal indicates the number of vectors).
• mask is set based on the feature sequence in the database. If remove_ids is called to delete feature vectors before this API is called, the feature sequence will change. In this case, call the getIdxMap API to obtain feature IDs and then set mask.
• To use this API, ensure that the database must be stored in a single device. Otherwise, the filtering result may be incorrect.