immish/docs/search.md

Search

This document describes the search functionality, including smart search, filters, and discovery features.

Search Overview

The search feature allows users to find assets using:

• AI-powered semantic search (CLIP)
• Text-based search (filename, description, OCR)
• Filter-based search (people, location, camera, date, type)

Search Screen Layout

┌─────────────────────────────────────────────────────────────┐
│  ←  [  Search photos and videos...        🔍 ]    [ ⋮ ]    │
├─────────────────────────────────────────────────────────────┤
│  [People] [Location] [Camera] [Date] [Type] [Display] →    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│                    Search Results                           │
│                         or                                  │
│                    Empty State                              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Search Types

1. Context Search (AI/CLIP)

• Default search mode
• Uses AI to understand image content
• Finds visually similar results

Examples:

• "sunset on the beach"
• "birthday cake"
• "dog playing in park"
• "red car"

2. Filename Search

• Searches asset filenames
• Partial matching supported

Examples:

• "IMG_2024"
• "screenshot"
• ".png"

3. Description Search

• Searches asset descriptions/captions
• User-added metadata

4. OCR Search

• Searches text detected in images
• Useful for documents, signs, receipts

Examples:

• "receipt"
• "invoice"
• Specific text in images

Search API

Main Search Endpoint

POST /search/smart

Body:
{
  "query": "sunset beach",
  "page": 1,
  "size": 100,
  "type": "IMAGE" | "VIDEO" | null,
  "isFavorite": true | false | null,
  "isArchived": true | false | null,
  "takenAfter": "2024-01-01T00:00:00Z",
  "takenBefore": "2024-12-31T23:59:59Z",
  "city": "San Francisco",
  "state": "California",
  "country": "United States",
  "make": "Apple",
  "model": "iPhone 15 Pro",
  "personIds": ["person-uuid-1", "person-uuid-2"],
  "language": "en-US"
}

Response:
{
  "assets": {
    "items": [...],
    "nextPage": "2"
  }
}

Search Suggestions

GET /search/suggestions?type={type}&country={country}&state={state}&make={make}&model={model}

Types: country, state, city, cameraMake, cameraModel

Filter Chips

People Filter

┌─────────────────────────────────────────────────────────────┐
│  People                                                 X   │
├─────────────────────────────────────────────────────────────┤
│  Search people...                                           │
├─────────────────────────────────────────────────────────────┤
│  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐              │
│  │ 👤  │  │ 👤  │  │ 👤  │  │ 👤  │  │ 👤  │              │
│  │     │  │     │  │     │  │     │  │     │              │
│  │John │  │Jane │  │Bob  │  │Alice│  │No   │              │
│  │  ✓  │  │     │  │     │  │  ✓  │  │Name │              │
│  └─────┘  └─────┘  └─────┘  └─────┘  └─────┘              │
│                                                             │
│  [Clear]                                    [Search]        │
└─────────────────────────────────────────────────────────────┘

Location Filter

┌─────────────────────────────────────────────────────────────┐
│  Location                                               X   │
├─────────────────────────────────────────────────────────────┤
│  Country                                                    │
│  [Select country...                               ▼]       │
│                                                             │
│  State                                                      │
│  [Select state...                                 ▼]       │
│                                                             │
│  City                                                       │
│  [Select city...                                  ▼]       │
│                                                             │
│  [Clear]                                    [Search]        │
└─────────────────────────────────────────────────────────────┘

Camera Filter

┌─────────────────────────────────────────────────────────────┐
│  Camera                                                 X   │
├─────────────────────────────────────────────────────────────┤
│  Make                                                       │
│  [Select camera make...                           ▼]       │
│                                                             │
│  Model                                                      │
│  [Select camera model...                          ▼]       │
│                                                             │
│  [Clear]                                    [Search]        │
└─────────────────────────────────────────────────────────────┘

Date Filter

Uses native date range picker:

• Start date
• End date
• Presets: Today, This Week, This Month, This Year

Media Type Filter

┌─────────────────────────────────────────────────────────────┐
│  Media Type                                             X   │
├─────────────────────────────────────────────────────────────┤
│  ○ All                                                      │
│  ○ Images only                                              │
│  ○ Videos only                                              │
│                                                             │
│  [Clear]                                    [Search]        │
└─────────────────────────────────────────────────────────────┘

Display Options Filter

┌─────────────────────────────────────────────────────────────┐
│  Display Options                                        X   │
├─────────────────────────────────────────────────────────────┤
│  ☐ Not in any album                                         │
│  ☐ Archived only                                            │
│  ☐ Favorites only                                           │
│                                                             │
│  [Clear]                                    [Search]        │
└─────────────────────────────────────────────────────────────┘

Search Filter Model

SearchFilter {
  // Text search
  context: String?      // AI search query
  filename: String?     // Filename search
  description: String?  // Description search
  ocr: String?          // OCR text search

  // Filters
  people: Set<Person>   // Selected people
  location: LocationFilter {
    country: String?
    state: String?
    city: String?
  }
  camera: CameraFilter {
    make: String?
    model: String?
  }
  date: DateFilter {
    takenAfter: DateTime?
    takenBefore: DateTime?
  }
  mediaType: AssetType  // image, video, or other (all)
  display: DisplayFilter {
    isNotInAlbum: Boolean
    isArchive: Boolean
    isFavorite: Boolean
  }
  rating: RatingFilter  // If rating feature enabled
  language: String      // For AI search localization
  assetId: String?      // Search for specific asset by ID
  tagIds: List<String>? // Filter by tag IDs
}

Quick Links (Empty State)

When search is empty, show quick access links:

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│                      [Polaroid Image]                       │
│                                                             │
│               Search photos and videos                      │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐   │
│  │  🕐  Recently Taken                                  │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │  ▶️  Videos                                          │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │  ♥️  Favorites                                       │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Explore Data

Explore API

GET /search/explore

Response:
[
  {
    "fieldName": "exifInfo.city",
    "items": [
      {
        "value": "San Francisco",
        "data": { asset preview data }
      }
    ]
  },
  {
    "fieldName": "smartInfo.objects",
    "items": [...]
  }
]

Places / Map View

Get Assets by City

GET /search/cities

Response: Array of assets grouped by city

Map Display

• Shows assets as markers on map
• Cluster markers for dense areas
• Tap cluster to zoom or view assets
• Filter by favorites, date range, partners

People Search

Get All People

GET /people

Response:
[
  {
    "id": "person-uuid",
    "name": "John Doe",
    "birthDate": "1990-01-15",
    "thumbnailPath": "/path/to/thumb",
    "isHidden": false
  }
]

Person Detail

GET /people/{id}

Response:
{
  "id": "person-uuid",
  "name": "John Doe",
  "birthDate": "1990-01-15",
  "thumbnailPath": "/path/to/thumb",
  "assets": [...]
}

Pagination

• Search results are paginated
• Initial page: 1
• Load more on scroll to bottom
• nextPage in response indicates more results

Search Result Actions

Same as timeline multi-select:

• Add to album
• Favorite
• Archive
• Delete
• Share
• Download

Performance Considerations

1. Debounced input: Wait for user to stop typing
2. Cached suggestions: Store frequently used
3. Incremental loading: Paginate results
4. Cancel previous: Cancel outdated requests

---

Previous: Timeline & Photos | Next: Albums