Query

Retrieves the nearest neighbors for given query vectors.

QueryResults Query(Array2D<float>& query_vectors,
                   const QueryParams& query_params,
                   const KeyContext& key);

Parameters

Parameter	Type	Description
query_vectors	Array2D<float>	Query vectors to search.
query_params	QueryParams	Parameters for querying, such as top_k, n_probes, and rerank_mult (default 50). Pass cyborg::QueryParams{} for defaults.
key	KeyContext	Key context for the operation. A bare 32-byte index key (the index_key) implicitly converts to a KeyContext. For an RBAC user, pass cyborg::KeyContext{user_kek, user_id} (read permission required).

Both query_params and key are required. There are no longer default values for these arguments.

If this function is called on an index where TrainIndex() has not been executed (or while a retrain is in progress), the query will use encrypted exhaustive search. This may cause queries to be slower, especially when there are many vector embeddings in the index.

Returns

QueryResults: Results top_k containing decrypted nearest neighbors IDs and distances.

Exceptions

std::invalid_argument

• Throws if the query vectors have incompatible dimensions with the index.
• Throws if the index was not created or loaded yet.

std::runtime_error

• Throws if the query could not be executed.
• Throws if the supplied key context lacks read permission.

Example Usage

cyborg::Array2D<float> queries{/*...*/}; // Populate with one or more query vectors

// Query with default parameters
QueryResults results = index->Query(queries, cyborg::QueryParams{}, index_key);

// Query with explicit parameters: top_k = 10, n_probes = 5
cyborg::QueryParams params(10, 5);
QueryResults results2 = index->Query(queries, params, index_key);

auto view = results[0]; // Access first query's results
for (uint32_t j = 0; j < view.num_results; ++j) {
    std::cout << "ID: " << view.ids[j] << ", Distance: " << view.distances[j] << std::endl;
}

index_key is the 32-byte std::array<uint8_t, 32> index KEK and converts implicitly to a KeyContext. In a stateless service that reloads the index per request, pass the key on every operation.