Skip to main content
Adds new vectors to the index or updates existing ones. Vector data is encrypted end-to-end before being stored. 
// Upsert accepts either VectorItems or BinaryUpsertParams
func (e *EncryptedIndex) Upsert(ctx context.Context, input UpsertInput) error

// Binary format upsert (convenience method)
func (e *EncryptedIndex) UpsertVectors(ctx context.Context, ids []string, vectors [][]float32, metadata []map[string]interface{}) error

​
Parameters (Upsert)

ParameterTypeDescription
ctxcontext.ContextContext for cancellation/timeouts
inputUpsertInputEither VectorItems or BinaryUpsertParams

​
Parameters (UpsertVectors)

ParameterTypeDescription
ctxcontext.ContextContext for cancellation/timeouts
ids[]stringSlice of unique identifiers, one per vector
vectors[][]float32Slice of vector embeddings
metadata[]map[string]interface{}Optional slice of metadata maps (can be nil)
UpsertVectors automatically uses an optimized binary transfer format for better performance with large batches.

​
VectorItem

type VectorItem struct {
    Id       string                 `json:"id"`                 // Unique identifier
    Vector   []float32              `json:"vector,omitempty"`   // Vector data
    Contents internal.NullableContents `json:"contents,omitempty"` // Optional payload (see types reference)
    Metadata map[string]interface{} `json:"metadata,omitempty"` // Optional metadata
}
Contents is a generated nullable wrapper and is not directly constructible from the public package. See the Types reference for the helper-based setter pattern; most Go code leaves it zero-valued.

​
Returns

TypeDescription
errorAny error encountered during the upsert operation

​
Exceptions

  • Throws if the API request fails due to network connectivity issues.
  • Throws if authentication fails (invalid API key).
  • Throws if the encryption key is invalid for the specified index.
  • Throws if there are internal server errors preventing the upsert.
  • Throws detailed validation errors for invalid VectorItem objects.
  • Throws if vector dimensions don’t match the index configuration.
  • Throws if required fields are missing from vector items.
  • Throws if array lengths don’t match in parallel array format.
  • Throws if vector elements are not finite numbers.

​
Example Usage

package main

import (
    "context"
    "encoding/hex"
    "log"
    
    "github.com/cyborginc/cyborgdb-go"
)

func main() {
    // Load existing index
    client, _ := cyborgdb.NewClient("http://localhost:8000", "your-api-key")
    indexKeyHex := "your-64-character-hex-key-here" // 32-byte key encoded as 64 hex chars
    key, err := hex.DecodeString(indexKeyHex)
    if err != nil {
        log.Fatal(err)
    }
    index, _ := client.LoadIndex(context.Background(), "my-documents", key)
    
    // Create vector items
    items := cyborgdb.VectorItems{
        {
            Id:     "doc1",
            Vector: []float32{0.1, 0.2, 0.3, 0.4, 0.5},
        },
        {
            Id:     "doc2",
            Vector: []float32{0.6, 0.7, 0.8, 0.9, 1.0},
        },
    }
    
    // Upsert vectors
    ctx := context.Background()
    err := index.Upsert(ctx, items)
    if err != nil {
        log.Fatal("Upsert failed:", err)
    }
    
    log.Printf("Successfully upserted %d vectors", len(items))
}

​
Upsert with Metadata

func upsertDocuments(index *cyborgdb.EncryptedIndex) error {
    items := cyborgdb.VectorItems{
        {
            Id:     "article_123",
            Vector: []float32{0.1, 0.2, 0.3, 0.4}, // Document embedding
            Metadata: map[string]interface{}{
                "title":     "Go Programming Guide",
                "category":  "programming",
                "author":    "John Doe",
                "published": "2024-01-15",
                "tags":      []string{"golang", "tutorial", "beginner"},
            },
        },
        {
            Id:     "article_124", 
            Vector: []float32{0.5, 0.6, 0.7, 0.8},
            Metadata: map[string]interface{}{
                "title":     "Advanced Go Patterns",
                "category":  "programming", 
                "author":    "Jane Smith",
                "published": "2024-01-20",
                "tags":      []string{"golang", "advanced", "patterns"},
            },
        },
    }
    
    ctx := context.Background()
    return index.Upsert(ctx, items)
}

​
UpsertVectors (Binary Format)

// Efficient bulk upsert using binary transfer
ids := []string{"vec1", "vec2", "vec3"}
vectors := [][]float32{
    {0.1, 0.2, 0.3, 0.4},
    {0.5, 0.6, 0.7, 0.8},
    {0.9, 1.0, 1.1, 1.2},
}

err := index.UpsertVectors(context.Background(), ids, vectors, nil)
if err != nil {
    log.Fatal("UpsertVectors failed:", err)
}