VectorX Go Client

A Go client library for VectorX, a high-performance vector database optimized for similarity search and retrieval-augmented generation (RAG) applications.

Features

• 🚀 High Performance: Optimized for large-scale vector operations
• 🔍 Multiple Distance Metrics: Support for cosine, L2, and inner product similarity
• 📊 High Dimensionality: Support for vectors up to 10,000 dimensions
• 🏷️ Metadata & Filtering: Rich metadata support with JSON-based filtering
• 🔒 Security Ready: Built-in support for encryption (coming soon)
• ⚡ Batch Operations: Efficient batch upsert of up to 1,000 vectors
• 🎯 Precision Control: FP16 and FP32 precision support
• 🌐 Cloud & Local: Support for both VectorX Cloud and self-hosted instances

Installation

go get github.com/LaunchX-Labs/vecx-go

Quick Start

package main

import (
    "fmt"
    "log"
    "github.com/LaunchX-Labs/vecx-go"
)

func main() {
    // Initialize client with your VectorX token
    client := vecx.NewVectorX("your-token-here")
    
    // Create a new index
    err := client.CreateIndex("my-index", 768, "cosine", 16, 128, false, nil)
    if err != nil {
        log.Fatal(err)
    }
    
    // Get the index for operations
    index, err := client.GetIndex("my-index")
    if err != nil {
        log.Fatal(err)
    }
    
    // Upsert some vectors
    vectors := []vecx.VectorItem{
        {
            ID:     "doc1",
            Vector: make([]float32, 768), // Your 768-dimensional vector
            Meta: map[string]interface{}{
                "title":    "My Document",
                "category": "technology",
            },
        },
    }
    
    err = index.Upsert(vectors)
    if err != nil {
        log.Fatal(err)
    }
    
    // Search for similar vectors
    queryVector := make([]float32, 768) // Your query vector
    results, err := index.Query(queryVector, 10, nil, 128, false)
    if err != nil {
        log.Fatal(err)
    }
    
    for _, result := range results {
        fmt.Printf("ID: %s, Similarity: %.3f\n", result.ID, result.Similarity)
    }
}

Authentication

Local Development

For local development, simply initialize without a token:

client := vecx.NewVectorX("")

VectorX Cloud

For VectorX Cloud, use your provided token:

client := vecx.NewVectorX("account:api-key:region")

The client automatically detects cloud tokens and configures the appropriate endpoint.

API Reference

Client Operations

NewVectorX(token string) *VectorX

Creates a new VectorX client instance.

CreateIndex(name, dimension, spaceType, M, efCon, useFp16, version) error

Creates a new vector index.

Parameters:

• name (string): Index name (alphanumeric + underscores, <48 chars)
• dimension (int): Vector dimension (1-10,000)
• spaceType (string): Distance metric ("cosine", "l2", "ip")
• M (int): HNSW algorithm parameter for connectivity
• efCon (int): HNSW construction parameter
• useFp16 (bool): Use 16-bit floating point precision
• version (*int): Optional version number

Example:

err := client.CreateIndex("embeddings", 1536, "cosine", 16, 128, false, nil)

ListIndexes() ([]interface{}, error)

Lists all available indexes.

GetIndex(name string) (*Index, error)

Retrieves an index instance for operations.

DeleteIndex(name string) error

Deletes an index and all its data.

Index Operations

Upsert(vectors []VectorItem) error

Inserts or updates vectors in the index (max 1,000 vectors per batch).

VectorItem Structure:

type VectorItem struct {
    ID     string                 `json:"id"`
    Vector []float32              `json:"vector"`
    Meta   map[string]interface{} `json:"meta,omitempty"`
    Filter map[string]interface{} `json:"filter,omitempty"`
}

Query(vector, k, filter, ef, includeVectors) ([]QueryResult, error)

Searches for similar vectors.

Parameters:

• vector ([]float32): Query vector
• k (int): Number of results to return (max 256)
• filter (map[string]interface{}): Optional metadata filter
• ef (int): Search quality parameter (max 1,024)
• includeVectors (bool): Include vector data in results

Returns:

type QueryResult struct {
    ID         string                 `json:"id"`
    Similarity float32               `json:"similarity"`
    Distance   float32               `json:"distance"`
    Meta       map[string]interface{} `json:"meta"`
    Filter     map[string]interface{} `json:"filter,omitempty"`
    Vector     []float32             `json:"vector,omitempty"`
}

GetVector(id string) (VectorItem, error)

Retrieves a specific vector by ID.

DeleteVector(id string) (string, error)

Deletes a vector by ID.

Examples

Basic Vector Operations

package main

import (
    "fmt"
    "log"
    "github.com/LaunchX-Labs/vecx-go"
)

func main() {
    client := vecx.NewVectorX("your-token")
    
    // Create index
    err := client.CreateIndex("documents", 384, "cosine", 16, 128, false, nil)
    if err != nil {
        log.Fatal(err)
    }
    
    index, err := client.GetIndex("documents")
    if err != nil {
        log.Fatal(err)
    }
    
    // Prepare sample data
    documents := []vecx.VectorItem{
        {
            ID:     "doc_1",
            Vector: generateEmbedding("The quick brown fox jumps"),
            Meta: map[string]interface{}{
                "title":     "Sample Document 1",
                "author":    "John Doe",
                "timestamp": "2024-01-15",
            },
            Filter: map[string]interface{}{
                "category": "animals",
                "public":   true,
            },
        },
        {
            ID:     "doc_2", 
            Vector: generateEmbedding("Machine learning advances"),
            Meta: map[string]interface{}{
                "title":     "ML Research Paper",
                "author":    "Jane Smith",
                "timestamp": "2024-01-16",
            },
            Filter: map[string]interface{}{
                "category": "technology",
                "public":   false,
            },
        },
    }
    
    // Upsert documents
    err = index.Upsert(documents)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Println("Documents uploaded successfully!")
}

func generateEmbedding(text string) []float32 {
    // This is a placeholder - use your actual embedding model
    embedding := make([]float32, 384)
    for i := range embedding {
        embedding[i] = float32(len(text)) * 0.01 * float32(i)
    }
    return embedding
}

Semantic Search with Filtering

func searchDocuments(index *vecx.Index, queryText string) {
    // Generate query embedding
    queryVector := generateEmbedding(queryText)
    
    // Search without filters
    results, err := index.Query(queryVector, 5, nil, 128, false)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Found %d results for '%s':\n", len(results), queryText)
    for i, result := range results {
        fmt.Printf("%d. %s (similarity: %.3f)\n", 
            i+1, result.Meta["title"], result.Similarity)
    }
    
    // Search with category filter
    filter := map[string]interface{}{
        "category": "technology",
        "public":   true,
    }
    
    filteredResults, err := index.Query(queryVector, 5, filter, 128, false)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("\nFiltered results (%d):\n", len(filteredResults))
    for i, result := range filteredResults {
        fmt.Printf("%d. %s\n", i+1, result.Meta["title"])
    }
}

Advanced Index Management

func manageIndexes(client *vecx.VectorX) {
    // List all indexes
    indexes, err := client.ListIndexes()
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Current indexes (%d):\n", len(indexes))
    for i, idx := range indexes {
        fmt.Printf("%d. %+v\n", i+1, idx)
    }
    
    // Create high-precision index
    err = client.CreateIndex("high-precision", 1536, "cosine", 32, 256, true, nil)
    if err != nil {
        log.Printf("Create failed: %v", err)
    }
    
    // Get index info
    index, err := client.GetIndex("high-precision")
    if err == nil {
        fmt.Printf("Index info: %s\n", index.GetInfo())
    }
    
    // Clean up
    err = client.DeleteIndex("high-precision")
    if err != nil {
        log.Printf("Delete failed: %v", err)
    }
}

Distance Metrics

Cosine Similarity

Best for normalized vectors and semantic similarity:

client.CreateIndex("semantic", 768, "cosine", 16, 128, false, nil)

L2 (Euclidean) Distance

Best for spatial data and exact matches:

client.CreateIndex("spatial", 512, "l2", 16, 128, false, nil)

Inner Product

Best for recommendation systems:

client.CreateIndex("recommendations", 256, "ip", 16, 128, false, nil)

Performance Optimization

Index Parameters

• M: Controls recall vs memory usage (16-64 recommended)
• ef_con: Build-time search quality (128-512 recommended)
• ef: Query-time search quality (k to 512 recommended)

Best Practices

1. Batch Operations: Use batch upsert for better performance
2. Dimension Choice: Higher dimensions = better accuracy but slower queries
3. Precision: Use FP16 for memory savings if precision allows
4. Filter Strategy: Apply filters judiciously to maintain performance

Error Handling

// Handle common errors
err := client.CreateIndex("test", 768, "cosine", 16, 128, false, nil)
if err != nil {
    switch {
    case strings.Contains(err.Error(), "already exists"):
        fmt.Println("Index already exists, continuing...")
    case strings.Contains(err.Error(), "invalid index name"):
        fmt.Println("Invalid index name format")
    case strings.Contains(err.Error(), "dimension cannot be greater"):
        fmt.Println("Dimension too large")
    default:
        log.Fatal("Unexpected error:", err)
    }
}

Requirements

• Go 1.24.5 or later

Dependencies

• github.com/vmihailenco/msgpack/v5 - Efficient binary serialization