Skip to content

Semantic Routing

Semantic routing in Quiver enables intelligent distribution of queries across shards based on the semantic meaning of vectors, improving search efficiency and accuracy.

Overview

Semantic routing provides:

  • Intelligent query routing
  • Semantic-aware sharding
  • Improved search performance
  • Reduced query latency
  • Better resource utilization

How It Works

  1. Vector Space Partitioning
  2. The vector space is divided into semantic regions
  3. Each region corresponds to a shard

  4. Routing decisions are based on vector similarity

  5. Dynamic Routing

  6. Queries are routed to relevant shards
  7. Routing decisions are made in real-time
  8. Load balancing is semantically aware

Configuration

Basic Setup

config := quiver.Config{
    // Enable semantic routing
    EnableSemanticRouting: true,
    // Number of semantic regions
    SemanticRegions: 10,
    // Minimum similarity threshold
    RoutingSimilarityThreshold: 0.7,
}

Advanced Configuration

config := quiver.Config{
    EnableSemanticRouting: true,
    SemanticRegions: 10,
    // Advanced routing options
    RoutingOptions: RoutingOptions{
        UpdateInterval: 1 * time.Hour,
        MinRegionSize: 1000,
        MaxRegionSize: 100000,
        AdaptiveThreshold: true,
    },
}

Usage

Basic Routing

// Router automatically handles query distribution
results, err := idx.Search(queryVector, 10, 1, 10)
if err != nil {
    // Handle error
}

Explicit Region Selection

// Search specific semantic regions
options := SearchOptions{
    Regions: []int{1, 3, 5},  // Specific regions to search
    MaxRegions: 3,            // Maximum regions to search
}

results, err := idx.SearchWithOptions(queryVector, 10, options)

Performance Optimization

Region Configuration

// Optimize region configuration
config := quiver.Config{
    // Adjust region count based on data size
    SemanticRegions: calculateOptimalRegions(dataSize),

    // Configure region update frequency
    RegionUpdateInterval: 24 * time.Hour,

    // Set region size limits
    MinRegionSize: 1000,
    MaxRegionSize: 100000,
}

Routing Strategy

// Configure routing strategy
config := quiver.Config{
    RoutingStrategy: RoutingStrategy{
        // Primary routing method
        Primary: "semantic",

        // Fallback strategy
        Fallback: "round-robin",

        // Routing weights
        Weights: map[string]float64{
            "semantic": 0.8,
            "load": 0.2,
        },
    },
}

Monitoring

Routing Metrics

// Get routing metrics
metrics := idx.GetRoutingMetrics()
fmt.Printf("Active regions: %d\n", metrics.ActiveRegions)
fmt.Printf("Average region size: %d\n", metrics.AvgRegionSize)
fmt.Printf("Routing accuracy: %.2f%%\n", metrics.RoutingAccuracy)

Performance Tracking

// Track routing performance
stats := idx.GetRoutingStats()
fmt.Printf("Average routing time: %v\n", stats.AvgRoutingTime)
fmt.Printf("Routing hit rate: %.2f%%\n", stats.HitRate)
fmt.Printf("Cross-region queries: %d\n", stats.CrossRegionQueries)

Best Practices

  1. Region Configuration
  2. Size regions appropriately
  3. Balance region count
  4. Monitor region distribution

  5. Update regions periodically

  6. Performance Tuning

  7. Optimize similarity thresholds
  8. Configure update intervals
  9. Monitor routing accuracy

  10. Adjust based on workload

  11. Monitoring

  12. Track routing metrics
  13. Monitor region balance
  14. Measure query distribution
  15. Analyze routing patterns

Advanced Features

Adaptive Routing

// Configure adaptive routing
config := quiver.Config{
    EnableAdaptiveRouting: true,
    AdaptiveOptions: AdaptiveOptions{
        // Learning rate for adaptation
        LearningRate: 0.1,
        // Minimum samples before adaptation
        MinSamples: 1000,
        // Update frequency
        UpdateInterval: 1 * time.Hour,
    },
}

Custom Routing Rules

// Define custom routing rules
rules := []RoutingRule{
    {
        // Route based on vector properties
        Condition: func(v []float32) bool {
            return calculateDensity(v) > 0.5
        },
        TargetRegions: []int{1, 2, 3},
    },
}

config.RoutingRules = rules

Error Handling

// Handle routing errors
results, err := idx.Search(queryVector, 10, 1, 10)
if err != nil {
    switch {
    case errors.Is(err, ErrNoRegionsAvailable):
        // Handle no available regions
    case errors.Is(err, ErrRoutingFailed):
        // Handle routing failure
    default:
        // Handle other errors
    }
}

Next Steps