Create Index

Creates and returns an EncryptedIndex instance backed by a new encrypted DiskIVF index on the server.

v0.17 introduces a single DiskIVF index type and removes the polymorphic index_config argument. The previous IndexIVFFlat, IndexIVFPQ, and IndexIVFSQ types are gone — index configuration is now expressed as flat keyword arguments (dimension, metric, storage_precision).

client.create_index(
    index_name,
    index_key = None,
    kms_name = None,
    dimension = None,
    embedding_model = None,
    metric = None,
    storage_precision = None,
)

Parameters

Parameter	Type	Default	Description
index_name	str	-	Unique name for the index
index_key	bytes	None	(Optional) 32-byte encryption key. Required when kms_name is omitted (SDK-supplied KEK). Must be omitted when kms_name references a real KMS provider.
kms_name	str	None	(Optional) Name of a kms.registry entry in the service YAML. When supplied, the service generates the KEK and wraps it under the named provider; the SDK never sees the plaintext key.
dimension	int	None	(Optional) Vector dimensionality. If omitted, the server auto-detects from the first upsert.
embedding_model	str	None	(Optional) sentence-transformers model name for automatic embedding generation. When set, dimension is inferred from the model.
metric	str	None	(Optional) Distance metric ("euclidean", "squared_euclidean", or "cosine"). When None, the server applies its default.
storage_precision	str	None	(Optional) On-disk rerank-vector dtype: "float32" (default) or "float16".

Key Management Modes

At least one of index_key / kms_name must be supplied; supplying both against a real-KMS slot is rejected by the server with 400:

• SDK-supplied KEK — pass index_key, omit kms_name. The server records the index with provider: none; you must re-supply the same key on every subsequent call (load_index, query, upsert, etc.).
• KMS-backed — pass kms_name, omit index_key. The server generates the DEK, wraps it under the named registry slot, and persists the envelope. Subsequent calls omit index_key entirely.

Returns

An instance of EncryptedIndex bound to the newly created index. For KMS-backed indexes the returned handle holds no plaintext key.

Exceptions

ValueError

• Raised if neither index_key nor kms_name is provided.
• Raised if index_key is provided but is not exactly 32 bytes.
• Raised by the server (re-wrapped as ValueError) if both index_key and kms_name are provided against a real-KMS slot.
• Raised by the server if the index name already exists, the embedding model is unsupported, or the KMS slot lookup fails.

Service Errors

• Raised if the CyborgDB service is unavailable, unreachable, or returns 5xx (including KMS-wrap failures as 502).

Example Usage

SDK-supplied key (basic)

from cyborgdb import Client

# Initialize client
client = Client(base_url='http://localhost:8000', api_key='your-api-key')

# Generate a secure encryption key
index_key = client.generate_key(save=True)

# Create a basic index — dimension is auto-detected from the first upsert
index = client.create_index('documents', index_key=index_key)

For more info on generate_key, refer to Generate Key.

SDK-supplied key with explicit dimension

# Pin the dimension and metric explicitly
index = client.create_index(
    'documents',
    index_key=index_key,
    dimension=384,
    metric='cosine',
)

KMS-backed index

# The service generates the KEK, wraps it via the 'prod-aws' registry slot,
# and persists the envelope. The SDK never sees the plaintext key.
index = client.create_index(
    'kms_documents',
    kms_name='prod-aws',
    dimension=384,
)
# Subsequent calls — including load_index — omit index_key entirely.

Auto-embedding

# When embedding_model is set, the server infers `dimension` from the model.
index = client.create_index(
    'semantic_docs',
    index_key=index_key,
    embedding_model='all-MiniLM-L6-v2',
)

Float16 storage for reduced footprint

# Halves on-disk rerank-vector storage at the cost of small recall
index = client.create_index(
    'compact_docs',
    index_key=index_key,
    dimension=768,
    storage_precision='float16',
)

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