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

Builds the index using the specified training configuration. Required before efficient querying.
Prior to calling this, all queries will be conducted using encrypted exhaustive search.
After, they will be conducted using encrypted ANN search.

```python theme={null}
def train(self,
          n_lists: int = None,
          batch_size: int = None,
          max_iters: int = None,
          tolerance: float = None,
          max_memory: int = None,
          *,
          index_key: bytes = None,
          user_id: bytes = None)
```

### Parameters

| Parameter    | Type    | Default | Description                                                                                                                                                       |
| ------------ | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `n_lists`    | `int`   | `None`  | *(Optional)* Number of inverted index lists to create in the index. When `None`, auto-determines based on the number of vectors in the index (equivalent to `0`). |
| `batch_size` | `int`   | `None`  | *(Optional)* Size of each batch for training. When `None`, defaults to `0` (auto — the optimal batch size is selected automatically).                             |
| `max_iters`  | `int`   | `None`  | *(Optional)* Maximum number of iterations for training. When `None`, defaults to `100`.                                                                           |
| `tolerance`  | `float` | `None`  | *(Optional)* Convergence tolerance for training. When `None`, defaults to `1e-6`.                                                                                 |
| `max_memory` | `int`   | `None`  | *(Optional)* Maximum memory to use for training. When `None`, defaults to `0` (no limit).                                                                         |
| `index_key`  | `bytes` | `None`  | *(Optional, keyword-only)* Override the per-operation index key. See [Per-operation key override](#per-operation-key-override).                                   |
| `user_id`    | `bytes` | `None`  | *(Optional, keyword-only)* 16-byte RBAC user identifier. See [Per-operation key override](#per-operation-key-override).                                           |

<Tip>There must be at least `2 * n_lists` or `10,000` (whichever is greater) vector embeddings in the index prior to calling this function.</Tip>

### Exceptions

<AccordionGroup>
  <Accordion title="ValueError">
    * Raises an exception if the index was not created or loaded yet.
  </Accordion>

  <Accordion title="RuntimeError">
    * Raises an exception if there are not enough vector embeddings in the index for training (must be at least `2 * n_lists`).
    * Raises an exception if the index could not be trained.
  </Accordion>
</AccordionGroup>

### Example Usage

```python theme={null}
# Load index
index = client.load_index(
    index_name=index_name, 
    index_key=index_key
)

# Train the index with custom settings
index.train(
    batch_size=128, 
    max_iters=10, 
    tolerance=1e-4
)

# Train with default settings (auto-selected configuration)
index.train()
```

### Per-operation key override

The calls above reuse the key supplied at [`create_index()`](../client/create-index) / [`load_index()`](../client/load-index). You may instead pass `index_key=` (and `user_id=` for an [RBAC user](./manage-users)) to override the per-operation key. This is required in stateless/service deployments that reload the index per request:

```python theme={null}
index.train(index_key=index_key)
```

<Note>Training requires write permission. An [RBAC user](./manage-users) without a write wrap cannot train the index.</Note>