Recommender Filtering

08/09/2025

This page explains how to use the Recommender API's filtering feature to narrow down recommendation results based on specific document properties. To filter results, you add a filter field to the standard /recommend endpoint request body. This field accepts a JSON object that acts as the body of an Elasticsearch Boolean query.

The filter field takes an Elasticsearch Boolean query body, which can include various query types like term, query_string, and nested queries. This allows you to create highly specific and complex filtering conditions.

To create a filter object, you need to understand the syntax of Elasticsearch Boolean queries. The official Elasticsearch documentation is your best resource for learning about the different query types and how to structure a Boolean query.

A Boolean query consists of logical clauses (must, should, must_not, filter) that can contain other query types. You can use any of these clauses to build your filter.

The fields you can filter on are defined in the Elasticsearch documents. These fields are created during content ingestion via the GraphSearch API. They are based on the document's content and its associated taxonomy and ontology data.

Main Field Categories

The following are the primary field categories you can use for filtering:

Free text: dyn_txt_content contains the document's title and content.
Concept annotations (taxonomy): dyn_uri_all_concepts contains all taxonomy-based concepts associated with the document.
Integer annotations (ontology attributes): dyn_int_attr_<URI_OF_ATTRIBUTE> stores integer-based ontology attributes.
String annotations (ontology attributes): dyn_lit_attr_<URI_OF_ATTRIBUTE> stores string-based ontology attributes.
Entity annotations (classes): dyn_uri_rdftype contains URIs for document classes.
Ontology-based annotations: dyn_uri_pred_<URI_OF_RELATION> contains URIs of related objects based on ontology relations (such as citizenOf or adoptedBy).
Date: date stores the document's date.

Note

The exact field names for ontology-based attributes and relations are dynamic and can be discovered via the GraphSearch API as described in the next section.

Ontology-based fields are dynamically generated based on the URIs defined in your PoolParty project. For example, in the case of integer attributes, the field name is constructed as dyn_int_attr_<URI_OF_ATTRIBUTE>, and <URI_OF_ATTRIBUTE> is the URI of an attribute from your PoolParty ontology that was assigned during content creation. The URIs used in these field names are the same as those you can find and manage within the PoolParty Ontology Management tool.

Because ontology-based field names are dynamically generated, you cannot assume what they will be. To find the correct field names for a specific search space, use the GraphSearch API's /api/context/fields endpoint.

Example request:

curl -X GET http://localhost:8081/GraphSearch/api/context/fields?searchSpaceId=c8f0b28e-0731-494b-896b-d736a786828b

This request will return a list of all available Elasticsearch fields for the given searchSpaceId, which you can then use in your filter queries.

The following is an example for an Elasticsearch Boolean query with other nested queries, applied as a filter in a recommendation request:

{
  "searchSpaceId": "{searchSpaceID}",
  "locale": "en",
  "input": "The quick brown fox jumps over the lazy dog.",
  "concepts": [
    {
      "uri": "http://id.nlm.nih.gov/mesh/2016/D005589",
      "score": 15.248
    }
  ],
  "filter": {
    "must": [
      {
        "bool": {
          "should": [
            {
              "match": {
                "title": "Title example"
              }
            },
            {
              "match": {
                "user.id": "1234567"
              }
            }
          ]
        }
      },
      {
        "match": {
          "language": "en"
        }
      }
    ],
    "should": [
      {
        "bool": {
          "must": [
            {
              "match": {
                "status": "technically not a must to match with this"
              }
            },
            {
              "match": {
                "title": "also not a must to match with this"
              }
            }
          ]
        }
      }
    ]
  },
  "page": 0,
  "size": 100
}

This is an example of a general Elasticsearch Boolean query using the query_string query type, with the actual search criteria provided in its nested "query" field, applied as a filter in a recommendation request:

{
  "searchSpaceId": "{{searchSpaceID}}",
  "locale": "en",
  "input": "The quick brown fox jumps over the lazy dog.",
  "concepts": [
    {
      "uri": "http://id.nlm.nih.gov/mesh/2016/D005589",
      "score": 15.248
    }
  ],
  "filter": {
    "minimum_should_match": 1,
    "should": [
      {
        "query_string": {
          "fields": [
            "title",
            "content"
          ],
          "query": "In Conversation: Why exercise is key to living a long and healthy life"
        }
      }
    ]
  },
  "page": 0,
  "size": 100
}

In this section: