Face search

In addition to real-time matching of detected face against faces stored in watchlists, SmartFace is also capable to search in all detected faces stored by SmartFace from all real-time camera streams or all offline video files processed by Rapid Video Processing.

The SmartFace Face Search feature is provided by SmartFace Face Matcher service. This service keeps all available face templates in the memory for the best search performance. The list of face templates is constantly updated with new face templates from camera streams and offline video processing.

Face search processing

Face search request

To perform Face Search on all detected faces you need to make a face matching request through REST API via endpoint: /api/v1/Faces/Search

Example of search request:

  "image": {
    "data": "base64 encoded image"
  "threshold": 40,
  "faceDetectorConfig": {
    "minFaceSize": 30,
    "maxFaceSize": 500,
    "confidenceThreshold": 600
  "faceDetectorResourceId": "cpu", 			// "cpu" or "gpu" or "accurate_cpu" or "accurate_gpu"
  "templateGeneratorResourceId": "cpu" 		// "cpu" or "gpu"
⚠️ The minimum value for the threshold accepted by API is 30. A value of 30 represents a value, where one in a thousand (10 ^ 3) faces can be false positive.

Example of search response:

  "searchSessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"

The response contains SearchSessionId which can be used to query data via GraphQL API.

All match results are stored in the database, and each search request will create:

  • SearchSession object in database, which identifies each search by its searchSessionId.

  • SearchSessionObject for each matched face above requested threshold

Querying face search results

Only GraphQL can be used to query for results of face search functionality. You can either traverse SearchSessionObjects and its linked Faces or vice versa.

Example of GraphQL query:

query {
  faces (where: { searchSessionObjects: { some: { searchSessionId: { eq:"3fa85f64-5717-4562-b3fc-2c963f66afa6"}}}}) {
    items {

Deleting face search results data

The face search feature can produce large amounts of SearchSessionObjects data, which can lead to reduced performance when querying data.

You can setup cleanup process of this data by making request through REST API via endpoint: /api/v1/Setup/SearchSessionsCleanup

Example of search results cleanup process configuration request:

  "enabled": true,
  "maxItemsCount": 100000000,
  "maxSessionAge": "7.00:00:00",
  "interval": "01:00:00"
PropertyProperty typeProperty summaryValid valuesDefault values
IntervalTimeSpan or nullThe interval of cleanup.01:00:00
MaxSessionAgeTimeSpan or nullThe maximum age of Search sessions which will be stored. When the cleanup runs, all Search sessions older than MaxSessionAge will be removed.7.00:00:00
MaxItemsCountinteger or nullThe maximum count of Search sessions items (associations between search session and matched face) for which the Search sessions will be stored. When the cleanup runs, the count of Search sessions to delete to meet this constraint is computed and afterwards these Search sessions will be removed.

  • After each cleanup the number of Search sessions items will be always less or equal than MaxItemsCount
  • If oldest search sessions contain no Search session items then they will be also removed whatever the value of MaxItemsCount property is.
Greater than zero or null100000000

Face search HW requirements

The Face Matcher service keeps all available face templates in the memory for the best search performance. If you have a long history of detected faces in the database from many high-traffic cameras, you need to consider allocating special HW resources just to run this service.

⚠️ It is important to allocate enough resources to Face Matcher, otherwise it can have a major impact on the core functionality of the SmartFace system. In case you do not use Feace Search feature, it is recommended to remove Face Matcher form your system design.
ℹ️ All measurements were done on x86 PC with following configuration: i7-7700 CPU, 3.60GHz, MS SQL server 2016. All times may vary depending on your system HW and SW configuration.

Memory footprint of Face Matcher

Reference measurements:

Faces in DBMemory usage
1,151,5541.9 GB
2,403,0443.5 GB

Example: If your face database contains e.g. 10,000,000 faces, you have to count with 15 GB of memory for loaded templates and +20% increase in memory during search requests.

Initial loading time

It will take approximately 3.5 minutes to initially load 1 million face templates from the database into Face Matcher if the database is on the same server as the service itself. Increase of the loading time is linear with increasing number of faces.

Example: If your face database contains e.g. 10,000,000 faces, initial load time will be 35 minutes.

Search time

Final duration of the face search consist from two times:

  • matching time - in memory match of all loaded templates with uploaded face

  • results insert time - time of inserting SearchSessionObjects into the database

Matching time on 1 million face templates in memory is approximately 500 ms.

Results insert time depend on number of results what need to be inserted, database access speed and available HW.

Reference measurements:

Number of resultsInsert time

Example: If your face database contains e.g. 10,000,000 faces, and you will have 1% matches (~ 100,000) you can calculate the search time:
Search Time = Matching time + Result Insert Time = 0.5s * 10 + 2s = approx. 7 seconds

Cleanup process time

Reference measurements:

Session object countApprox. cleanup time
100 0002s
1 000 00020s
1 000Instant
10 000Instant