Create Index

Creates a new encrypted DiskIVF vector index. The new index is empty and ready for vector operations.

v0.17 introduces a single DiskIVF index type. The polymorphic IndexIVFFlat / IndexIVFPQ / IndexIVFSQ helpers and the IndexConfig field have been removed — configuration is now expressed as flat fields on CreateIndexParams (Dimension, Metric, StoragePrecision).

func (c *Client) CreateIndex(ctx context.Context, params *CreateIndexParams) (*EncryptedIndex, error)

Parameters

Parameter	Type	Description
`ctx`	`context.Context`	Context for cancellation/timeouts
`params`	`*CreateIndexParams`	Configuration for the new index

CreateIndexParams

Field	Type	Required	Description
`IndexName`	`string`	Yes	Unique identifier for the index
`IndexKey`	`[]byte`	Conditional	32-byte encryption key. Required when `KmsName` is nil; mutually exclusive with `KmsName` against a real-KMS slot.
`KmsName`	`*string`	Conditional	Name of a `kms.registry` entry in the service YAML. Required when `IndexKey` is nil.
`Dimension`	`*int32`	No	Vector dimensionality. Auto-detected from the first upsert if nil.
`Metric`	`*string`	No	Distance metric (`"euclidean"`, `"squared_euclidean"`, `"cosine"`). Defaults to the server’s default (`"euclidean"`).
`EmbeddingModel`	`*string`	No	Optional sentence-transformers model name for automatic embedding generation.
`StoragePrecision`	`*string`	No	On-disk rerank-vector dtype: `"float32"` (default) or `"float16"`.

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 — set IndexKey, leave KmsName nil. The server records the index with provider: none; you must re-supply the same key on every subsequent call.
KMS-backed — set KmsName, leave IndexKey nil. The server generates the DEK, wraps it under the named registry slot, and persists the envelope. Subsequent calls omit IndexKey entirely.

Returns

Type	Description
`*EncryptedIndex`	Handle for performing vector operations on the new index
`error`	Any error encountered during index creation

Errors

Common errors

ErrMissingKeyOrKMS — Returned when neither IndexKey nor KmsName is provided.
Returns error if IndexKey is provided but is not exactly 32 bytes.
Returns error if the index name already exists on the server.
Returns error if both IndexKey and KmsName are provided against a real-KMS slot (server-side 400).
Returns error if the embedding model is unsupported.

Service Errors

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

Example Usage

SDK-supplied key

package main

import (
    "context"
    "log"

    "github.com/cyborginc/cyborgdb-go"
)

func main() {
    // Create client
    client, err := cyborgdb.NewClient("http://localhost:8000", "your-api-key")
    if err != nil {
        log.Fatal(err)
    }

    // Generate encryption key
    key, err := cyborgdb.GenerateKey()
    if err != nil {
        log.Fatal(err)
    }

    // Create basic index
    dimension := int32(384)
    params := &cyborgdb.CreateIndexParams{
        IndexName: "my-documents",
        IndexKey:  key,
        Dimension: &dimension,
    }

    ctx := context.Background()
    index, err := client.CreateIndex(ctx, params)
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Created index: %s", index.GetIndexName())
}

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.
kmsName := "prod-aws"
dimension := int32(384)

params := &cyborgdb.CreateIndexParams{
    IndexName: "kms-documents",
    KmsName:   &kmsName,
    Dimension: &dimension,
}

index, err := client.CreateIndex(context.Background(), params)
if err != nil {
    log.Fatal(err)
}
// Subsequent calls — including LoadIndex — pass a nil key.

Auto-embedding with cosine metric

// Initialize client and key (omitted for brevity)
client, _ := cyborgdb.NewClient("http://localhost:8000", "your-api-key")
key, _ := cyborgdb.GenerateKey()

// Create an index with automatic embedding generation
metric := "cosine"
embeddingModel := "all-MiniLM-L6-v2"

params := &cyborgdb.CreateIndexParams{
    IndexName:      "large-dataset",
    IndexKey:       key,
    Metric:         &metric,
    EmbeddingModel: &embeddingModel,
}

ctx := context.Background()
index, err := client.CreateIndex(ctx, params)
if err != nil {
    log.Fatal(err)
}

Float16 storage for reduced footprint

// Create a compact index using float16 on-disk rerank vectors
dimension := int32(768)
storage := cyborgdb.StoragePrecisionFloat16

params := &cyborgdb.CreateIndexParams{
    IndexName:        "compact-index",
    IndexKey:         key,
    Dimension:        &dimension,
    StoragePrecision: &storage,
}

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

Introduction

Client

Encrypted Index

Types & Helpers

Parameters

CreateIndexParams

Key Management Modes

Returns

Errors

Example Usage

SDK-supplied key

KMS-backed index

Auto-embedding with cosine metric

Float16 storage for reduced footprint

​Parameters

​CreateIndexParams

​Key Management Modes

​Returns

​Errors

​Example Usage

​SDK-supplied key

​KMS-backed index

​Auto-embedding with cosine metric

​Float16 storage for reduced footprint

Parameters

CreateIndexParams

Key Management Modes

Returns

Errors

Example Usage

SDK-supplied key

KMS-backed index

Auto-embedding with cosine metric

Float16 storage for reduced footprint