VectorIndex.hh

Go to the documentation of this file.

//
// VectorIndex.hh
//
// Copyright (c) 2024 Couchbase, Inc All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
 
 
#ifdef COUCHBASE_ENTERPRISE
 
#pragma once
#include "cbl++/Base.hh"
#include "cbl++/Collection.hh"
#include "cbl/CBLQueryIndexTypes.h"
 
CBL_ASSUME_NONNULL_BEGIN
 
namespace cbl {
    using DistanceMetric = CBLDistanceMetric;

    class VectorEncoding {
    public:
        static VectorEncoding none() {
            return VectorEncoding(CBLVectorEncoding_CreateNone());
        }
        
        static VectorEncoding scalarQuantizer(CBLScalarQuantizerType type) {
            return VectorEncoding(CBLVectorEncoding_CreateScalarQuantizer(type));
        }
        
        static VectorEncoding productQuantizer(unsigned int subquantizers, unsigned int bits) {
            return VectorEncoding(CBLVectorEncoding_CreateProductQuantizer(subquantizers, bits));
        }
        
        VectorEncoding() = delete;
        
    protected:
        friend class VectorIndexConfiguration;
        
        CBLVectorEncoding* ref() const {return _ref.get();}
    
    private:
        VectorEncoding(CBLVectorEncoding* ref) {
            _ref = std::shared_ptr<CBLVectorEncoding>(ref, [](auto r) {
                CBLVectorEncoding_Free(r);
            });
        }
        
        std::shared_ptr<CBLVectorEncoding> _ref;
    };

    class VectorIndexConfiguration {
    public:
        VectorIndexConfiguration(CBLQueryLanguage expressionLanguage, std::string_view expression,
                                 unsigned dimensions, unsigned centroids)
        :_exprLang(expressionLanguage)
        ,_expr(slice(expression))
        ,_dimensions(dimensions)
        ,_centroids(centroids)
        { }
        
        //-- Accessors:
        
        QueryLanguage expressionLanguage() const         {return _exprLang;}
        
        slice expression() const                         {return _expr;}
        
        unsigned dimensions() const                      {return _dimensions;}
        
        unsigned centroids() const                       {return _centroids;}
        
        bool isLazy = false;
        
        VectorEncoding encoding = VectorEncoding::scalarQuantizer(kCBLSQ8);
        
        DistanceMetric metric = kCBLDistanceMetricEuclideanSquared;
        
        unsigned minTrainingSize = 0;
        
        unsigned maxTrainingSize = 0;
        
        unsigned numProbes = 0;
 
    protected:
        friend Collection;
 
    private:
        template <typename F>
        decltype(auto) withCConfig(F&& f) const {
            CBLVectorIndexConfiguration cConfig {
                _exprLang, slice(_expr), _dimensions, _centroids
            };
            cConfig.isLazy   = isLazy;
            cConfig.encoding = encoding.ref();
            cConfig.metric   = metric;
            cConfig.minTrainingSize = minTrainingSize;
            cConfig.maxTrainingSize = maxTrainingSize;
            cConfig.numProbes = numProbes;
            return std::forward<F>(f)(cConfig);
        }
 
        QueryLanguage _exprLang;
        std::string   _expr;
        unsigned      _dimensions;
        unsigned      _centroids;
    };
 
    void Collection::createVectorIndex(std::string_view name, VectorIndexConfiguration config) {
        config.withCConfig([this, name](const CBLVectorIndexConfiguration& cConfig) {
            CBLError error;
            internal::check(
                CBLCollection_CreateVectorIndex(ref(), slice(name), cConfig, &error),
                error);
        });
    }
}
 
CBL_ASSUME_NONNULL_END
 
#endif