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. The polymorphic IndexIVFFlat / IndexIVFPQ / IndexIVFSQ types and the indexConfig argument have been removed — index configuration is now expressed as flat keyword arguments (dimension, metric, storagePrecision).

async createIndex({
    indexName: string,                                      // required
    indexKey?: Uint8Array,                                  // optional (see Key Management)
    kmsName?: string,                                       // optional (see Key Management)
    dimension?: number,                                     // optional, auto-detected from first upsert
    metric?: 'euclidean' | 'squared_euclidean' | 'cosine',  // optional, defaults to server default ('euclidean')
    embeddingModel?: string,                                // optional
    storagePrecision?: 'float32' | 'float16'                // optional, defaults to 'float32'
}): Promise<EncryptedIndex>

Parameters

Parameter	Type	Description
`indexName`	`string`	Name of the index to create. Must be unique within the CyborgDB service.
`indexKey`	`Uint8Array`	(Optional) 32-byte encryption key. Required when `kmsName` is omitted. Must be omitted when `kmsName` references a real KMS provider.
`kmsName`	`string`	(Optional) Name of a `kms.registry` entry in the service YAML. When supplied, the server generates the KEK and wraps it via the named provider; the SDK never sees the plaintext key.
`dimension`	`number`	(Optional) Vector dimensionality. If omitted, the server auto-detects from the first upsert.
`metric`	`'euclidean' \| 'squared_euclidean' \| 'cosine'`	(Optional) Distance metric. If omitted, the SDK does not set a value and the server applies its default.
`embeddingModel`	`string`	(Optional) sentence-transformers model name for automatic embedding generation.
`storagePrecision`	`'float32' \| 'float16'`	(Optional) On-disk rerank-vector dtype. Defaults to `'float32'`.

Key Management Modes

At least one of indexKey / kmsName must be supplied; supplying both against a real-KMS slot is rejected by the server:

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

Returns

Promise<EncryptedIndex>: A Promise that resolves to a handle bound to the newly created index.

Exceptions

Error

Throws if neither indexKey nor kmsName is provided.
Throws if indexKey is provided but is not exactly 32 bytes.
Throws if the index name already exists on the server.
Throws if the embedding model is not supported by the server.
Throws if both indexKey and kmsName are provided against a real-KMS slot (rejected by the server with 400).

Service Errors

Throws if the CyborgDB service is unavailable or unreachable.
Throws on 5xx responses, including KMS-wrap failures (502).

Example Usage

SDK-supplied key

import { Client } from 'cyborgdb';

// Initialize client
const client = new Client({ baseUrl: 'http://localhost:8000', apiKey: 'your-api-key' });

// Generate a secure 32-byte encryption key
const indexKey: Uint8Array = client.generateKey();

// Create a basic index
const index = await client.createIndex({
    indexName: 'my_vector_index',
    indexKey,
    dimension: 384,
});

For more info on generateKey, refer to Generate Key.

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.
const index = await client.createIndex({
    indexName: 'kms_vector_index',
    kmsName: 'prod-aws',
    dimension: 384,
});
// Subsequent calls — including loadIndex — omit indexKey entirely.

With embedding model

// When embeddingModel is set, the server infers `dimension` from the model.
const index = await client.createIndex({
    indexName: 'semantic_search_index',
    indexKey,
    embeddingModel: 'all-MiniLM-L6-v2',
});

Float16 storage for reduced footprint

// Halves on-disk rerank-vector storage at the cost of small recall
const index = await client.createIndex({
    indexName: 'compact_index',
    indexKey,
    dimension: 768,
    storagePrecision: 'float16',
});

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

Introduction

Client

Encrypted Index

Types & Helpers

Parameters

Key Management Modes

Returns

Exceptions

Example Usage

SDK-supplied key

KMS-backed index

With embedding model

Float16 storage for reduced footprint

​Parameters

​Key Management Modes

​Returns

​Exceptions

​Example Usage

​SDK-supplied key

​KMS-backed index

​With embedding model

​Float16 storage for reduced footprint

Parameters

Key Management Modes

Returns

Exceptions

Example Usage

SDK-supplied key

KMS-backed index

With embedding model

Float16 storage for reduced footprint