Index

Indexes are used to speed up queries by allowing fast – O(log n) – lookup of documents that have specific values or ranges of values. More...

Data Structures
struct	CBLValueIndexConfiguration
	Value Index Configuration. More...
struct	CBLFullTextIndexConfiguration
	Full-Text Index Configuration. More...
struct	CBLArrayIndexConfiguration
	Array Index Configuration for indexing property values within arrays in documents, intended for use with the UNNEST query. More...
struct	CBLVectorIndexConfiguration
	ENTERPRISE EDITION ONLY. More...

Typedefs
typedef struct CBLQueryIndex	CBLQueryIndex
	A query index. More...
typedef struct CBLIndexUpdater	CBLIndexUpdater

Index Configuration
enum	CBLScalarQuantizerType : uint32_t { kCBLSQ4 = 4 , kCBLSQ6 = 6 , kCBLSQ8 = 8 }
	Scalar Quantizer encoding type. More...
enum	CBLDistanceMetric : uint32_t { kCBLDistanceMetricEuclideanSquared = 1 , kCBLDistanceMetricCosine , kCBLDistanceMetricEuclidean , kCBLDistanceMetricDot }
	Distance metric to use in CBLVectorIndexConfiguration. More...
typedef struct CBLVectorEncoding	CBLVectorEncoding
	An opaque object representing vector encoding type to use in CBLVectorIndexConfiguration. More...
_cbl_warn_unused CBLVectorEncoding *	CBLVectorEncoding_CreateNone (void)
	Creates a no-encoding type to use in CBLVectorIndexConfiguration; 4 bytes per dimension, no data loss. More...
_cbl_warn_unused CBLVectorEncoding *	CBLVectorEncoding_CreateScalarQuantizer (CBLScalarQuantizerType type)
	Creates a Scalar Quantizer encoding to use in CBLVectorIndexConfiguration. More...
_cbl_warn_unused CBLVectorEncoding *	CBLVectorEncoding_CreateProductQuantizer (unsigned subquantizers, unsigned bits)
	Creates a Product Quantizer encoding to use in CBLVectorIndexConfiguration. More...
void	CBLVectorEncoding_Free (CBLVectorEncoding *_cbl_nullable)
	Frees a CBLVectorEncoding object. More...

CBLQueryIndex
CBLQueryIndex represents an existing index in a collection. Available in the enterprise edition, the CBLQueryIndex can be used to obtain a CBLIndexUpdater object for updating the vector index in lazy mode.
static const CBLQueryIndex *	CBLQueryIndex_Retain (const CBLQueryIndex *t)
static void	CBLQueryIndex_Release (const CBLQueryIndex *t)
FLString	CBLQueryIndex_Name (const CBLQueryIndex *index)
	Returns the index's name. More...
CBLCollection *	CBLQueryIndex_Collection (const CBLQueryIndex *index)
	Returns the collection that the index belongs to. More...
static const CBLIndexUpdater *	CBLIndexUpdater_Retain (const CBLIndexUpdater *t)
static void	CBLIndexUpdater_Release (const CBLIndexUpdater *t)
_cbl_warn_unused CBLIndexUpdater *_cbl_nullable	CBLQueryIndex_BeginUpdate (CBLQueryIndex *index, size_t limit, CBLError *_cbl_nullable outError)
	ENTERPRISE EDITION ONLY. More...

IndexUpdater
CBLIndexUpdater used for updating the index in lazy mode. Currently, the vector index is the only index type that can be updated lazily.
size_t	CBLIndexUpdater_Count (const CBLIndexUpdater *updater)
	ENTERPRISE EDITION ONLY. More...
FLValue	CBLIndexUpdater_Value (CBLIndexUpdater *updater, size_t index)
	ENTERPRISE EDITION ONLY. More...
bool	CBLIndexUpdater_SetVector (CBLIndexUpdater *updater, size_t index, const float vector[_cbl_nullable], size_t dimension, CBLError *_cbl_nullable outError)
	ENTERPRISE EDITION ONLY. More...
void	CBLIndexUpdater_SkipVector (CBLIndexUpdater *updater, size_t index)
	ENTERPRISE EDITION ONLY. More...
bool	CBLIndexUpdater_Finish (CBLIndexUpdater *updater, CBLError *_cbl_nullable outError)
	ENTERPRISE EDITION ONLY. More...

Detailed Description

Indexes are used to speed up queries by allowing fast – O(log n) – lookup of documents that have specific values or ranges of values.

The values may be properties, or expressions based on properties.

An index will speed up queries that use the expression it indexes, but it takes up space in the database file, and it slows down document saves slightly because it needs to be kept up to date when documents change.

Tuning a database with indexes can be a tricky task. Fortunately, a lot has been written about it in the relational-database (SQL) realm, and much of that advice holds for Couchbase Lite. You may find SQLite's documentation particularly helpful since Couchbase Lite's querying is based on SQLite.

Supported index types: Value indexes speed up queries by making it possible to look up property (or expression) values without scanning every document. They're just like regular indexes in SQL or N1QL. Multiple expressions are supported; the first is the primary key, second is secondary. Expressions must evaluate to scalar types (boolean, number, string).

Full-Text Search (FTS) indexes enable fast search of natural-language words or phrases by using the MATCH() function in a query. A FTS index is required for full-text search: a query with a MATCH() function will fail to compile unless there is already a FTS index for the property/expression being matched.

(Enterprise Edition Only) Vector indexes allows efficient search of ML vectors by using the VECTOR_MATCH() function in a query. The CouchbaseLiteVectorSearch extension library is required to use the functionality. Use CBL_EnableVectorSearch function to set the directoary path containing the extension library.

Typedef Documentation

CBLIndexUpdater

typedef struct CBLIndexUpdater CBLIndexUpdater

CBLQueryIndex

typedef struct CBLQueryIndex CBLQueryIndex

A query index.

CBLVectorEncoding

typedef struct CBLVectorEncoding CBLVectorEncoding

An opaque object representing vector encoding type to use in CBLVectorIndexConfiguration.

Enumeration Type Documentation

CBLDistanceMetric

enum CBLDistanceMetric : uint32_t

Distance metric to use in CBLVectorIndexConfiguration.

Enumerator
kCBLDistanceMetricEuclideanSquared	Squared Euclidean distance (AKA Squared L2)
kCBLDistanceMetricCosine	Cosine distance (1.0 - Cosine Similarity)
kCBLDistanceMetricEuclidean	Euclidean distance (AKA L2)
kCBLDistanceMetricDot	Dot-product distance (Negative of dot-product)

CBLScalarQuantizerType

enum CBLScalarQuantizerType : uint32_t

Scalar Quantizer encoding type.

Enumerator
kCBLSQ4	4 bits per dimension
kCBLSQ6	6 bits per dimension
kCBLSQ8	8 bits per dimension

Function Documentation

CBLIndexUpdater_Count()

size_t CBLIndexUpdater_Count

(

const CBLIndexUpdater *

updater

)

ENTERPRISE EDITION ONLY.

Returns the total number of vectors to compute and set for updating the index.

Parameters

updater

The index updater.

Returns

The total number of vectors to compute and set for updating the index.

CBLIndexUpdater_Finish()

bool CBLIndexUpdater_Finish	(	CBLIndexUpdater *	updater,
		CBLError *_cbl_nullable	outError
	)

ENTERPRISE EDITION ONLY.

Updates the index with the computed vectors and removes any index rows for which null vector was given. If there are any indexes that do not have their vector value set or are skipped, a error will be returned.

Note

Before calling CBLIndexUpdater_Finish, the set vectors are kept in the memory.

Warning

The index updater cannot be used after calling CBLIndexUpdater_Finish.

Parameters

updater	The index updater.
outError	On failure, an error is written here.

Returns

True if success, or False if an error occurred.

CBLIndexUpdater_Release()

static void CBLIndexUpdater_Release ( const CBLIndexUpdater *  t )

inlinestatic

CBLIndexUpdater_Retain()

static const CBLIndexUpdater * CBLIndexUpdater_Retain ( const CBLIndexUpdater *  t )

inlinestatic

CBLIndexUpdater_SetVector()

bool CBLIndexUpdater_SetVector	(	CBLIndexUpdater *	updater,
		size_t	index,
		const float	vector[_cbl_nullable],
		size_t	dimension,
		CBLError *_cbl_nullable	outError
	)

ENTERPRISE EDITION ONLY.

Sets the vector for the value corresponding to the given index. Setting null vector means that there is no vector for the value, and any existing vector will be removed when the CBLIndexUpdater_Finish is called.

Parameters

updater	The index updater.
index	The zero-based index.
vector	A pointer to the vector which is an array of floats, or NULL if there is no vector.
dimension	The dimension of vector. Must be equal to the dimension value set in the vector index config.
outError	On failure, an error is written here.

Returns

True if success, or False if an error occurred.

CBLIndexUpdater_SkipVector()

void CBLIndexUpdater_SkipVector	(	CBLIndexUpdater *	updater,
		size_t	index
	)

ENTERPRISE EDITION ONLY.

Skip setting the vector for the value corresponding to the index. The vector will be required to compute and set again when the CBLQueryIndex_BeginUpdate is later called.

Parameters

updater	The index updater.
index	The zero-based index.

CBLIndexUpdater_Value()

FLValue CBLIndexUpdater_Value	(	CBLIndexUpdater *	updater,
		size_t	index
	)

ENTERPRISE EDITION ONLY.

Returns the valut at the given index to compute a vector from.

Note

The returned Fleece value is valid unilt its CBLIndexUpdater is released. If you want to keep it longer, retain it with FLRetain.

Parameters

updater	The index updater.
index	The zero-based index.

Returns

A Fleece value of the index's evaluated expression at the given index.

CBLQueryIndex_BeginUpdate()

_cbl_warn_unused CBLIndexUpdater *_cbl_nullable CBLQueryIndex_BeginUpdate	(	CBLQueryIndex *	index,
		size_t	limit,
		CBLError *_cbl_nullable	outError
	)

ENTERPRISE EDITION ONLY.

Finds new or updated documents for which vectors need to be (re)computed and returns an CBLIndexUpdater object for setting the computed vectors to update the index. If the index is not lazy, an error will be returned.

Note

For updating lazy vector indexes only.

You are responsible for releasing the returned A CBLIndexUpdater object.

Parameters

index	The index.
limit	The maximum number of vectors to be computed.
outError	On failure, an error is written here.

Returns

A CBLIndexUpdater object for setting the computed vectors to update the index, or NULL if the index is up-to-date or an error occurred.

CBLQueryIndex_Collection()

CBLCollection * CBLQueryIndex_Collection

(

const CBLQueryIndex *

index

)

Returns the collection that the index belongs to.

Parameters

index

The index.

Returns

A CBLCollection instance that the index belongs to.

CBLQueryIndex_Name()

FLString CBLQueryIndex_Name

(

const CBLQueryIndex *

index

)

Returns the index's name.

Parameters

index

The index.

Returns

The name of the index.

CBLQueryIndex_Release()

static void CBLQueryIndex_Release ( const CBLQueryIndex *  t )

inlinestatic

CBLQueryIndex_Retain()

static const CBLQueryIndex * CBLQueryIndex_Retain ( const CBLQueryIndex *  t )

inlinestatic

CBLVectorEncoding_CreateNone()

_cbl_warn_unused CBLVectorEncoding * CBLVectorEncoding_CreateNone

(

void

)

Creates a no-encoding type to use in CBLVectorIndexConfiguration; 4 bytes per dimension, no data loss.

Returns

A None encoding object.

CBLVectorEncoding_CreateProductQuantizer()

_cbl_warn_unused CBLVectorEncoding * CBLVectorEncoding_CreateProductQuantizer	(	unsigned	subquantizers,
		unsigned	bits
	)

Creates a Product Quantizer encoding to use in CBLVectorIndexConfiguration.

Parameters

subquantizers	Number of subquantizers. Must be > 1 and a factor of vector dimensions.
bits	Number of bits. Must be >= 4 and <= 12.

Returns

A Product Quantizer encoding object.

CBLVectorEncoding_CreateScalarQuantizer()

_cbl_warn_unused CBLVectorEncoding * CBLVectorEncoding_CreateScalarQuantizer

(

CBLScalarQuantizerType

type

)

Creates a Scalar Quantizer encoding to use in CBLVectorIndexConfiguration.

Parameters

type	Scalar Quantizer Type.

Returns

A Scalar Quantizer encoding object.

CBLVectorEncoding_Free()

void CBLVectorEncoding_Free

(

CBLVectorEncoding *

_cbl_nullable

)

Frees a CBLVectorEncoding object.

The encoding object can be freed after the index is created.