Query Result

Data structure that contains the result of processing a batch of queries.

template<typename Idx>
using svs::QueryResult = QueryResultImpl<Idx, Matrix>

Default type alias for general RAII style query results.

template<typename Idx>
using svs::QueryResultView = QueryResultImpl<Idx, MatrixView>

Default type alias for query results viewing a span of memory.

template<typename Idx, template<typename> typename Array = Matrix>
class QueryResultImpl

Struct containing result indices and distances for a query batch.

A struct holding the results of a Query, containing the indices of the nearest neighbors and the distances.

The second type parameter is expected to be one of two arguments:

(1) Matrix - in this case QueryResultImpl owns its data. Alias: QueryResult<Idx>. (2) MatrixView - in the case QueryResultImpl does not own its data. Alias: QueryResultView<Idx>

Public Functions

inline QueryResultImpl(size_t n_queries, size_t n_neighbors)

Construct an uninitialized QueryResult of the given size.

Creates an uninitialized QueryResult with the capacity to hold the indices and distances for n_neighbors nearest neighbors for n_queries queries.

Parameters:

  • n_queries – The number of queries to use.

  • n_neighbors – The number of neighbors to return for each query.

inline QueryResultImpl(Array<Idx> indices, Array<float> distances)

Construct a QueryResultImpl from indices and distance directly.

Preconditions:

  • indices.ndims() == 2 (compiler time failure if not).

  • distances.ndims() == 2 (compiler time failure if not).

  • indices.dims() == distances.dims().

The constructed QueryResultImpl will have the following properties.

  • n_queries() == getsize<0>(indices) == getsize<0>(distances).

  • n_neighbors() == getsize<1>(indices) == getsize<1>(distances).

Note: This constructor provides a way using externally-supplied pointers for the contents of the QueryResultImpl by using array views.

Parameters:

  • indices – The indices array to use.

  • distances – The distances array to use.

inline size_t n_queries() const

Return the number of queries this instance has neighbors for.

inline size_t n_neighbors() const

Return the number of neighbors this instance can hold for each query.

inline const Array<Idx> &indices() const

Return the indices container directly.

inline Array<Idx> &indices()

Return the indices container directly.

inline const Array<float> &distances() const

Return the distances container directly.

inline Array<float> &distances()

Return the distances container directly.

inline const Idx &index(size_t query, size_t neighbor) const

Return the ID for the requested position.

Parameters:

  • query – The query index to lookup. Must be in [0, n_queries()).

  • neighbor – The neighbor number to return. Must be in [0, n_neighbors()).

inline Idx &index(size_t query, size_t neighbor)

Return the ID for the requested position.

Parameters:

  • query – The query index to lookup. Must be in [0, n_queries()).

  • neighbor – The neighbor number to return. Must be in [0, n_neighbors()).

inline const float &distance(size_t query, size_t neighbor) const

Return the ID for the requested position.

Parameters:

  • query – The query index to lookup. Must be in [0, n_queries()).

  • neighbor – The neighbor number to return. Must be in [0, n_neighbors()).

inline float &distance(size_t query, size_t neighbor)

Return the ID for the requested position.

Parameters:

  • query – The query index to lookup. Must be in [0, n_queries()).

  • neighbor – The neighbor number to return. Must be in [0, n_neighbors()).

inline QueryResultImpl<Idx, MatrixView> view()

Return a non-owning view the underlying data structures.

Often, especially when dealing with type-erased interfaces, it is useful to have a single concrete type as a parameter. The view mechanisms performs that for the QueryResult, taking any particular specialization (i.e., different allocators) and creating a non-owning view of the underlying arrays.

inline void save_vecs(const std::string &filename)

Save the indices in ivecs form.

Parameters:

filename – The file path where the nearest neighbors will be saved.