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

Reverse Filtering

Reverse Filtering (BETA)🔗

NOTE: Reverse filtering is currently a beta feature. Behavior may change in future releases.

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.

NOTE: The SOAP v6 search, searchWithUrl, and searchWithFile responses may now include a reverseFilteredCount element. This element is declared as optional (minOccurs="0") in the v6 WSDL and will only appear when result filtering is active for the environment. Clients that regenerate stubs from the WSDL or that apply strict XML schema validation against it should update their generated code. Clients that do not validate against the schema are unaffected.

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🔗