Load Index - CyborgDB Docs

Loads and connects to an existing encrypted index by name. indexKey is optional in v0.17: SDK-supplied indexes (provider: none) must pass the exact 32-byte key used at creation, while KMS-backed indexes omit it — the service resolves the KEK via the stored KMSBlob.

async loadIndex({
    indexName: string,       // required
    indexKey?: Uint8Array    // optional (see notes)
}): Promise<EncryptedIndex>

Parameters

Parameter	Type	Description
`indexName`	`string`	Name of the existing index to load
`indexKey`	`Uint8Array`	(Optional) The exact 32-byte encryption key used when creating the index. Required for indexes created with the SDK-supplied KEK path (`provider: none`); omit for KMS-backed indexes.

In v0.17 indexKey is optional. KMS-backed indexes (created with kmsName) omit it — the server resolves the DEK via the persisted KMSBlob. SDK-supplied indexes must re-supply the same 32-byte key here.

For SDK-supplied indexes, the encryption key must exactly match the key used during index creation. KMS-backed indexes are tied to their kmsName slot in the service YAML — load fails if that slot is missing or unreachable.

Returns

Promise<EncryptedIndex>: A Promise that resolves to an EncryptedIndex instance ready for vector operations (query, upsert, delete, etc.)

Exceptions

Error

Throws if the index doesn’t exist on the server
Throws if the encryption key is incorrect or invalid
Throws by the server if a KMS-backed index’s slot is unavailable.
Throws if the server returns an HTTP error status.
Throws if authentication fails (invalid API key).

Service Errors

Throws if the CyborgDB service is unavailable or unreachable.
Throws if there are internal server errors on the CyborgDB service.

Example Usage

import { Client } from 'cyborgdb';

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

// Use the same key that was used to create the index
const indexKey = new Uint8Array(32); // Your stored 32-byte key
// Or convert from hex: Buffer.from('your-hex-key', 'hex')

// SDK-supplied index (legacy path) — supply the key
try {
    const index = await client.loadIndex({ indexName: 'my-existing-index', indexKey });
    console.log('Index loaded successfully');

    // Now you can perform operations on the loaded index
    const results = await index.query({ queryVectors: [0.1, 0.2, 0.3], topK: 5 });
    console.log('Query results:', results);
} catch (error) {
    console.error('Failed to load index:', error.message);
}

// KMS-backed index — no key required
const kmsIndex = await client.loadIndex({ indexName: 'kms-index' });

​Parameters

​Returns

​Exceptions

​Example Usage

Parameters

Returns

Exceptions

Example Usage