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

ParameterTypeDescription
ctxcontext.ContextContext for cancellation/timeouts
params*CreateIndexParamsConfiguration for the new index

​
CreateIndexParams

FieldTypeRequiredDescription
IndexNamestringYesUnique identifier for the index
IndexKey[]byteConditional32-byte encryption key. Required when KmsName is nil; mutually exclusive with KmsName against a real-KMS slot.
KmsName*stringConditionalName of a kms.registry entry in the service YAML. Required when IndexKey is nil.
Dimension*int32NoVector dimensionality. Auto-detected from the first upsert if nil.
Metric*stringNoDistance metric ("euclidean", "squared_euclidean", "cosine"). Defaults to the server’s default ("euclidean").
EmbeddingModel*stringNoOptional sentence-transformers model name for automatic embedding generation.
StoragePrecision*stringNoOn-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

TypeDescription
*EncryptedIndexHandle for performing vector operations on the new index
errorAny error encountered during index creation

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