indexing_explained.md

How Indexing Works in Neighborly

The index service is a crucial background process that maintains the efficiency and performance of the vector database. Here are its key functions:

1. Automatic Index Rebuilding: Rebuilds search indexes when the database is modified.
2. Delayed Rebuilding: Waits for 5 seconds after the last modification before rebuilding, batching changes to avoid unnecessary rebuilds.
3. Tag Rebuilding: Rebuilds the map of tags to vector IDs for efficient lookups.
4. Search Index Rebuilding: Rebuilds KD-Tree and Ball Tree indexes for fast nearest-neighbor searches.
5. Background Operation: Runs on a low-priority thread to avoid interfering with foreground tasks.
6. Continuous Monitoring: Checks for changes every 5 seconds.
7. Telemetry: Tracks rebuild frequency for monitoring.

Code snippet showing the core functionality:

if (_hasOutdatedIndex &&
    _vectors.Count > 0 &&
    DateTime.UtcNow.Subtract(_lastModification).TotalSeconds > timeThresholdSeconds)
{
    await RebuildTagsAsync();
    await RebuildSearchIndexesAsync();
    _indexRebuildCounter.Add(1);
}

Mobile Platform Limitations

The index service is not available on mobile platforms (Android and iOS) due to:

• Power consumption concerns
• Resource constraints
• Platform restrictions on background processes
• Different usage patterns compared to desktop applications

Implications for mobile:

1. Search performance may degrade over time without manual rebuilds.
2. Tag-based operations won't reflect changes automatically.
3. The database might consume more resources due to less optimized structures.

Compensating on Mobile Platforms

To maintain performance on mobile:

1. Implement manual index rebuilding at strategic points:
   • App startup
   • When device is charging and app is in background
   • After significant database modifications
2. Use these methods for manual rebuilding:

   await RebuildTagsAsync();
   await RebuildSearchIndexesAsync();

3. Consider a job queue for rebuild tasks to avoid interfering with user interactions.
4. Monitor rebuild frequency and duration to optimize based on usage patterns.
5. Optionally provide manual controls for advanced users.

By carefully managing these aspects, developers can maintain good performance of the vector database on mobile platforms while working within device constraints.