Train Index - CyborgDB Docs

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,
          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`	-	(Required, keyword-only) 32-byte index KEK. See Index key.
`user_id`	`bytes`	`None`	(Optional, keyword-only) 16-byte RBAC user identifier. See Index key.

Training needs at least 10,000 vectors in the index and at least 2 * n_lists vectors. Below either threshold, train() does not raise: it logs a warning and leaves the index untrained. Check is_trained() afterwards.

Exceptions

ValueError

Raises an exception if the index was not created or loaded yet.
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,
    index_key=index_key
)

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

Index key

index_key is required on every call. Pass the same 32-byte index KEK you used with create_index() / load_index(). For an RBAC user, pass the user’s KEK as index_key= together with their user_id=:

index.train(index_key=user_kek, user_id=user_id)

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