ComputeDistanceByIdx

APP_ERROR ComputeDistanceByIdx(int n, const float16_t *queries, const int *num, const idx_t *indices, float *distances, unsigned int tableLen = 0, const float *table = nullptr)

This API is similar to ComputeDistance. The difference is that ComputeDistance calculates the distance between the vector to be queried and all base library vectors, while ComputeDistanceByIdx calculates only the distance between the vector to be queried and the base library vector with a specified subscript index. If a valid mapping table (tableLen > 0 and *table is a non-null pointer) is transferred, the top k results after mapping are returned.

int n: number of feature vectors to be queried.

const float16_t *queries: feature vectors to be queried. The valid length is n x dim. dim must be the same as that specified during initialization.

const int *num: number of feature vectors in the base library to be compared for each query. The length is n.

const idx_t *indices: subscript index of the base library feature vector to be compared. The number of base library vectors to be compared for each query can be different. Consecutive valid subscripts should be provided, and the occupied space should be padded based on the maximum num. The length of indices is n x max(num).

unsigned int tableLen: length of the mapping table. The default value is 0, indicating that no mapping is performed. Currently, the mapping table length can be set to 10000.

const float *table: pointer of the mapping table, pointing to the storage space of valid mapping values with the tableLen length. Currently, the supported redundancy length is 48, that is, the length of the space to which *table points is 10048 x sizeof(float) bytes.

float *distances: distance between the query vector and the selected base library vector. Each query continuously records the valid distance in sequence and supplements the used space based on the maximum num. The space length is n x max(num).

APP_ERROR: return status. For details, see Return Code Reference.

• n: The value range is [0, capacity].
• num: specified by the user. The length is n. The value of num of each query must range from 0 to ntotal.
• indices: The range of each feature index is [0, ntotal).
• Parameter configuration examples: n = 3, num[3] = {1, 5, 3} indicates the number of base libraries to be compared by three queries. max(num) = 5 indicates that the space length pointed to by *indices is aligned by 5 and total size is 3 x 5 x sizeof(idx_t) bytes, for example, { {1, 0, 0, 0, 0}, {4, 7, 9, 0, 0}, {1, 3, 4, 7, 9} }.
• If both TableLen and *table meet the requirements during the parameter pass, the API maps the calculated distance.

  First, the distance value is normalized to a floating point number f1 in the range of [0, 1], and then f1 is multiplied by tableLen and rounded up to obtain an integer index between [0, tableLen]. Then, the integer index is used as an offset to obtain the corresponding score from the memory space pointed to by *table. The mapping is completed, and score is saved to *distance .

  The index mapping formula is as follows: ((CosDistance + 1)/2) x tableLen