🆕Creation

This guide explains how to create an encrypted index using the enVector Python SDK. The index creation process involves configuring encryption parameters and creating the index with specified settings.

Detailed Usage Using Arguments

🧩 Index Configuration Details

Index creation relies on an index configuration that the SDK keeps in memory. You can set it once via ev.init_index_config(...) and/or override key parts when calling create_index(...).

Core parameters you’ll use most often:

• Identity: index_name (str), dim (int, max 4096)

• Key management: auto_key_setup (bool, default True), key_path (str), key_id (str), metadata_encryption (bool, default True), seal_mode ("none"|"aes"), seal_kek_path (when seal_mode='aes')

• Presets and modes: preset ("ip"), index_type ("flat"), query_encryption ("plain"|"cipher"), index_encryption (always "cipher"), eval_mode ("rmp" | "mm")

  • Note: mm is an advanced mode and currently does not support encrypted queries (query_encryption="cipher"). Use rmp for end‑to‑end encrypted search.

Recommended setup pattern:

import pyenvector as ev

# 1) Connect first
ev.init_connect(address="your.hostname:50050")

# 2) Initialize index configuration (can be called once per session)
ev.init_index_config(
    key_path="keys",
    key_id="my-key",
    auto_key_setup=True,       # auto-generate & register if missing
    metadata_encryption=True,  # encrypt metadata at rest/in transit
    seal_mode="none",         # or "aes" with seal_kek_path
    # seal_kek_path="./aes.kek", # use a 32-byte file

    # Search/crypto presets
    preset="ip",              # optimized for inner product
    index_type="flat",        # exhaustive search
    query_encryption="cipher" # end-to-end encrypted search
)

# 3) Create the index (you should pass name + dimension explicitly)
index = ev.create_index(index_name="products", dim=768)

For full explanations of each parameter, see:

• Basic identification: user-guide/initialize/index-configuration/1.-basic-index-identification.md

• 🔑 Key management: user-guide/initialize/index-configuration/2.-key-management.md

• 🚀 Presets and modes: user-guide/initialize/index-configuration/3.-presets.md

1. Basic Index Creation

To create an index, you must first initialize pyenvector. For custom settings, please refer to Index Configuration.

# Initialize the SDK
import pyenvector as ev

HOST_ADDRESS = "your.hostname:50050"

ev.init(address=HOST_ADDRESS, key_path="./keys", key_id="key_id")

# Create the index
index = ev.create_index(index_name="my_index", dim=128)

Important Notes: The maximum value for vector dimension is 4096

2. Complete Working Example

import pyenvector as ev
import os
import numpy as np
from pyenvector.crypto import KeyGenerator
from pyenvector.index import IndexConfig, Index

HOST_ADDRESS = "your.hostname:50050"

def create_encrypted_index(key_path, key_id, index_name, dim):
    # Init Connection and Index Configuration
    ev.init_connect(address=HOST_ADDRESS)
    ev.init_index_config(
        key_path=key_path,
        key_id=key_id,
    )

    # Create index
    try:
        index = ev.create_index(index_name=index_name, dim=dim)
        print(f"Index '{index_config.index_name}' created successfully")
        return index
    except Exception as e:
        print(f"Failed to create index: {e}")
        return None

# Usage example
# index = create_encrypted_index()

3. Error Handling

try:
    index = ev.create_index(index_name="my_index", dim=128)
except ValueError as e:
    if "Indexer not connected" in str(e):
        print("Please ensure the server is running and accessible")
    elif "Key ID not found" in str(e):
        print("Please register the key with the server first")
    elif "Key path mismatch" in str(e):
        print("Please reinitialize the SDK with ev.init()")
    else:
        print(f"Configuration error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

4. Verification

After creating an index, you can verify it was created successfully:

# The index object is returned upon successful creation
if index is not None:
    print("Index created successfully!")
    print(f"Index name: {index.index_name}")
    print(f"Index dimension: {index.dim}")
    
    # Print full index information
    print("\nFull index details:")
    print(index)
else:
    print("Index creation failed")

5. Best Practices

1. Dimension Selection: Choose dimensions based on your vector model requirements (maximum: 4096)

2. Encryption Strategy:

   • Query encryption: Choose based on your use case:

     • "plain": When query vectors can be sent in cleartext

     • "cipher": When query privacy is required (e.g., sensitive user queries)

3. Error Handling: Implement proper error handling for production deployments

4. Resource Cleanup: Ensure proper cleanup of resources after operations

This completes the guide for creating encrypted indexes with the enVector Python SDK. The process ensures secure, encrypted storage of your vector data while maintaining search functionality.

Note: This guide assumes you have already configured enVector server and registered your encryption keys. For connection and key registration details, please refer to the respective documentation sections.