> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Train

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

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

<Tip>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.</Tip>

### 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. |

<Warning>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.</Warning>

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](#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.

<Warning>`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()`](../getters#istrained) after `train()` returns: an untrained index has `getNLists()` of `1`. Queries on an untrained index still work.</Warning>

### Returns

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

### Exceptions

<AccordionGroup>
  <Accordion title="CyborgDBAuthenticationError">
    The client isn't using the root key, or the `indexKey` is invalid (HTTP `401`/`403`). Training requires the root key.
  </Accordion>

  <Accordion title="CyborgDBNotFoundError">
    The index doesn't exist (HTTP `404`).
  </Accordion>

  <Accordion title="CyborgDBServiceError">
    The service returns `5xx`. A failed training run doesn't throw; see [Requirements](#requirements).
  </Accordion>
</AccordionGroup>

See [Errors](../errors) for the full hierarchy.

### Example Usage

#### Default settings

```typescript theme={null}
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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.