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.

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.
user_id	bytes	None	(Optional, keyword-only) 16-byte RBAC user identifier. See Per-operation key override.

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

Exceptions

ValueError

• Raises an exception if the index was not created or loaded yet.

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.

Example Usage

# 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() / load_index(). You may instead pass index_key= (and user_id= for an RBAC user) to override the per-operation key. This is required in stateless/service deployments that reload the index per request:

index.train(index_key=index_key)

Training requires write permission. An RBAC user without a write wrap cannot train the index.