The Search System provides multi-faceted search capabilities across Immich's asset library, supporting metadata-based queries, semantic search via CLIP embeddings, OCR text extraction, and various filtering criteria. This system enables users to find photos and videos through traditional metadata filters (date, location, camera, people, tags) as well as natural language queries powered by machine learning.
For information about the ML-based features that power smart search and face detection, see Machine Learning Service. For asset metadata extraction that populates searchable fields, see Metadata Extraction.
The search system operates across three layers: client interfaces (web and mobile), API endpoints, and backend search services. Both clients communicate with the same search API but implement different user experiences optimized for their respective platforms.
Sources:
Immich supports multiple search modalities that can be used independently or combined for powerful queries.
Metadata search queries asset properties extracted during upload and processing. This includes EXIF data, file information, and user-assigned metadata. The SearchRepository.searchMetadata method handles these queries server/src/repositories/search.repository.ts196-205
Searchable Fields:
takenAfter, takenBefore, createdAfter, createdBefore, updatedAfter, updatedBefore, trashedAfter, trashedBefore (date ranges) server/src/repositories/search.repository.ts48-57city, state, country (from GPS coordinates) server/src/repositories/search.repository.ts68-70make, model, lensModel (EXIF data) server/src/repositories/search.repository.ts71-72originalFileName, type (IMAGE/VIDEO), checksum, originalPath, previewPath, thumbnailPath, encodedVideoPath server/src/repositories/search.repository.ts60-65isFavorite, isNotInAlbum, visibility (archive status), isEncoded, isMotion, isOffline server/src/repositories/search.repository.ts26-35personIds (face recognition) server/src/repositories/search.repository.ts88-89tagIds (user-assigned tags) server/src/repositories/search.repository.ts91-92Smart search uses CLIP (Contrastive Language-Image Pre-training) embeddings to enable natural language queries like "sunset on the beach" or "birthday cake". This feature requires the machine learning service to be enabled. The SearchService.searchSmart method orchestrates this server/src/services/search.service.ts121-162
How it works:
smart_search table and the embedding column server/src/queries/search.repository.sql75-98<=> operator in PostgreSQL).Query Types:
query: Natural language text (e.g., "dog playing in park") server/src/dtos/search.dto.ts86queryAssetId: Find similar images to a reference asset server/src/dtos/search.dto.ts87OCR (Optical Character Recognition) search indexes text found within images, enabling queries for text content like signs, documents, or screenshots. The ocr field in search DTOs is used for this server/src/dtos/search.dto.ts49
Implementation:
asset_exif.ocrText column.asset_exif.ocrText for full-text search.Sources:
The web search interface is implemented as a route page that accepts search parameters via URL query strings, enabling deep linking and browser history integration.
Search queries are encoded as JSON in the URL's query parameter. The SearchFilterModal.svelte component constructs the search payload based on user input web/src/lib/modals/SearchFilterModal.svelte134-156
Search results are displayed using GalleryViewer, which provides:
Key Implementation:
Sources:
The mobile search interface uses a filter-based approach with dedicated pickers for each search criterion, managed through Riverpod state providers.
The SearchFilter class encapsulates all search criteria web/src/lib/types.ts100-124
| Property | Type | Description |
|---|---|---|
query | string | Smart search text query, OCR, filename, description, or full path |
ocr | string | OCR text content |
queryType | QueryType | Type of text query (smart, ocr, metadata, description, fullPath) |
queryAssetId | string | Reference asset for similarity |
personIds | SvelteSet<string> | Selected people/faces |
tagIds | SvelteSet<string> | null | Selected tag IDs |
location | { country?: string | null; state?: string | null; city?: string | null; } | City, state, country |
camera | { make?: string | null; model?: string | null; lensModel?: string | null; } | Make, model, lens |
date | { takenAfter?: DateTime; takenBefore?: DateTime; } | Start and end dates |
display | { isArchive: boolean; isFavorite: boolean; isNotInAlbum: boolean; } | Favorite, archive, not in album flags |
mediaType | MediaType | IMAGE, VIDEO, or All |
rating | number | undefined | Star rating filter |
The paginatedSearchProvider manages search results with automatic pagination:
State Management:
Key Methods:
Sources:
Both web and mobile clients communicate with the same backend search endpoints through generated API clients.
The SearchController defines the API endpoints for search operations server/src/controllers/search.controller.ts1-160
| Endpoint | Method | Purpose |
|---|---|---|
/search/metadata | POST | Metadata-based search |
/search/smart | POST | CLIP semantic search |
/search/person | GET | Search people/faces by name |
/search/places | GET | Search places by name |
/search/suggestions | GET | Search suggestions for various metadata fields |
/search/explore | GET | Retrieve data for the explore section |
/search/cities | GET | Retrieve assets by city |
/search/statistics | GET | Get search statistics |
/search/random | GET | Get random assets |
/search/large | GET | Get large assets |
Metadata Search Request (MetadataSearchDto):
This DTO defines the parameters for metadata-based searches mobile/openapi/lib/model/metadata_search_dto.dart1-30824
Smart Search Request (SmartSearchDto):
This DTO defines the parameters for smart searches mobile/openapi/lib/model/smart_search_dto.dart1-24017
Response Structure (SearchResponseDto):
The response for metadata and smart searches includes paginated assets and albums.
The SearchApi class in the mobile OpenAPI client wraps API calls with error handling and type conversions mobile/openapi/lib/api/search_api.dart1-27254
Key Methods:
searchMetadata(MetadataSearchDto dto): Performs metadata search.searchSmart(SmartSearchDto dto): Performs smart search with CLIP.getSearchSuggestions(SearchSuggestionType type, { String? country, bool? includeNull, String? lensModel, String? make, String? model, String? state, }): Retrieves search suggestions mobile/openapi/lib/api/search_api.dart218-220Sources:
Search results on web are displayed using GalleryViewer, which provides:
Features:
Performance Optimizations:
Sources:
Search results on mobile use the Timeline widget:
Features:
Layout:
Sources:
Search chips display active filters visually and are generated dynamically from search terms:
Display Logic:
Chip Rendering:
Sources:
Mobile uses SearchFilterChip components that open bottom sheet pickers:
Chip Types:
PeoplePicker - Multi-select peopleLocationPicker - City/state/countryCameraPicker - Camera make/modelQuickDatePicker - Date rangesTagPicker - Multi-select tagsMediaTypePicker - Image/video toggleStarRatingPicker - 0-5 star ratingDisplayOptionPicker - Favorite/archive/not in albumInteraction Pattern:
Sources:
Both clients support navigating to search with pre-populated filters from other contexts.
The searchPreFilterProvider allows other pages to set initial search filters:
Use Cases:
Implementation:
Sources:
Search capabilities depend on server-side features:
Feature-dependent Search:
isSmartSearchEnabled utility function checks this server/src/services/search.service.ts25Client Adaptation:
smartSearch flag.Sources:
The search system integrates with multiple other Immich subsystems:
Sources:
Refresh this wiki