Restricting search results with filters

🔍 mSearch finds documents with similar meaning 🔍

Filterable fields

Only fields of the following types can be used for filtering:

Simple filter passed as query parameters

Simple filters consisting of one field or several fields in an AND relation can be specified as query parameters of the query endpoint:

Each filtered value goes in its own query parameter named like filter:{field_name}=field_value such as filter:color=red. Documents whose field values contain the filtered value get returned. The value can also be a regular expression such as (red|green), such as:

GET https://api.msearch.themama.ai/msearch/collections/{collection_id}/query?query=shirts-with-animals&filter:color=red&filter:size=(xl|l)

Filters in POST request bodies

Filters are however better placed inside POST request bodies of these endpoints:

Search and answer request bodies may include an optional filter object whose syntax adheres to the filtering capabilities of ElasticSearch which powers the filtering capability of mSearch. For filtering to work, fulltext_config must be enabled for your collection and the fulltext_config.engine must be elastic. The examples below show how filtering can be combined with search.

Search with AND filter in request body

POST https://api.msearch.themama.ai/msearch/collections/{collection_id}/search
Authorization: CENSORED
Content-Type: application/json

{
  "query": "T-Shirts with animals on them",
  "result_format": "flat",
  "highlight": false,
  "filter": {
    "bool": {
      "must": [
        {
          "term": {
            "size": "xl"
          }
        },
        {
          "term": {
            "color": "red"
          }
        }
      ]
    }
  }
}

Search with OR filter in request body

POST https://api.msearch.themama.ai/msearch/collections/{collection_id}/search
Authorization: Basic CENSORED
Content-Type: application/json

{
  "query": "T-Shirts with animals on them",
  "result_format": "flat",
  "highlight": false,
  "filter": {
    "bool": {
      "should": [
        {
          "term": {
            "size": "l"
          }
        },
        {
          "term": {
            "size": "xl"
          }
        }
      ]
    }
  }
}

Search with an AND and an OR filter, and a number in request body

POST https://api.msearch.themama.ai/msearch/collections/{collection_id}/search
Authorization: Basic CENSORED
Content-Type: application/json

{
  "query": "T-Shirts with animals",
  "result_format": "flat",
  "highlight": false,
  "filter": {
    "bool": {
      "must": [
        {
          "range": {
            "price": {
              "lte": 50
            }
          }
        }
      ],
      "should": [
        {
          "term": {
            "size": "xl"
          }
        },
        {
          "term": {
            "color": "red"
          }
        }
      ]
    }
  }
}

Search with a regular expression filter

Regular expression filters get embedded in another filter container of ElasticSearch, as below. The regular expression needs to match the whole value of the field.

POST https://api.msearch.themama.ai/msearch/collections/{collection_id}/search
Authorization: CENSORED
Content-Type: application/json

{
  "query": "T-Shirts with animals",
  "filter": {
    "bool": {
      "filter": {
        "regexp": {
          "size": {
            "value": "x*l",
            "case_insensitive": true
          }
        }
      }
    }
  }
}

Filter only, no query

POST https://api.msearch.themama.ai/msearch/collections/{collection_id}/search
Authorization: CENSORED
Content-Type: application/json

{
  "filter": {
    "bool": {
      "must": [
        {
          "term": {
            "color": "red"
          }
        }
      ]
    }
  }
}

API reference