Face search
Watchlist matching answers "is this one of the people I know?". Face search answers a different question: "when and where has this face been seen before?". It searches a query face against all faces ever detected by the cameras and edge streams, whether or not they matched a watchlist, and returns the detections ranked by score. Typical uses are investigating an incident ("show me every appearance of this person last week") and checking whether a new enrollment candidate has been seen at the site before.
The face search service
Face search is provided by the face search service, the container named face-matcher in the release package. To answer within milliseconds it keeps every stored face template in memory, seeds them from the database at start-up (FaceMatcher__SeedPageSize, default 50000 templates per page) and keeps the set up to date as cameras produce new faces. A search compares the query template with all loaded templates, then writes the results into the database as a search session that the API and Station can page through.
Face search therefore depends on stored detections: if a camera's save strategy or the global storage mode prevents faces from being stored, they cannot be found later, see Data retention. Templates must have been extracted with the same algorithm version the service uses; after changing the extraction algorithm, migrate templates first.
Hardware considerations
Because all templates live in memory, the service's footprint grows with the detection history. Reference measurements from the platform team:
| Faces stored | Memory of the face search service |
|---|---|
| 1,151,554 | 1.9 GB |
| 2,403,044 | 3.5 GB |
Rule of thumb: about 15 GB per 10 million faces, plus roughly 20 % more while a search runs. Initial loading takes about 3.5 minutes per million templates when the database is on the same server and grows linearly, so 10 million faces need about 35 minutes before the first search can be answered after a restart.
A search itself has two parts: in-memory matching, roughly 500 ms per million templates, and inserting the results, which depends on how many detections pass the threshold (about 2 s for 100,000 results, about 40 s for a million). Ten million faces with 1 % hits therefore take around 7 s. Give the service enough memory: if it starves, it can affect the rest of the deployment. If you do not need face search, remove the face-matcher service from your Compose project or scale it to zero replicas; no other service depends on it.
Cleanup
Search sessions and their result objects are stored in the database and are removed by the same daily cleanup that prunes old detections. Removing up to 10,000 session objects is instant; 100,000 take about 2 s and a million about 20 s. Configure retention in the data retention and cleanup guide.
Using it
Face search is exposed through the REST API (see the REST API reference) and in Station's event history, where you can search past events by an uploaded face, see Event history.