Skip to content

api.md

Latest commit

 

History

History
346 lines (231 loc) · 5.35 KB

api.md

File metadata and controls

346 lines (231 loc) · 5.35 KB
Raw

API Reference

Cache API

NewFastCache

cache := src.NewFastCache()

Creates a basic FastCache instance with default settings.

NewRistrettoCache

cache, err := src.NewRistrettoCache(config *Config) (*RistrettoCache, error)

Creates a Ristretto cache instance with custom configuration.

Config Parameters:

Parameter Type Default Description
MaxCost int64 1GB Maximum memory cost
BufferSize int 512MB Write buffer size
ShardCount int 8 Number of shards
TTL time.Duration 0 Default TTL
MetricsEnabled bool false Enable metrics

Set

cache.Set(key string, value interface{}, cost int64) bool

Sets a value in the cache.

Parameters:

  • key: Cache key
  • value: Value to store
  • cost: Memory cost of this item

Returns: true if successfully set

Get

val := cache.Get(key string) (interface{}, bool)

Gets a value from the cache.

Returns: (value, found)

SetM2One

cache.SetM2One(keys []string, value interface{}, cost int64) bool

Maps multiple keys to a single value. All keys will return the same value.

SetM

cache.SetM(items []CacheItem)

Batch set multiple items.

Del

cache.Del(key string) bool

Deletes a key from the cache.

Wait

cache.Wait()

Waits for all pending writes to complete.

Cost

cost := cache.Cost() int64

Returns the total memory cost of all items in the cache.

Clear

cache.Clear()

Clears all items from the cache.

Vector Store API

NewVectorStore

store, err := src.NewVectorStore(config *VectorStoreConfig) (*VectorCache, error)

Creates a vector store instance.

Config Parameters:

Parameter Type Default Description
IndexType string "flat" Index type: "flat" or "hnsw"
Metric MetricType MetricL2 Distance metric
MaxCost int64 1GB Maximum memory cost
ShardCount int 1 Number of shards
TTL time.Duration 0 Vector TTL
HNSW HNSWConfig default HNSW configuration

Add

err := store.Add(id string, vector Vector, metadata map[string]any) error

Adds a vector to the store.

Parameters:

  • id: Unique identifier
  • vector: Float32 vector
  • metadata: Optional metadata

Get

item, found := store.Get(id string) (*VectorItem, bool)

Retrieves a vector by ID.

Delete

err := store.Delete(id string) error

Deletes a vector by ID.

Search

results, err := store.Search(query Vector, k int) ([]SearchResult, error)

Searches for k nearest vectors.

Returns: Array of SearchResult sorted by distance

SearchWithFilter

results, err := store.SearchWithFilter(query Vector, k int, filter FilterFunc) ([]SearchResult, error)

Searches with metadata filtering.

FilterFunc:

type FilterFunc func(metadata map[string]any) bool

BatchAdd

err := store.BatchAdd(items []VectorItem) error

Batch add multiple vectors.

BatchGet

result := store.BatchGet(ids []string) map[string]*VectorItem

Batch get multiple vectors.

BatchDelete

count := store.BatchDelete(ids []string) int

Batch delete vectors.

ExportToBytes

data, err := store.ExportToBytes() ([]byte, error)

Exports vectors to JSON bytes.

ImportFromBytes

err := store.ImportFromBytes(data []byte) error

Imports vectors from JSON bytes.

Len

count := store.Len() int

Returns the number of vectors.

Cost

cost := store.Cost() int64

Returns current memory cost.

Close

store.Close() error

Closes the vector store.

Vector Types

Vector

type Vector []float32

Represents a vector as a slice of float32 values.

VectorItem

type VectorItem struct {
    ID       string
    Vector   Vector
    Metadata map[string]any
    Cost     int64
}

Represents a stored vector with metadata.

SearchResult

type SearchResult struct {
    ID       string
    Vector   Vector
    Score    float32
    Metadata map[string]any
}

Represents a search result.

MetricType

type MetricType string

const (
    MetricL2     MetricType = "l2"      // Euclidean distance
    MetricCosine MetricType = "cosine"  // Cosine similarity
    MetricIP     MetricType = "ip"       // Inner product
)

Distance Functions

L2Distance

dist := src.L2Distance(v1, v2 Vector) float32

Calculates Euclidean distance.

CosineDistance

dist := src.CosineDistance(v1, v2 Vector) float32

Calculates cosine distance (1 - similarity).

IPDistance

dist := src.IPDistance(v1, v2 Vector) float32

Calculates inner product (returns negative for sorting).

HNSW Configuration

HNSWConfig

type HNSWConfig struct {
    M              int     // Number of connections per node
    EFConstruction int    // Candidate list size during construction
    EFSearch       int    // Candidate list size during search
    LevelMult      float64 // Level multiplier factor
}

Default Configuration:

func DefaultHNSWConfig() HNSWConfig {
    return HNSWConfig{
        M:              16,
        EFConstruction: 200,
        EFSearch:       50,
        LevelMult:      1 / math.Ln2,
    }
}