search_with_masks

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

Queries the feature vectors for AscendIndexSQ and returns IDs of the most similar k features based on the input feature vectors. 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 float *x: feature vector data.

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

const void *mask: database masks.

float *distances: distance between a vector 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 with a length of n × ceil(ntotal/8). (ntotal indicates the number of features in the database.) Otherwise, an out-of-bounds read/write error may occur, causing program breakdown.
• 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.