Auxiliary Types

This page gathers the remaining public types: the attribute system used for hybrid (attribute-filtered) search, the IndexFeature capability flags, the index detail info introspection types, the utility functions in utils.h, and the string constants in constants.h.

Attributes

Declared in vsag/attribute.h. Attributes are typed, named metadata attached to each vector, enabling SQL-style filtering during search (see Attribute Filter (Hybrid Search)).

AttrValueType

enum AttrValueType {
    INT32 = 1, UINT32 = 2, INT64 = 3, UINT64 = 4,
    INT8 = 5, UINT8 = 6, INT16 = 7, UINT16 = 8,
    STRING = 9,
};

The element type carried by an attribute.

Attribute

class Attribute {
public:
    std::string name_{};

    virtual AttrValueType GetValueType() const = 0;
    virtual uint64_t GetValueCount() const = 0;
    virtual Attribute* DeepCopy() const = 0;
    virtual bool Equal(const Attribute* other) const = 0;
};
using AttributePtr = std::shared_ptr<Attribute>;

An abstract, named attribute. Each attribute may hold multiple values (GetValueCount()), so a single field can represent a multi-valued tag set.

AttributeValue<T>

template <class T>
class AttributeValue : public Attribute {
public:
    AttrValueType GetValueType() const override;
    uint64_t GetValueCount() const override;
    std::vector<T>& GetValue();
    const std::vector<T>& GetValue() const;
    Attribute* DeepCopy() const override;
    bool Equal(const Attribute* other) const override;
};

The concrete, typed implementation of Attribute. Instantiate it with the C++ type matching the desired AttrValueType (e.g. AttributeValue<int32_t>, AttributeValue<std::string>), set name_, and push values into GetValue().

auto tag = std::make_shared<vsag::AttributeValue<int32_t>>();
tag->name_ = "category";
tag->GetValue().push_back(7);

AttributeSet

struct AttributeSet {
    std::vector<Attribute*> attrs_;
};

A bag of attributes describing one element. Attach a per-element array of AttributeSet to a Dataset via AttributeSets(...), or pass one to Index::UpdateAttribute.

IndexFeature

Declared in vsag/index_features.h. An enum of optional capabilities you can probe with Index::CheckFeature before calling an optional method.

enum IndexFeature {
    NEED_TRAIN = 1,
    SUPPORT_BUILD,
    SUPPORT_ADD_AFTER_BUILD,
    SUPPORT_KNN_SEARCH,
    SUPPORT_RANGE_SEARCH,
    SUPPORT_DELETE_BY_ID,
    SUPPORT_SERIALIZE_BINARY_SET,
    SUPPORT_CAL_DISTANCE_BY_ID,
    SUPPORT_MERGE_INDEX,
    SUPPORT_CLONE,
    /* ... many more ... */
    INDEX_FEATURE_COUNT   // sentinel; always the last value
};

The enum groups capabilities into families:

INDEX_FEATURE_COUNT marks the end of the enum and is not a real feature. See examples/cpp/307_feature_check_features.cpp.

Index detail info

Declared in vsag/index_detail_info.h. These types describe and carry the structured data returned by Index::GetIndexDetailInfos and Index::GetDetailDataByName. See Index Introspection and examples/cpp/317_feature_get_detail_data.cpp.

IndexDetailDataType

enum class IndexDetailDataType {
    TYPE_2DArray_INT64,
    TYPE_1DArray_INT64,
    TYPE_SCALAR_INT64,
    TYPE_SCALAR_DOUBLE,
    TYPE_SCALAR_STRING,
    TYPE_SCALAR_BOOL,
};

Tells you which DetailData getter is valid for a given field.

IndexDetailInfo

class IndexDetailInfo {
public:
    std::string name;
    std::string description;
    IndexDetailDataType type;
};

A descriptor for one introspectable field: its name, a human-readable description, and the payload type.

DetailData

class DetailData {
public:
    virtual std::vector<int64_t> GetData1DArrayInt64();
    virtual std::vector<std::vector<int64_t>> GetData2DArrayInt64();
    virtual std::string GetDataScalarString();
    virtual bool GetDataScalarBool();
    virtual int64_t GetDataScalarInt64();
    virtual double GetDataScalarDouble();
    // ... const overloads ...
};
using DetailDataPtr = std::shared_ptr<DetailData>;

The payload itself. Read it through the getter matching the descriptor’s IndexDetailDataType; calling a mismatched getter is not meaningful.

Utility functions

Declared in vsag/utils.h. Free helper functions for clustering and recall evaluation.

kmeans_clustering

float kmeans_clustering(uint64_t d, uint64_t n, uint64_t k, const float* x,
                        float* centroids, const std::string& dis_type);

Runs k-means over n points of dimension d, writing k centroids into the pre-allocated centroids (size k * d). dis_type is one of "l2", "cosine", "ip". Returns the final quantization error.

l2_and_filtering

BitsetPtr l2_and_filtering(int64_t dim, int64_t nb, const float* base,
                           const float* query, float threshold);

Returns a Bitset in which bit i is set (true) when base vector i falls within threshold L2 distance of query — the ground truth consumed by range_search_recall. Note the polarity is the opposite of a search pre-filter, where a set bit excludes an id (see Bitset); invert it before reusing it as an invalid / bitset_filter_ mask.

knn_search_recall / range_search_recall

float knn_search_recall(const float* base, const int64_t* id_map, int64_t base_num,
                        const float* query, int64_t data_dim,
                        const int64_t* result_ids, int64_t result_size);

float range_search_recall(const float* base, const int64_t* base_ids, int64_t num_base,
                          const float* query, int64_t dim,
                          const int64_t* result_ids, int64_t result_size, float threshold);

Compute the recall of a KNN or range search result against the ground truth derived from the base vectors. Handy for tests and benchmarks; see Benchmarks.

Constants

Declared in vsag/constants.h. A large set of extern const char* const string constants for the keys and enumerated string values used throughout the JSON-based configuration. Using the constants instead of raw string literals avoids typos. They fall into several groups:

For the meaning of each parameter key, see Index Parameters and the individual index pages.

See also

• Index — CheckFeature, GetIndexDetailInfos, UpdateAttribute.
• Dataset — attaching AttributeSet data to elements.
• Search Request & Filters — attribute-filter expressions and Bitset.