> For the complete documentation index, see [llms.txt](https://docs.envector.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.envector.io/1.4.x/api-reference/index.md).

# Index

## module `index`

Index Module

This module provides classes and methods for managing index configurations and operations.

* `IndexConfig` — Configuration class for index settings.
* `Index` — Class for managing index operations.

### class `IndexConfig`

```python
class IndexConfig()
```

Configuration class for index settings.

**ARGUMENTS**

* `index_name` (`str`): Name of the index.
* `dim` (`int`): Dimensionality of the index.
* `key_path` (`str`): Path to the key.
* `key_id` (`str`): ID of the key.
* `seal_mode` (`str`): Seal mode for the key.
* `seal_kek_path` (`str`): KeK for AES Seal Mode
* `preset` (`str`): Preset for the index.
* `eval_mode` (`str`): Evaluation mode for the index.
* `query_encryption` (`str`): The encryption type for query. Currently, "plain" supported only.
* `index_encryption` (`str`): The encryption type for database. Currently, "cipher" supported only.
* `index_params` (`dict`): Parameters for the index.
* `metadata_encryption` (`bool`): The encryption type for metadata, e.g. True, False.
* `description` (`str`): Human-readable text describing the index.
* `key_store` (`str`): External key storage provider (e.g., `"aws"`, `"gcp"`).
* `region_name` (`str`): Region used by the external key store (AWS).
* `bucket_name` (`str`): Bucket name for external key storage.
* `secret_prefix` (`str`): Secret prefix for external key storage.

***

#### `__init__()`

```python
def __init__(index_name: Optional[str] = None,
             dim: Optional[int] = None,
             key_path: Optional[str] = None,
             key_id: Optional[str] = None,
             seal_mode: Optional[str] = None,
             seal_kek_path: Optional[str] = None,
             preset: Optional[str] = None,
             eval_mode: Optional[str] = None,
             query_encryption: Optional[str] = None,
             index_encryption: Optional[str] = None,
             index_params: Optional[dict] = None,
             index_type: Optional[str] = None,
             metadata_encryption: Optional[bool] = None,
             description: Optional[str] = None,
             use_key_stream: Optional[bool] = None,
             enc_key: Optional[bytes] = None,
             eval_key: Optional[bytes] = None,
             sec_key: Optional[bytes] = None,
             metadata_key: Optional[bytes] = None,
             seal_kek: Optional[bytes] = None,
             key_store: Optional[str] = None,
             region_name: Optional[str] = None,
             bucket_name: Optional[str] = None,
             secret_prefix: Optional[str] = None,
             vault_addr: Optional[str] = None,
             vault_mount: Optional[str] = None)
```

Initializes the IndexConfig class.

***

#### `index_name()`

```python
@property
def index_name() -> str
```

Returns the index name.

**RETURNS**

`str`: Name of the index.

***

#### `index_name()`

```python
@index_name.setter
def index_name(index_name: str)
```

Sets the index name.

**ARGUMENTS**

* `index_name` (`str`): Name of the index.

***

#### `description()`

```python
@property
def description() -> Optional[str]
```

Returns the description for the index.

**RETURNS**

`Optional[str]`: Description text if configured.

***

#### `description()`

```python
@description.setter
def description(description: Optional[str])
```

Sets the description for the index.

**ARGUMENTS**

* `description` (`Optional[str]`): Description text.

***

#### `context_param()`

```python
@property
def context_param() -> ContextParameter
```

Returns the context parameter object.

**RETURNS**

`ContextParameter`: The parameter object for this context.

***

#### `context_param()`

```python
@context_param.setter
def context_param(context_param: ContextParameter)
```

Sets the context parameter object.

**ARGUMENTS**

* `context_param` (`ContextParameter`): The parameter object for this context.

***

#### `key_param()`

```python
@property
def key_param() -> KeyParameter
```

Returns the key parameter object.

**RETURNS**

`KeyParameter`: The parameter object for the key.

***

#### `key_param()`

```python
@key_param.setter
def key_param(key_param: KeyParameter)
```

Sets the key parameter object.

**ARGUMENTS**

* `key_param` (`KeyParameter`): The parameter object for the key.

***

#### `index_param()`

```python
@property
def index_param() -> IndexParameter
```

Returns the index parameter object.

**RETURNS**

`IndexParameter`: The parameter object for the index.

***

#### `index_param()`

```python
@index_param.setter
def index_param(index_param: IndexParameter)
```

Sets the index parameter object.

**ARGUMENTS**

* `index_param` (`IndexParameter`): The parameter object for the index.

***

#### `preset()`

```python
@property
def preset() -> str
```

Returns the preset.

**RETURNS**

`str`: Preset for the index.

***

#### `preset()`

```python
@preset.setter
def preset(preset: str)
```

Sets the preset.

**ARGUMENTS**

* `preset` (`str`): Preset for the index.

***

#### `dim()`

```python
@property
def dim() -> int
```

Returns the dimensionality of the index.

**RETURNS**

`int`: Dimensionality of the index.

***

#### `dim()`

```python
@dim.setter
def dim(dim: int)
```

Sets the dimensionality of the index.

**ARGUMENTS**

* `dim` (`int`): Dimensionality of the index.

***

#### `eval_mode()`

```python
@property
def eval_mode() -> str
```

Returns the evaluation mode.

**RETURNS**

`str`: Evaluation mode for the context.

***

#### `eval_mode()`

```python
@eval_mode.setter
def eval_mode(eval_mode: str)
```

Sets the evaluation mode.

**ARGUMENTS**

* `eval_mode` (`str`): Evaluation mode for the context.

***

#### `level()`

```python
@property
def level() -> int
```

Returns the level.

**RETURNS**

`int`: Level for the context.

***

#### `level()`

```python
@level.setter
def level(level: int)
```

Sets the level.

**ARGUMENTS**

* `level` (`int`): Level for the context.

***

#### `search_type()`

```python
@property
def search_type() -> str
```

Returns the search type.

**RETURNS**

`str`: Search type for the index.

***

#### `index_encryption()`

```python
@property
def index_encryption() -> str
```

Returns whether database encryption is enabled.

**RETURNS**

`str`: The encryption type for database. Currently, "cipher" supported only.

***

#### `index_encryption()`

```python
@index_encryption.setter
def index_encryption(index_encryption: str)
```

Sets whether database encryption is enabled.

**ARGUMENTS**

* `index_encryption` (`str`): The encryption type for database. Currently, "cipher" supported only.

***

#### `query_encryption()`

```python
@property
def query_encryption() -> str
```

Returns whether query encryption is enabled.

**RETURNS**

`str`: The encryption type for query. Currently, "plain" supported only.

***

#### `query_encryption()`

```python
@query_encryption.setter
def query_encryption(query_encryption: str)
```

Sets whether query encryption is enabled.

**ARGUMENTS**

* `query_encryption` (`str`): The encryption type for query. Currently, "plain" supported only.

***

#### `index_type()`

```python
@property
def index_type() -> str
```

Returns the index type.

**RETURNS**

`str`: Type of the index.

***

#### `index_type()`

```python
@index_type.setter
def index_type(index_type: str)
```

Sets the index type.

**ARGUMENTS**

* `index_type` (`str`): Type of the index.

***

#### `index_params()`

```python
@property
def index_params() -> dict
```

Returns the index parameters.

**RETURNS**

`dict`: Parameters for the index.

***

#### `nlist()`

```python
@property
def nlist()
```

Returns the nlist parameter for IVF indices.

**RETURNS**

`int`: Number of clusters (nlist) for IVF indices.

***

#### `default_nprobe()`

```python
@property
def default_nprobe()
```

Returns the default nprobe parameter for IVF indices.

**RETURNS**

`int`: Default number of probes (nprobe) for IVF indices.

***

#### `centroids()`

```python
@property
def centroids()
```

Returns the centroids for IVF indices.

**RETURNS**

`list[list[float]]`: Centroids for IVF indices.

***

#### `key_path()`

```python
@property
def key_path() -> str
```

Returns the key path.

**RETURNS**

`str`: Path to the key.

***

#### `key_path()`

```python
@key_path.setter
def key_path(key_path: str)
```

Sets the key path.

**ARGUMENTS**

* `key_path` (`str`): Path to the key.

***

#### `key_id()`

```python
@property
def key_id() -> str
```

Returns the key ID.

**RETURNS**

`str`: ID of the key.

***

#### `key_id()`

```python
@key_id.setter
def key_id(key_id: str)
```

Sets the key ID.

**ARGUMENTS**

* `key_id` (`str`): ID of the key.

***

#### `seal_info()`

```python
@property
def seal_info() -> SealInfo
```

Returns the seal mode.

**RETURNS**

`str`: Seal mode for the keys.

***

#### `seal_mode()`

```python
@property
def seal_mode() -> str
```

Returns the seal mode.

**RETURNS**

`str`: Seal mode for the keys.

***

#### `seal_kek_path()`

```python
@property
def seal_kek_path() -> str
```

Returns the seal KEK path.

**RETURNS**

`str`: Path to the seal KEK.

***

#### `eval_key_path()`

```python
@property
def eval_key_path() -> str
```

Returns the evaluation key path.

**RETURNS**

`str`: Path to the evaluation key.

***

#### `enc_key_path()`

```python
@property
def enc_key_path() -> str
```

Returns the encryption key path.

**RETURNS**

`str`: Path to the encryption key.

***

#### `sec_key_path()`

```python
@property
def sec_key_path() -> str
```

Returns the secret key path.

**RETURNS**

`str`: Path to the secret key.

***

#### `metadata_key_path()`

```python
@property
def metadata_key_path() -> str
```

Returns the metadata encryption key path.

**RETURNS**

`str`: Path to the metadata encryption key.

***

#### `key_dir()`

```python
@property
def key_dir() -> str
```

Returns the directory where the keys are stored.

**RETURNS**

`str`: Directory for the keys.

***

#### `need_cipher()`

```python
@property
def need_cipher() -> bool
```

Returns whether cipher operations are needed.

**RETURNS**

`bool`: True if cipher operations are needed, False otherwise.

***

#### `enc_key()`

```python
@property
def enc_key() -> Optional[bytes]
```

Returns the encryption key.

**RETURNS**

`bytes`: Encryption key.

***

#### `eval_key()`

```python
@property
def eval_key() -> Optional[bytes]
```

Returns the evaluation key.

**RETURNS**

`bytes`: Evaluation key.

***

#### `sec_key()`

```python
@property
def sec_key() -> Optional[bytes]
```

Returns the secret key.

**RETURNS**

`bytes`: Secret key.

***

#### `metadata_key()`

```python
@property
def metadata_key() -> Optional[bytes]
```

Returns the metadata encryption key.

**RETURNS**

`bytes`: Metadata encryption key.

***

#### `seal_kek()`

```python
@property
def seal_kek() -> Optional[bytes]
```

Returns the seal KEK.

**RETURNS**

`bytes`: Seal KEK.

***

#### `use_key_stream()`

```python
@property
def use_key_stream() -> bool
```

Returns whether key stream is used.

**RETURNS**

`bool`: True if key stream is used, False otherwise.

***

#### `deepcopy()`

```python
def deepcopy(index_name: Optional[str] = None,
             dim: Optional[int] = None,
             key_path: Optional[str] = None,
             key_id: Optional[str] = None,
             seal_mode: Optional[str] = None,
             seal_kek_path: Optional[str] = None,
             preset: Optional[str] = None,
             eval_mode: Optional[str] = None,
             query_encryption: Optional[str] = None,
             index_encryption: Optional[str] = None,
             index_params: Optional[dict] = None,
             metadata_encryption: Optional[bool] = None,
             description: Optional[str] = None,
             use_key_stream: Optional[bool] = None,
             enc_key: Optional[bytes] = None,
             eval_key: Optional[bytes] = None,
             sec_key: Optional[bytes] = None,
             metadata_key: Optional[bytes] = None,
             seal_kek: Optional[bytes] = None,
             key_store: Optional[str] = None,
             region_name: Optional[str] = None,
             bucket_name: Optional[str] = None,
             secret_prefix: Optional[str] = None,
             vault_addr: Optional[str] = None,
             vault_mount: Optional[str] = None) -> "IndexConfig"
```

Creates a deep copy of the index configuration.

**RETURNS**

`IndexConfig`: A deep copy of the index configuration.

### class `Index`

```python
class Index()
```

Class for managing index operations.

**ARGUMENTS**

* `index_config` (`IndexConfig`): Configuration for the index.
* `indexer` (`Indexer`): Indexer object for managing connections.
* `num_entities` (`int`): Number of entities in the index.
* `cipher` (`Cipher`): Cipher object for encryption and decryption.

***

#### `__init__()`

```python
def __init__(index_name: str, index_config: Optional[IndexConfig] = None)
```

Initializes the Index class.

Check server connection and check if the index exists.

**ARGUMENTS**

* `index_name` (`str`): Name of the index.
* `index_config` (`IndexConfig`): Configuration object to override defaults (such as key paths and encryption options). Falls back to `Index._default_index_config`.

***

#### `init_connect()`

```python
@classmethod
def init_connect(cls,
                 address: str,
                 access_token: AccessTokenInput = None,
                 secure: Optional[bool] = None,
                 refresh_token: Optional[str] = None,
                 oidc_issuer: Optional[str] = None,
                 token_endpoint: Optional[str] = None,
                 client_id: Optional[str] = None,
                 client_secret: Optional[str] = None,
                 scope: Optional[str] = None) -> "Indexer"
```

Connects to the indexer.

**ARGUMENTS**

* `address` (`str`): Address of the indexer.
* `access_token` (\`\`\`str\`\` or callable\`): Access token for authentication, or a callable returning the current token for refreshable auth flows.
* `secure` (`bool`): Whether to use a secure connection. If None, (defaults to True when access\_token or refresh\_token is provided, otherwise False.)
* `refresh_token` (`str`): OIDC refresh token used by the SDK to renew bearer tokens.
* `oidc_issuer` (`str`): OIDC issuer URL used to discover the token endpoint.
* `token_endpoint` (`str`): Explicit token endpoint used for refresh token exchange.
* `client_id` (`str`): OIDC client ID for refresh token exchange.
* `client_secret` (`str`): OIDC client secret for refresh token exchange.
* `scope` (`str`): Optional scope value included in refresh requests.

**RETURNS**

`Indexer`: Connected indexer object.

***

#### `init_key_path()`

```python
@classmethod
def init_key_path(cls, key_path: str)
```

Initializes the key path for the index.

**ARGUMENTS**

* `key_path` (`str`): Path to the key directory.

***

#### `create_index()`

```python
@classmethod
def create_index(cls,
                 index_config: IndexConfig,
                 indexer: Optional[Indexer] = None) -> "Index"
```

Creates a new index.

**ARGUMENTS**

* `index_config` (`IndexConfig`): Configuration for the index.
* `indexer` (`Indexer`): Indexer object for managing connections.

**RETURNS**

`Index`: The created index.

***

#### `insert()`

```python
def insert(data: Union[CipherBlock, List[List[float]], List[np.ndarray],
                       np.ndarray, List[CipherBlock]],
           metadata: List[Any] = None,
           request_ids: Optional[List[str]] = None,
           await_completion: bool = False,
           execute_until: str = "segmentation",
           load: bool = True,
           use_row_insert: bool = False,
           encryptor=None,
           **kwargs)
```

Inserts data into the index.

enVector INSERT requests are asynchronous. `Index.insert()` always submits the split/persist RPCs first. `execute_until="flush"` stops there, while `execute_until="segmentation"` additionally submits `merge_by_request_ids` for the captured split request IDs. For request-scoped completion tracking, pass an empty list as `request_ids`. The server-generated split request IDs will be appended to it after each underlying async split RPC completes.

**ARGUMENTS**

* `data` (`CipherBlock, list of floats, list of np.ndarray, 2D np.ndarray, or list of CipherBlock`): Data to be inserted. It can be plaintext (list of lists, list of numpy arrays, or 2D numpy array) or ciphertext (`CipherBlock` or list of `CipherBlock`).
* `metadata` (`str`): Metadata for the data.
* `request_ids` (`Optional[List[str]]`): Out list for server-generated request identifiers (from response `header.id`).
* If `None` (default), the client does not capture request identifiers and you cannot poll completion for this insert.
* If provided, the list is cleared and filled with the server-generated request IDs (one per underlying async split request). These are the split request IDs; use them with :meth:`get_index_operation_status`, :meth:`wait_for_inserts_searchable`, or :meth:`async_merge_by_request_ids`.
* `await_completion` (`bool`): If `True`, block until the selected server-side stage is reached. `"flush"` waits for `SPLIT_COMPLETED`; `"segmentation"` waits for `MERGED_SAVED`. When `load=True` is also set, the SDK then calls :meth:`load` after that stage wait completes. The SDK does not perform an additional searchable wait automatically; use :meth:`wait_for_inserts_searchable` when callers need a `done=true` searchable guarantee.
* `execute_until` (`str`): Server-side completion stage for this insert. Supported values are:
* `"flush"`: stop after split/persist submission
* `"segmentation"`: submit `merge_by_request_ids` after split request IDs are captured
* `load` (`bool`): If `True`, call :meth:`load` after submission, or after the selected stage wait when `await_completion=True`. This triggers backend publication work but does not add an SDK-side searchable wait on its own. When invoked before merge completion, backend `LoadIndex` may expose raw fallback shards while request-scoped merge work is still unfinished.
* `use_row_insert` (`bool`): If `True`, small plaintext chunks (fewer vectors than `dim`) use the row-insert path instead of bulk insertion. Default: `False`.
* `encryptor` (`Encryptor or Cipher`): Custom encryptor for this insert call. When provided, this encryptor is used instead of `self.cipher` for FHE encryption. This enables thread-safe parallel inserts by giving each thread its own encryptor with an independent PRNG state. Accepts either an `Encryptor` instance or a `Cipher` instance (its internal encryptor is used). If `None` (default), `self.cipher` is used.

**RETURNS**

`Index`: The index object after insertion.

***

#### `delete()`

```python
def delete(item_ids: List[int],
           await_completion: bool = True,
           timeout_s: float = 600.0,
           poll_interval_s: float = 1.0) -> str
```

Deletes items from the index by item ID.

The server rebuilds affected shards excluding the deleted items. This operation is asynchronous — by default the SDK polls until the shard rebuild is complete and the remaining data becomes searchable.

**ARGUMENTS**

* `item_ids` (`List[int]`): List of item IDs to delete. These must be `item_id` values originally returned by `Index.insert()` or the low-level insert APIs (`Indexer.insert_data_bulk()`, `Indexer.insert_data_rows_batch()`). Must be non-empty, contain only positive integers, and have no duplicates.
* `await_completion` (`bool`): If `True` (default), poll `get_index_operation_status` with `operation_type=DELETE` until the operation reaches SEARCHABLE state. If `False`, return immediately after submitting the request.
* `timeout_s` (`float`): Maximum time to wait for completion (seconds). Only used when `await_completion=True`. Default: 600s.
* `poll_interval_s` (`float`): Poll interval (seconds). Only used when `await_completion=True`. Default: 1s.

**Raises**:

* `ValueError`: If the index is not loaded.
* `EnvectorValidationError`: If `item_ids` is empty, contains duplicates, or contains non-positive values.
* `EnvectorTimeoutError`: If `await_completion=True` and the operation does not complete within `timeout_s`.

**RETURNS**

`str`: Server-generated `request_id` for tracking operation completion.

***

#### `search()`

```python
def search(query: Union[List[float], np.ndarray, List[List[float]],
                        List[np.ndarray], List[CipherBlock]],
           top_k: int,
           output_fields: List[str] = None,
           search_params: dict = None)
```

Searches the index.

**ARGUMENTS**

* `query` (`list of float or np.ndarray`): Query vector.
* `top_k` (`int`): Number of top results to return (default 3).
* `output_fields` (`list of str`): Fields to include in the output.

**RETURNS**

`list of dict`: Search results.

***

#### `scoring()`

```python
def scoring(query: Union[List[float], np.ndarray, CipherBlock,
                         List[List[float]], List[np.ndarray],
                         List[CipherBlock]],
            search_params: dict = None)
```

Computes the scores for a query against the index.

**ARGUMENTS**

* `query` (`list`): Query vector.
* `search_params` (`dict`): Additional search-time parameters understood by the server.

**Raises**:

* `ValueError`: If the index is not connected.

**RETURNS**

list of dict: Scores for the query.

***

#### `get_topk_metadata_results()`

```python
def get_topk_metadata_results(result,
                              top_k: int,
                              output_fields: List[str] = None)
```

Get top-k metadata results from the search ciphertext result.

**ARGUMENTS**

* `result` (`CipherBlock`): The result context containing encrypted scores.
* `top_k` (`int`): Number of top results to return.
* `output_fields` (`list of str`): Fields to include in the output.

**Raises**:

* `ValueError`: If the indexer is not connected or if the result is empty.

**RETURNS**

list of dict: List of dictionaries containing the top-k results with metadata.

***

#### `decrypt_score()`

```python
def decrypt_score(result_ctxt: CipherBlock,
                  sec_key_path: Optional[str] = None,
                  seal_mode: Optional[str] = None,
                  seal_kek_path: Optional[str] = None)
```

Decrypts the scores from the result context.

**ARGUMENTS**

* `result_ctxt` (`CipherBlock`): The result context containing encrypted scores.
* `sec_key_path` (`str`): Path to the secret key used for decryption.
* `seal_mode` (`str`): Seal mode name for decrypting sealed keys.
* `seal_kek_path` (`str or bytes`): Path, bytes to the KEK when unsealing the key.

**RETURNS**

list of float: Decrypted scores.

***

#### `load()`

```python
def load()
```

Loads the index into memory.

This call is also used to publish pending merged shards for indexes that are already loaded. Backend `load_index` returns an "already loaded" error when there is nothing new to publish; that case is treated as a no-op here.

**RETURNS**

`Index`: The index object after loading it.

***

#### `unload()`

```python
def unload()
```

Unloads the index from memory.

**RETURNS**

`Index`: The index object after unloading it.

***

#### `drop()`

```python
def drop()
```

Drops the index.

**RETURNS**

`Index`: The index object after dropping it.

***

#### `summary()`

```python
def summary()
```

Returns a summary of the index.

**RETURNS**

`Dict`: A dictionary containing the index summary. Capacity-related keys include: `can_load_now`, `remaining_insertable_shards`, `remaining_insertable_vectors_guaranteed`, `remaining_insertable_vectors_best_effort`.

***

#### `is_connected()`

```python
@property
def is_connected() -> bool
```

Checks if the indexer is connected.

**RETURNS**

`bool`: True if the indexer is connected, False otherwise.

***

#### `is_loaded()`

```python
@property
def is_loaded() -> bool
```

Checks if the index is loaded in memory.

**RETURNS**

`bool`: True if the index is loaded, False otherwise.

***

#### `remaining_insertable_vectors()`

```python
@property
def remaining_insertable_vectors() -> int
```

Returns the number of remaining insertable vectors in the index.

**RETURNS**

`int`: The number of remaining insertable vectors.

***

#### `remaining_insertable_shards()`

```python
@property
def remaining_insertable_shards() -> int
```

Returns the number of remaining insertable shards in the index.

**RETURNS**

`int`: The number of remaining insertable shards.

***

#### `loadable()`

```python
@property
def loadable() -> bool
```

Checks if the index is loadable.

**RETURNS**

`bool`: True if the index is loadable, False otherwise.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.envector.io/1.4.x/api-reference/index.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.