Database Indexes

Data Structures
struct	C4VectorClustering
	Clustering options for vector indexes. More...
struct	C4VectorEncoding
	Encoding options for vector indexes. More...
struct	C4VectorIndexOptions
	Top-level options for vector indexes. More...
struct	C4IndexOptions
	Options for indexes; these each apply to specific types of indexes. More...

Enumerations
enum	C4IndexType : uint32_t {   kC4ValueIndex , kC4FullTextIndex , kC4ArrayIndex , kC4PredictiveIndex ,   kC4VectorIndex }
enum	C4VectorMetricType : uint32_t { kC4VectorMetricDefault , kC4VectorMetricEuclidean , kC4VectorMetricCosine }
enum	C4VectorClusteringType : uint32_t { kC4VectorClusteringFlat , kC4VectorClusteringMulti }
enum	C4VectorEncodingType : uint32_t { kC4VectorEncodingDefault , kC4VectorEncodingNone , kC4VectorEncodingPQ , kC4VectorEncodingSQ }

Functions
NODISCARD CBL_CORE_API bool	c4db_createIndex (C4Database *database, C4String name, C4String indexSpecJSON, C4IndexType indexType, const C4IndexOptions *indexOptions, C4Error *outError)
	Creates a database index, of the values of specific expressions across all documents.
NODISCARD CBL_CORE_API bool	c4db_createIndex2 (C4Database *database, C4String name, C4String indexSpec, C4QueryLanguage queryLanguage, C4IndexType indexType, const C4IndexOptions *indexOptions, C4Error *outError)
NODISCARD CBL_CORE_API bool	c4db_deleteIndex (C4Database *database, C4String name, C4Error *outError)
	Deletes an index that was created by c4db_createIndex.
CBL_CORE_API C4SliceResult	c4db_getIndexesInfo (C4Database *database, C4Error *outError)
	Returns information about all indexes in the database.

Detailed Description

Enumeration Type Documentation

C4IndexType

enum C4IndexType : uint32_t

Enumerator
kC4ValueIndex	Regular index of property value.
kC4FullTextIndex	Full-text index.
kC4ArrayIndex	Index of array values, for use with UNNEST.
kC4PredictiveIndex	Index of prediction() results (Enterprise Edition only)
kC4VectorIndex	Index of ML vector similarity (Enterprise Edition only)

C4VectorClusteringType

enum C4VectorClusteringType : uint32_t

Enumerator
kC4VectorClusteringFlat	Flat k-means clustering.
kC4VectorClusteringMulti	Inverted Multi-Index clustering.

C4VectorEncodingType

enum C4VectorEncodingType : uint32_t

Enumerator
kC4VectorEncodingDefault	Use default encoding, which is currently SQ8.
kC4VectorEncodingNone	No encoding: 32 bits per dimension, no data loss.
kC4VectorEncodingPQ	Product Quantizer.
kC4VectorEncodingSQ	Scalar Quantizer.

C4VectorMetricType

enum C4VectorMetricType : uint32_t

Enumerator
kC4VectorMetricDefault	Use default metric, Euclidean.
kC4VectorMetricEuclidean	Euclidean distance (squared)
kC4VectorMetricCosine	Cosine distance (1.0 - cosine similarity)

Function Documentation

c4db_createIndex()

NODISCARD CBL_CORE_API bool c4db_createIndex	(	C4Database *	database,
		C4String	name,
		C4String	indexSpecJSON,
		C4IndexType	indexType,
		const C4IndexOptions *	indexOptions,
		C4Error *	outError
	)

Creates a database index, of the values of specific expressions across all documents.

The name is used to identify the index for later updating or deletion; if an index with the same name already exists, it will be replaced unless it has the exact same expressions.

Currently four types of indexes are supported:

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 operator in a query. A FTS index is required for full-text search: a query with a MATCH operator will fail to compile unless there is already a FTS index for the property/expression being matched. Only a single expression is currently allowed, and it must evaluate to a string. Array indexes optimize UNNEST queries, by materializing an unnested array property (across all documents) as a table in the SQLite database, and creating a SQL index on it. Predictive indexes optimize queries that use the PREDICTION() function, by materializing the function's results as a table and creating a SQL index on a result property.

Note: If some documents are missing the values to be indexed, those documents will just be omitted from the index. It's not an error.

In an array index, the first expression must evaluate to an array to be unnested; it's usually a property path but could be some other expression type. If the array items are nonscalar (dictionaries or arrays), you should add a second expression defining the sub- property (or computed value) to index, relative to the array item.

In a predictive index, the expression is a PREDICTION() call in JSON query syntax, including the optional 3rd parameter that gives the result property to extract (and index.)

indexSpecJSON specifies the index as a JSON object, with properties: WHAT: An array of expressions in the JSON query syntax. (Note that each expression is already an array, so there are two levels of nesting.) WHERE: An optional expression. Including this creates a partial index: documents for which this expression returns false or null will be skipped.

For backwards compatibility, indexSpecJSON may be an array; this is treated as if it were a dictionary with a WHAT key mapping to that array.

Expressions are defined in JSON, as in a query, and wrapped in a JSON array. For example, [[".name.first"]] will index on the first-name property. Note the two levels of brackets, since an expression is already an array.

Parameters

database	The database to index.
name	The name of the index. Any existing index with the same name will be replaced, unless it has the identical expressions (in which case this is a no-op.)
indexSpecJSON	The definition of the index in JSON form. (See above.)
indexType	The type of index (value or full-text.)
indexOptions	Options for the index. If NULL, each option will get a default value.
outError	On failure, will be set to the error status.

Returns

True on success, false on failure.

c4db_createIndex2()

NODISCARD CBL_CORE_API bool c4db_createIndex2	(	C4Database *	database,
		C4String	name,
		C4String	indexSpec,
		C4QueryLanguage	queryLanguage,
		C4IndexType	indexType,
		const C4IndexOptions *	indexOptions,
		C4Error *	outError
	)

Parameters

database	The database to index.
name	The name of the index. Any existing index with the same name will be replaced, unless it has the identical expressions (in which case this is a no-op.)
indexSpec	The definition of the index in JSON or N1QL form. (See above.)
queryLanguage	The query language (JSON or N1QL) of indexSpec is expressed.
indexType	The type of index (value or full-text.)
indexOptions	Options for the index. If NULL, each option will get a default value.
outError	On failure, will be set to the error status.

Returns

True on success, false on failure.

c4db_deleteIndex()

NODISCARD CBL_CORE_API bool c4db_deleteIndex	(	C4Database *	database,
		C4String	name,
		C4Error *	outError
	)

Deletes an index that was created by c4db_createIndex.

Parameters

database	The database to index.
name	The name of the index to delete
outError	On failure, will be set to the error status.

Returns

True on success, false on failure.

c4db_getIndexesInfo()

CBL_CORE_API C4SliceResult c4db_getIndexesInfo	(	C4Database *	database,
		C4Error *	outError
	)

Returns information about all indexes in the database.

The result is a Fleece-encoded array of dictionaries, one per index. Each dictionary has keys "name", "type" (a C4IndexType), and "expr" (the source expression).

Parameters

database	The database to check
outError	On failure, will be set to the error status.

Returns

A Fleece-encoded array of dictionaries, or NULL on failure.