Train

Clusters the index’s vectors into IVF lists so queries only scan the closest lists. train() waits until training finishes before returning.

async train({
    nLists?: number,
    batchSize?: number,
    maxIters?: number,
    tolerance?: number,
    maxMemory?: number,
} = {}): Promise<TrainResponse>

The service also trains indexes automatically. An untrained index is trained once it holds more than AUTO_TRAIN_MIN_VECTORS vectors (default 65536), and a trained index is retrained when its size calls for more lists than it has. Set AUTO_TRAIN_DISABLED=true on the service to turn this off. Call train() yourself to train a smaller index, or to make sure training is finished before running queries or benchmarks.

Parameters

Parameter	Type	Default	Description
`nLists`	`number`	`undefined` (auto)	(Optional) Number of IVF lists. When omitted, the square root of the vector count, rounded to a power of two.
`batchSize`	`number`	`undefined` (ignored)	(Optional) Vectors processed per training batch.
`maxIters`	`number`	`undefined` (ignored)	(Optional) Maximum clustering iterations.
`tolerance`	`number`	`undefined` (ignored)	(Optional) Convergence tolerance.
`maxMemory`	`number`	`undefined` (ignored)	(Optional) Memory cap for training, in MB.

Only nLists affects training today. The service accepts batchSize, maxIters, tolerance, and maxMemory but doesn’t pass them to training, so they have no effect.

Parameter values aren’t range-checked. An out-of-range value such as nLists: 0 is accepted and training is skipped as described in Requirements; a negative nLists makes train() resolve with status: 'error'.

Requirements

Training only runs when all three hold:

The index has at least 10,000 vectors.
It has at least twice as many vectors as nLists.
The vector dimension is a multiple of 32, such as 384, 768, or 1536.

train() doesn’t report a skipped or failed training run. If a requirement isn’t met, train() still resolves with { status: 'success', message: "Index '...' trained successfully" }. If training fails on the service, it resolves with status: 'error' instead of throwing. Either way, the index stays untrained. Check isTrained() after train() returns: an untrained index has getNLists() of 1. Queries on an untrained index still work.

Returns

Promise<TrainResponse> with status and message. If the index is already training, train() waits for that run to finish, then trains again.

Exceptions

CyborgDBAuthenticationError

The client isn’t using the root key, or the indexKey is invalid (HTTP 401/403). Training requires the root key.

CyborgDBNotFoundError

The index doesn’t exist (HTTP 404).

CyborgDBServiceError

The service returns 5xx. A failed training run doesn’t throw; see Requirements.

See Errors for the full hierarchy.

Example Usage

Default settings

await index.train();

// train() doesn't throw if training is skipped, so check the result
console.log(await index.isTrained(), await index.getNLists());
// Output: true 128

Custom settings

await index.train({
    nLists: 128,
    batchSize: 4096,
    maxIters: 200,
    tolerance: 1e-7,
});

Introduction

Client

Encrypted Index

Types & Helpers

Parameters

Requirements

Returns

Exceptions

Example Usage

Default settings

Custom settings

​Parameters

​Requirements

​Returns

​Exceptions

​Example Usage

​Default settings

​Custom settings

Parameters

Requirements

Returns

Exceptions

Example Usage

Default settings

Custom settings