vecx

README

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

Documentation

Index

• type CreateIndexRequest
• type GetIndexResponse
• type Index
  • func NewIndex(name string, token string, url string, version int, params *IndexParams) *Index
  • func (i *Index) DeleteVector(id string) (string, error)
  • func (i *Index) GetInfo() string
  • func (i *Index) GetVector(id string) (VectorItem, error)
  • func (i *Index) Query(vector []float32, k int, filter map[string]interface{}, ef int, ...) ([]QueryResult, error)
  • func (i *Index) String() string
  • func (idx *Index) Upsert(inputArray []VectorItem) error
• type IndexParams
• type ListIndexesResponse
• type QueryRequest
• type QueryResult
• type VectorItem
• type VectorObject
• type VectorX
  • func NewVectorX(token string) *VectorX
  • func (v *VectorX) CreateIndex(name string, dimension int, spaceType string, M int, efCon int, useFp16 bool, ...) error
  • func (v *VectorX) DeleteIndex(name string) error
  • func (v *VectorX) GetIndex(name string) (*Index, error)
  • func (v *VectorX) ListIndexes() ([]interface{}, error)

Types

type CreateIndexRequest

type CreateIndexRequest struct {
	IndexName string `json:"index_name"`
	Dim       int    `json:"dim"`
	SpaceType string `json:"space_type"`
	M         int    `json:"M"`
	EfCon     int    `json:"ef_con"`
	Checksum  int    `json:"checksum"`
	UseFp16   bool   `json:"use_fp16"`
	Version   *int   `json:"version,omitempty"`
}

type GetIndexResponse

type GetIndexResponse struct {
	LibToken      string `json:"lib_token"`
	TotalElements int    `json:"total_elements"`
	SpaceType     string `json:"space_type"`
	Dimension     int    `json:"dimension"`
	UseFp16       bool   `json:"use_fp16"`
	M             int    `json:"M"`
	Checksum      int    `json:"checksum"`
	CreatedAt     int64  `json:"created_at"`
	Name          string `json:"name"`
}

GetIndexResponse represents the response from the /index/{name}/info endpoint

type Index

type Index struct {
	Name      string
	Token     string
	URL       string
	Version   int
	Checksum  int
	LibToken  string
	Count     int
	SpaceType string
	Dimension int
	Precision string
	M         int
	VxLib     interface{} // Placeholder for libvx - will be nil if no key provided
}

Index represents a VectorX index with its properties and configuration

func NewIndex

func NewIndex(name string, token string, url string, version int, params *IndexParams) *Index

NewIndex creates a new Index instance similar to Python's __init__

func (*Index) DeleteVector

func (i *Index) DeleteVector(id string) (string, error)

DeleteVector deletes a vector by ID from the index

func (*Index) GetInfo

func (i *Index) GetInfo() string

GetInfo returns a formatted string with index information for debugging

func (*Index) GetVector

func (i *Index) GetVector(id string) (VectorItem, error)

func (*Index) Query

func (i *Index) Query(vector []float32, k int, filter map[string]interface{}, ef int, includeVectors bool) ([]QueryResult, error)

func (*Index) String

func (i *Index) String() string

String implements the fmt.Stringer interface, equivalent to Python's __str__

func (*Index) Upsert

func (idx *Index) Upsert(inputArray []VectorItem) error

Upsert inserts or updates vectors in the index

type IndexParams

type IndexParams struct {
	LibToken      string `json:"lib_token"`
	TotalElements int    `json:"total_elements"`
	SpaceType     string `json:"space_type"`
	Dimension     int    `json:"dimension"`
	UseFp16       bool   `json:"use_fp16"`
	M             int    `json:"M"`
}

IndexParams represents the parameters passed to create an Index

type ListIndexesResponse

type ListIndexesResponse struct {
	Indexes []interface{} `json:"indixes"`
}

type QueryRequest

type QueryRequest struct {
	Vector         []float32 `json:"vector"`
	K              int       `json:"k"`
	Ef             int       `json:"ef"`
	IncludeVectors bool      `json:"include_vectors"`
	Filter         string    `json:"filter,omitempty"`
}

QueryRequest represents the search request payload

type QueryResult

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"`
	Norm       float32                `json:"norm"`
	Vector     []float32              `json:"vector,omitempty"`
}

QueryResult represents a single search result

type VectorItem

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"`
}

VectorItem represents a vector with metadata for upserting

type VectorObject

type VectorObject struct {
	ID     string    `json:"id"`
	Meta   string    `json:"meta"`
	Filter string    `json:"filter"`
	Norm   float32   `json:"norm"`
	Vector []float32 `json:"vector"`
}

VectorObject represents the internal structure for API submission

type VectorX

type VectorX struct {
	BaseUrl string
	Token   string
	HTTP    *http.Client
}

func NewVectorX

func NewVectorX(token string) *VectorX

func (*VectorX) CreateIndex

func (v *VectorX) CreateIndex(name string, dimension int, spaceType string, M int, efCon int, useFp16 bool, version *int) error

func (*VectorX) DeleteIndex

func (v *VectorX) DeleteIndex(name string) error

func (*VectorX) GetIndex

func (v *VectorX) GetIndex(name string) (*Index, error)

func (*VectorX) ListIndexes

func (v *VectorX) ListIndexes() ([]interface{}, error)