Search & Indexing - Version Mapping
Domain: Search & Indexing Domain Number: 11 First Introduced: V1.2 Status: Specification Complete Last Updated: 2025-10-25
Overview
This document maps Search & Indexing domain features and entities to specific MVP and version releases. It provides a quick reference for understanding when search capabilities were introduced and the evolution from basic text search to advanced faceted discovery.
Version Timeline
| Version | Status | Key Features |
|---|---|---|
| MVP.0 | OUT OF SCOPE | Search deferred to post-launch |
| MVP.1 | OUT OF SCOPE | Still deferred |
| MVP.2 | OUT OF SCOPE | Still deferred |
| V1.2 | Planned | Full-text search with PostgreSQL FTS |
| V2.0 | Future | Faceted search, geospatial queries, Elasticsearch |
| V2.1 | Future | Personalized search, recommendations |
| V2.2 | Future | Vector search, semantic embeddings |
Entity Version Mapping
MVP.0-MVP.2 Entities
| Entity | Status | Rationale |
|---|---|---|
| ALL | ❌ Deferred | MVP supports direct listing URLs; manual curation replaces search |
V1.2 Entities
| Entity | Table Name | Purpose | Status |
|---|---|---|---|
| SearchIndex | search_indexes | Denormalized search records | ✅ Planned |
| DiscoveryIndex | discovery_indexes | Availability and pricing snapshots | ✅ Planned |
| SearchQuery | search_queries | Query logs for analytics | ✅ Planned |
V2.0 Entities
| Entity | Table Name | Purpose | Status |
|---|---|---|---|
| SearchSynonym | search_synonyms | Query expansion rules | 📋 Future |
| Facet | facets | Filterable dimension definitions | 📋 Future |
| SearchIndexQueue | search_index_queue | Prioritized reindex jobs | 📋 Future |
V2.1 Entities
| Entity | Table Name | Purpose | Status |
|---|---|---|---|
| UserPreference | user_preferences | Search behavior tracking | 📋 Future |
| SavedSearch | saved_searches | User-saved queries and alerts | 📋 Future |
V2.2 Entities
| Entity | Table Name | Purpose | Status |
|---|---|---|---|
| SearchEmbedding | search_embeddings | Vector representations for semantic search | 📋 Future |
Feature Version Mapping
MVP.0-MVP.2 Features (OUT OF SCOPE)
Status: ❌ Entire domain deferred
Rationale:
- Initial launch uses direct listing URLs
- Admin panel lists all properties
- Manual curation by TVL team
- Reduces MVP complexity and database load
- Limited inventory (< 50 properties) doesn't require search
Workarounds:
- Admin dashboard shows all listings
- Shared links via direct Space URLs
- Manual recommendations by TVL team
- Simple filtering in admin panel (status, region)
V1.2 Features (Initial Search Implementation)
Full-Text Search:
- ✅ PostgreSQL FTS using tsvector and GIN indexes
- ✅ Text search on name, headline, description
- ✅ Multi-language stemming support (English primary)
- ✅ Simple relevance ranking
Basic Filters:
- ✅ Country and region filtering
- ✅ Price range (min/max)
- ✅ Bedrooms, bathrooms, capacity
- ✅ Tag-based filtering (Oceanfront, Private Chef, etc.)
- ✅ Amenity filtering (pool, wifi, parking)
- ✅ Property type (villa, apartment, house)
Indexing Strategy:
- ✅ Event-driven reindexing from domain events
- ✅ Nightly batch sync for availability
- ✅ Incremental price updates
- ✅ Change detection via source_version tracking
- ✅ Index freshness monitoring
Query Capabilities:
- ✅ Simple text search
- ✅ Filter combination (AND logic)
- ✅ Sort by price, capacity, relevance, featured
- ✅ Pagination support
- ✅ Result count aggregation
Observability:
- ✅ Query logging to search_queries table
- ✅ Latency tracking
- ✅ Zero-result query identification
- ✅ Click tracking (which results users select)
- ✅ Conversion tracking (search → booking)
Performance:
- ✅ P50 latency < 100ms
- ✅ P95 latency < 200ms
- ✅ Index lag < 5 seconds for critical updates
- ✅ Support for 1,000+ active listings
Use Cases Enabled:
- ✅ Public website search
- ✅ Partner API search endpoints
- ✅ Admin panel advanced filtering
- ✅ Basic discovery workflows
V2.0 Features (Advanced Search)
Geospatial Search:
- 📋 Radius-based queries ("within 10km")
- 📋 Polygon boundary searches
- 📋 Geohash indexing
- 📋 PostGIS or Elasticsearch geo queries
- 📋 Map-based search UI
Faceted Filtering:
- 📋 Pre-computed facet counts
- 📋 Facet values scoped to current filters
- 📋 Multi-select facets with AND/OR logic
- 📋 Numeric range sliders
- 📋 Dynamic facet generation
Advanced Text Search:
- 📋 Multi-language stemming
- 📋 Phrase matching
- 📋 Proximity search
- 📋 Boosted fields (name > headline > description)
- 📋 Fuzzy matching for typo tolerance
Search Relevance:
- 📋 Configurable field weights
- 📋 Freshness boosting
- 📋 Quality signals (booking rate, reviews)
- 📋 Featured listing promotion
- 📋 A/B testing framework
Synonym Management:
- 📋 search_synonyms table
- 📋 Admin UI for synonym editing
- 📋 Bidirectional synonym mapping
- 📋 Language-specific synonyms
Real-Time Availability:
- 📋 Per-day availability pricing in DiscoveryIndex
- 📋 Instant calendar-aware search
- 📋 Blocking rule awareness (min/max stay)
- 📋 Check-in day filtering
Elasticsearch Migration:
- 📋 Full index rebuild with ES schema
- 📋 Dual-write strategy during migration
- 📋 A/B testing PostgreSQL vs. Elasticsearch
- 📋 Rollback plan if issues detected
Performance:
- 📋 P95 latency < 150ms (with facets)
- 📋 Support 10,000+ active listings
- 📋 Real-time index updates (< 1 second lag)
V2.1 Features (Personalization)
User Preferences:
- 📋 Past search and booking tracking
- 📋 Behavioral ranking adjustments
- 📋 Saved searches and alerts
- 📋 "More like this" recommendations
Collaborative Filtering:
- 📋 "Users who viewed this also booked..."
- 📋 Similar listing discovery
- 📋 Personalized result ordering
V2.2 Features (Semantic Search)
Vector Search:
- 📋 Semantic search using embeddings
- 📋 Natural language query parsing
- 📋 Image similarity search
- 📋 AI-generated search suggestions
Workflow Version Mapping
| Workflow | MVP.0-MVP.2 | V1.2 | V2.0 | V2.1 | V2.2 |
|---|---|---|---|---|---|
| Reindex Space | ❌ | ✅ Event-driven | ✅ | ✅ | ✅ Embeddings |
| Execute Search Query | ❌ | ✅ Basic filters | ✅ Faceted | ✅ Personalized | ✅ Semantic |
| Nightly Availability Sync | ❌ | ✅ | ✅ Real-time | ✅ | ✅ |
| Query Expansion | ❌ | ❌ | ✅ Synonyms | ✅ | ✅ AI-driven |
| Geospatial Search | ❌ | ❌ | ✅ | ✅ | ✅ |
Dependency Version Mapping
V1.2 Dependencies
Required Domains:
- ✅ Supply (MVP.0) - Space and Unit entities
- ✅ Content & Metadata (MVP.0) - Descriptions, amenities, attributes
- ✅ Pricing (MVP.0) - Price ranges
- ✅ Availability (MVP.0) - Calendar data
- ✅ Identity & Tenancy (MVP.0) - Org/Account scoping
Depended On By:
- 🔄 Channels (MVP.0) - Search results for partner feeds
- 🔄 Analytics (MVP.0) - Query logs for behavioral analytics
Related:
- ✅ System Architecture (V1.0) - Index storage technology choices
Technical Implementation Timeline
V1.2 Implementation
Database:
- ✅ 3 tables: search_indexes, discovery_indexes, search_queries
- ✅ 12+ indexes (GIN, GIST, B-tree)
- ✅ PostgreSQL FTS configuration
- ✅ JSONB for flexible attributes
Search Backend:
- ✅ PostgreSQL full-text search (tsvector)
- ✅ GIN indexes for text and array columns
- ✅ GIST indexes for geospatial (preparation for V2.0)
- ✅ JSONB operators for attribute filtering
API Endpoints:
- ✅ GET /api/search - Execute search with filters
- ✅ GET /api/search/facets - Get available facet values
- ✅ POST /admin/search/reindex - Trigger manual reindex
Background Jobs:
- ✅ Event-driven reindex worker (subscribes to domain events)
- ✅ Nightly availability sync batch job
- ✅ Weekly index verification job (detect drift)
- ✅ Monthly full reindex (schema evolution)
Event Subscriptions:
- ✅ space.updated → reindex Space
- ✅ pricing.changed → update price_min/price_max
- ✅ availability.blocked → trigger availability sync
- ✅ content.published → reindex descriptions
Monitoring:
- ✅ Reindex queue depth and lag
- ✅ Failed reindex job alerts
- ✅ Index freshness per Space
- ✅ Dashboard: avg index age, reindex throughput
V2.0 Implementation
Database:
- 📋 3 new tables: search_synonyms, facets, search_index_queue
- 📋 Additional geospatial indexes (PostGIS or Elasticsearch)
Search Backend:
- 📋 Elasticsearch cluster deployment
- 📋 Dual-write to PostgreSQL and Elasticsearch
- 📋 A/B testing framework
Caching:
- 📋 Redis cache for popular searches (TTL: 5 min)
- 📋 Facet count caching
- 📋 Geo-boundary query caching
Business Rules by Version
V1.2 Rules
- ✅ Index Freshness: Updates complete within 5s of source change (P95)
- ✅ Availability Window: DiscoveryIndex tracks next 180 days
- ✅ Tenant Isolation: All queries filtered by authorized org_id/account_id
- ✅ Public vs. Private: Only status='active' Spaces in public search
- ✅ Result Limits: Max 1000 results per query
- ✅ Query Timeout: 2-second timeout, partial results on overflow
- ✅ Reindex Priority: Price/availability < 1 min; content < 5 min
- ✅ Zero Results Logging: All zero-result queries logged
V2.0 Rules
- 📋 Facet Limits: Max 100 unique values per facet shown
- 📋 Synonym Precedence: Org-specific override global
- 📋 Geospatial Precision: 6 decimal places (±0.11m accuracy)
Performance Targets by Version
V1.2 Targets
| Metric | Target | Measurement |
|---|---|---|
| P50 search latency | < 100ms | Median query execution |
| P95 search latency | < 200ms | 95th percentile |
| Index lag (critical) | < 5s | Price/availability changes |
| Index lag (content) | < 5min | Description updates |
| Reindex throughput | > 100 spaces/sec | Batch reindex performance |
| Query result accuracy | > 95% | Relevant results in top 10 |
| Zero-result rate | < 5% | Queries with 0 results |
V2.0 Targets
| Metric | Target | Status |
|---|---|---|
| P95 latency (with facets) | < 150ms | 📋 Including aggregations |
| Supported listings | 10,000+ | 📋 Scale target |
| Real-time index lag | < 1s | 📋 Elasticsearch sync |
| Geospatial query latency | < 100ms | 📋 Radius search |
Migration Notes
From MVP.2 to V1.2
New Capabilities:
- Full-text search infrastructure
- Event-driven indexing
- Query analytics
Breaking Changes:
- None (greenfield feature)
Migration Steps:
- Deploy search domain schema (3 tables)
- Create GIN and GIST indexes (may take time for large datasets)
- Perform initial full reindex of all active Spaces
- Enable event subscriptions for incremental updates
- Configure nightly availability sync job
- Deploy search API endpoints
- Integrate search into frontend applications
- Set up monitoring dashboards
Performance Considerations:
- Initial full reindex may take 10-30 minutes for 1000 spaces
- Plan reindex during low-traffic period
- Monitor database CPU and I/O during reindex
Data Validation:
- Verify all active Spaces have corresponding search_indexes records
- Check index freshness (last_indexed_at within expected range)
- Test query performance with realistic filters
- Validate result counts match expectations
From V1.2 to V2.0
New Capabilities:
- Faceted search
- Geospatial queries
- Synonym management
- Optional Elasticsearch backend
Breaking Changes:
- None (additive only)
Migration Steps (PostgreSQL-only path):
- Deploy new tables: search_synonyms, facets, search_index_queue
- Backfill facet definitions
- Seed common synonyms
- Enable geospatial queries (PostGIS extension)
- Update API endpoints with facet support
Migration Steps (Elasticsearch path):
- Deploy Elasticsearch cluster
- Create index mapping (schema)
- Enable dual-write (PostgreSQL + Elasticsearch)
- Perform full reindex to Elasticsearch
- A/B test query performance
- Gradual traffic shift to Elasticsearch
- Keep PostgreSQL as fallback
Related Documents
- Search & Indexing Specification - Complete domain spec
- Supply Specification - Source data for indexing
- Content & Metadata Specification - Descriptions and attributes
- Availability Specification - Calendar data
- Pricing Specification - Rate data
- System Architecture Specification - Technology choices
- V1.2 Product Vision
- V2.0 Roadmap
Glossary
- SearchIndex: Denormalized, query-optimized Space representation
- DiscoveryIndex: Availability and pricing snapshot for advanced filtering
- SearchQuery: Log of executed search for analytics
- Facet: Filterable dimension (country, bedrooms, amenities)
- Full-Text Search (FTS): Text matching using tsvector and GIN indexes
- GIN Index: Generalized Inverted Index for array and full-text columns
- GIST Index: Generalized Search Tree for geospatial and range queries
- Geohash: Hierarchical spatial encoding for location indexing
- Query Expansion: Adding synonyms and related terms to improve recall
- Reindex: Rebuilding search record from authoritative source data
- Index Lag: Time between source data change and search index update
- Zero-Result Query: Search query returning no matching listings