Search indexes

The search indexes of a pipeline, which hold the fragments in the form that each kind of search reads, and the distance indexes of vector indexes. Search indexes describes the index kinds, the default indexes and the life cycle of an index, and Add, rebuild or switch a search index shows each operation.

📄️List search indexes

Returns every search index of a pipeline as a JSON array, ordered by identifier, without the list envelope. Each index shows its kind, its status, the progress of its backfill, whether the index is a default of the pipeline and, for a vector index, the distance indexes. A search names an index by the identifier in `id`.

📄️Add a search index

Adds a search index to a pipeline: a vector index on VectorChord (`vchord`) or pgvector (`pgvector`) for an embedding model, the full-text index (`fts`) or a BM25 index (`bm25`) with a tokenizer. A pipeline holds one full-text index, one BM25 index for each distinct tokenizer and one vector index for each embedding model and extension.

📄️Get a search index

Returns one search index of a pipeline: the kind, the status, the progress of the backfill, whether the index is a default of the pipeline, the progress of a running rebuild and, for a vector index, the distance indexes. A client application reads an added index until `status` is `ready`.

📄️Delete a search index

Deletes a search index of a pipeline with the index's table and, for a BM25 index, the stored tokenizer. The deletion is permanent, and a search that names the deleted index returns HTTP 400. A default index cannot be deleted: another index of the same kind becomes the default first. A failed index can be deleted.

📄️Set the default search index

Makes a `ready` search index the default index of its kind: a vector index becomes the default vector index, and a full-text or BM25 index becomes the default text index. Searches and agent placeholders that name no index use the new default from the next request. The previous default stays in the pipeline and can then be deleted. The request has no body.

📄️List distance indexes

Returns the distance indexes of a vector index as a JSON array: one database index for each distance strategy that searches of the vector index can use, with the size of the index and whether the build is complete. A new vector index has a distance index for `cosine`. A search with a distance strategy that has no distance index returns HTTP 400, and a vector index without any distance index cannot be searched.

📄️Add a distance index

Adds a distance index for `cosine`, `euclidean-distance` or `dot-product` to a vector index, so that searches can use that distance strategy. The database builds the index in the background with a concurrent build, so searches and document processing continue. The response returns as soon as the build starts: the new entry of the distance index list shows `valid` set to `false` until the build completes, and the `rebuild` field of the search index reports the progress. The `max-inner-product` strategy cannot be indexed.

📄️Remove a distance index

Removes the distance index of one distance strategy from a vector index. The removal is concurrent, so searches and document processing continue. From the next request, a search with that distance strategy returns HTTP 400. A vector index without any distance index cannot be searched, so the last distance index of a vector index that searches use is replaced before it is removed.

📄️Rebuild a search index

Rebuilds the database indexes of a search index in the background, one after the other, with a concurrent reindex. Searches and document processing continue on the existing copy of each database index during the rebuild. A rebuild reclaims the space that the entries of deleted and replaced fragments occupy, and improves a vector index that was first built on few fragments. The request has no body.

📄️Retry a failed backfill

Restarts the backfill of a `failed` search index from the first fragment, after the cause of the failure is fixed, such as an embedding model that could not be reached. The index becomes `building`, and `message` is cleared. The request has no body.