Create Index

Creates and returns a new encrypted index. CyborgDB v0.17 uses a single DiskIVF index type, so there is no longer an index_config parameter to choose between index variants.

def create_index(self,
                 index_name: str,
                 index_key: bytes,
                 *,
                 dimension: int | None = None,
                 storage_precision = None,
                 embedding_model: str | None = None,
                 metric: str | None = None,
                 logger: Logger | None = None) -> EncryptedIndex

All parameters after index_key are keyword-only.

Parameters

Parameter	Type	Default	Description
index_name	str	-	Name of the index to create. Must be unique.
index_key	bytes	-	32-byte encryption key (KEK) for the index, used to secure the index data.
dimension	int | None	None	(Optional, keyword-only) Dimensionality of vector embeddings. When None, auto-detected from the first upsert (or derived from embedding_model).
storage_precision	np.float32 | np.float16	np.float32	(Optional, keyword-only) On-disk dtype for the rerank vectors. np.float16 (or "float16") halves the disk footprint with a slight precision loss. See storage precision.
embedding_model	str | None	None	(Optional, keyword-only) Name of the SentenceTransformer model to use for automatic text embeddings.
metric	str | None	"euclidean"	(Optional, keyword-only) Distance metric to use: "euclidean", "cosine", or "squared_euclidean". See DistanceMetric.
logger	Logger	None	(Optional, keyword-only) Logger instance for capturing operation logs.

For more info on auto-generating embeddings, refer to Auto-Generate Embeddings.

Returns

EncryptedIndex: An instance of the newly created encrypted index.

Exceptions

ValueError

• Throws if the index name is not unique.
• Throws if the index configuration is invalid.
• Throws if the index could not be created.

Example Usage

Automatic Setup

import cyborgdb_core as cyborgdb
import secrets

api_key = "your_api_key_here"  # Replace with your CyborgDB API key

client = cyborgdb.Client(api_key, cyborgdb.StorageConfig.memory())

index_name = "my_index"
index_key = secrets.token_bytes(32)  # 32-byte index KEK — store securely

# Dimension auto-detected from the first upsert
index = client.create_index(index_name, index_key)

Explicit Setup

import cyborgdb_core as cyborgdb
import numpy as np
import secrets

api_key = "your_api_key_here"  # Replace with your CyborgDB API key

client = cyborgdb.Client(api_key, cyborgdb.StorageConfig.disk("/tmp/cyborgdb"))

index_name = "my_index"
index_key = secrets.token_bytes(32)  # 32-byte index KEK — store securely

# Optional: Set up logging
logger = cyborgdb.Logger.instance()
logger.configure(level="info", to_file=True, file_path="index_creation.log")

index = client.create_index(
    index_name,
    index_key,
    dimension=128,
    storage_precision=np.float16,  # halve on-disk rerank-vector footprint
    metric="cosine",
    logger=logger,
)