Skip to content
Search! & Match! API
Reverse Filtering
latest

Reverse Filtering

Reverse Filtering🔗

Reverse filtering is a post-search field-level filtering capability designed for automated matching flows, such as matching candidates against job requirements (candidate-to-job matching). It enables a hard-knockout removal of results that impose field-value requirements not satisfied by the search query.

Use Case🔗

In automated matching workflows, a search query is auto-generated from source document information. The searcher returns results that are semantically similar, but some results may impose specific requirements — such as language skills or education levels — that are not present in the source. While bi-metric scoring penalizes such asymmetric matches with a lower reverse score, it does not eliminate them; it only re-ranks them.

Reverse filtering provides a complementary hard removal step: for fields configured to support reverse filtering, any result that imposes requirements not fully satisfied by the query is dropped from the result list before results are returned.

Example (candidate-to-job matching): A job requiring both Dutch and English language skills is removed from results for a candidate who only speaks English, even if the overall semantic similarity score was high.

How It Works🔗

Reverse filtering is based on an all-must-match semantics: if a result has any values for a configured field, the search query must satisfy all of those values. A partial match (e.g., query contains English but not Dutch when both are required) results in the result being removed.

Configuration🔗

Reverse filtering is configured at the searcher level in the environment configuration via the <reverseFilter> element, which lists environment field names (not concept names) to which the filter applies.

Example configuration:

<searcher name="internal" type="elasticsearch" label="Internal">
    <bimetricScoring>true</bimetricScoring>
    <reverseFilter>
        <field>educationlevel_international</field>
        <field>langskills</field>
    </reverseFilter>
</searcher>

In this example:

  • educationlevel_international is a top-level ORDERED field containing a single education level per document
  • langskills is a multivalued object field, where each object represents a language with an associated proficiency level

Enabling per Request🔗

Reverse filtering is opt-in at the request level. The search request must include allowResultFiltering: true to activate the filter. Without this flag, the filter is not applied, keeping the behavior as usual.

SOAP example:

<request>
    <query>langskills:{name:English level:>=Intermediate} langskills:{name:Spanish level:>=Advanced}</query>
    <allowResultFiltering>true</allowResultFiltering>
</request>

Requirements🔗

Reverse filtering has three requirements:

  1. Bi-metric Scoring Enabled — The searcher must have <bimetricScoring>true</bimetricScoring> configured. Reverse filtering reuses the per-value match marks produced by bi-metric scoring internally, avoiding additional processing cost.

  2. Field Types — Most field types are supported except for NUMERIC, DATE and LOCATION.

  3. Field in Result Fields — All fields listed in <reverseFilter> must also be included in the searcher's <resultFields> configuration so the filter can access their values.

Response Format🔗

When reverse filtering is applied, the response includes a reverseFilteredCount field indicating the number of results removed:

SOAP example:

<searchResult>
    <matchSize>30</matchSize>
    <reverse_filtered_count>2</reverse_filtered_count>
    <resultItems>...</resultItems>
</searchResult>

Important: matchSize represents the total number of results found by the searcher before reverse filtering is applied. The actual number of returned items may be lower. This is intentional: matchSize reflects the index query result, not the post-filtering step.

Limitations🔗

First Page Only — Reverse filtering is applied only to the first page of results. On subsequent pages (when using pagination), reverse filtering is silently skipped. This is consistent with other post-processing features like bi-metric score threshold estimation. The feature is designed for single-pass automated matching flows, not for paginated interactive searches.

If you need to paginate through reverse-filtered results, request a larger pageSize to ensure you receive the number of items you need even after filtering.

Examples with ORDERED Fields🔗

Education Level🔗

Education levels are stored as integers mapped to labels via a code-table:

  • 1 = Secondary Education
  • 2 = Vocational Education
  • 3 = Bachelor
  • 4 = Master
  • 5 = Post-Master

A requirement of >=Bachelor is satisfied by a query containing Bachelor, Master, or Post-Master education.

Language Proficiency Levels🔗

Language skills are typically stored in a multivalued object where each language is paired with a proficiency level:

  • 1 = No Knowledge
  • 2 = Basic Knowledge
  • 3 = Intermediate
  • 4 = Advanced
  • 5 = Near Native
  • 6 = Native

A result requiring [English: Advanced, French: Intermediate] is kept only if the query contains English at Advanced level and French at Intermediate level or higher. A query containing only English at Advanced level causes the result to be filtered out, even if English proficiency matches.

Cross-References🔗