Skip to main content
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

ParameterTypeDescription
indexNamestringName of the index to create. Must be unique within the CyborgDB service.
indexKeyUint8Array(Optional) 32-byte encryption key. Required when kmsName is omitted. Must be omitted when kmsName references a real KMS provider.
kmsNamestring(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.
dimensionnumber(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.
embeddingModelstring(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

  • 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).
  • 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.