How Immich Finds Faces and Meaning
Immich’s search and face features are not properties that appear automatically when an original file is stored. They are indexes built over the archive: some use explicit metadata, while others use machine-learning representations and clustering. This chapter explains that difference and the trade-offs behind it. The reader should come away able to tell what a search result is grounded in, why model choice changes resource use and language coverage, and why a recognized face remains an inference that may need correction.
The useful contrast is not “ordinary search versus artificial intelligence.” Immich combines several search paths because they answer different questions. A filename or date filter can use information already recorded. A contextual query can retrieve images whose metadata never contains the words used in the query. Facial recognition adds another index whose usefulness depends on detection, similarity, clustering, and human naming.
Two kinds of search answer different questions
Metadata search starts with explicit properties of an asset. Immich documents filters for people, file names and extensions, original paths, descriptions, OCR text, locations, tags, cameras, time ranges, media type, archive or favorites state, and ratings. If a user knows a date, a folder fragment, a camera model, or a word recognized from an image, the system can search a recorded field or a structured index. The result is explainable in a direct way: the asset matched a value or condition that the system already stored.
Contextual search is useful when the desired concept was never written into the file. Immich uses Postgres as its search database and documents VectorChord-backed contextual CLIP search. A CLIP model lets the system compare a free-form text query with learned representations of visual content, so a phrase can retrieve relevant images without requiring that phrase to appear in a filename, description, or other metadata. The user does not need to predict the exact label that an earlier metadata-extraction step chose.
That convenience does not make contextual search a replacement for filters. A query such as “photographs from a particular camera in a given month” is naturally expressed through explicit fields. A query such as “a person standing beside a red boat” may benefit from a learned representation because the relevant relationship is not necessarily present in the metadata. One path is not more real than the other; they operate on different evidence.
The same distinction helps explain why the index must be built after ingestion. The original file and its metadata are inputs. Background work creates the representations used for contextual retrieval, and those representations are stored in a form that can be searched. Until that work completes, an image can be present in the timeline while remaining invisible to a contextual query. Search quality therefore depends on both the model and the completeness of the processing lifecycle.
Explicit search is not limited to a filename box. A location filter can use reverse-geocoded city or country information; an OCR filter can use text found in an image; a camera filter can use make, model, or lens information; and a people filter can use face groupings once those groupings exist. These fields compose into a narrower question without asking a model to infer the whole meaning of a sentence. They also expose their own boundary: a missing or incorrect metadata field can make a precise filter return nothing even when the image is visually relevant.
Contextual retrieval changes the form of the question rather than eliminating uncertainty.