Search Filtering Using Filter Object

Indexed documents contain properties you can use to construct search filters in the filter object. These properties include categories (domains, path segments, and document types), custom fields, language, and date.

You can use the filter object to filter search results in ready-made views and Search UI Library instances. You can also use it URL-encoded as the Search API request’s filter parameter.

This article explains the filter object and document properties and provides examples of using them in a filter object in different filtering scenarios.

Filter object

A filter object allows you to filter search results based on indexed document properties (category, custom fields, language, and date). You can use a single property or combine multiple properties as search filters. The filter object also allows logical and comparison operators to construct complex filters from these properties.

The filter object supports the following operators:

• Logical Operators:
  • and: All conditions must be true
  • or: At least one condition must be true
  • not: Negates a condition
• Comparison Operators (used with ranges):
  • gt: Greater than
  • lt: Less than
  • gte: Greater than or equal to
  • lte: Less than or equal to

Let’s examine a practical example demonstrating how these operators work together with properties in a filter object.

The filter object below selects items from www.example.com (domain) in the products or services categories, excluding clearance items, made by Apple, priced between 100 and 1000, and excluding PDF or DOCX document types.

{
  "and": [
    { "category": "0xwww.example.com" },
    { "or": [
      { "category": "1xproducts" },
      { "category": "1xservices" }
    ]},
    { "not": { "category": "2xclearance" }},
    { "custom_fields.manufacturer": "apple" },
    { "range": {
      "custom_fields.price": {
        "gte": 100,
        "lte": 1000
      }
    }},
    { "not": {
      "or": [
        { "category": "doctype_pdf" },
        { "category": "doctype_docx" }
      ]
    }}
  ]
}

Category properties

A category refers to an indexed document property that contains information on 1) domain and path segments and 2) document type.

1. Domain and path segments

Domains and path segments are automatically indexed with prefixes identifying each segment’s domain and depth level:

• 0x represents the domain level
• 1x represents the first path segment
• 2x represents the second path segment
• 3x represents the third path segment, and so on…

For example, the URL www.addsearch.com/documentation/category-filters contains the following prefixed path segments:

• 0xwww.addsearch.com
• 1xdocumentation
• 2xcategory-filters

Filter object examples

Returns results from www.example.com:

{ "category": "0xwww.example.com" }

Excludes results from forum.example.com:

{ "not": { "category": "0xforum.example.com" } }

Returns results from /blog/:

{ "category": "1xblog" }

Returns results from www.example.com, excluding forum.example.com and /../past-calendar-events/:

{
  "and": [
    { "category": "0xwww.example.com" },
    { "not": { "category": "0xforum.example.com" } },
    { "not": { "category": "2xpast-calendar-events" } }
  ]
}

Returns results from either /products/ or /blog/:

{
  "or": [
    { "category": "1xproducts" },
    { "category": "1xblog" }
  ]
}

Returns results from www.example.com/manufacturers/apple/:

{
  "and": [
    { "category": "0xwww.example.com" },
    { "category": "1xmanufacturers" },
    { "category": "2xapple" }
  ]
}

Alternative way:

{ "category": "0xwww.example.com/1xmanufacturers/2xapple" }

2. Document type

Document types are automatically indexed using the following identifiers:

• doctype_html
• doctype_pdf
• doctype_doc
• doctype_docx
• doctype_ppt
• doctype_pptx
• doctype_xls
• doctype_xlsx

Filter object examples

Only PDF documents:

{ "category": "doctype_pdf" }

All Microsoft Office documents:

{
  "or": [
    { "category": "doctype_doc" },
    { "category": "doctype_docx" },
    { "category": "doctype_ppt" },
    { "category": "doctype_pptx" },
    { "category": "doctype_xls" },
    { "category": "doctype_xlsx" }
  ]
}

Newer Microsoft Office format:

{
  "or": [
    { "category": "doctype_docx" },
    { "category": "doctype_pptx" },
    { "category": "doctype_xlsx" }
  ]
}

Exclude PDFs and HTML:

{
  "not": {
    "or": [
      { "category": "doctype_pdf" },
      { "category": "doctype_html" }
    ]
  }
}

Custom fields

Custom fields include content indexed from ‘custom-fields’ tags or elements defined using the Custom Fields manager. They can contain numbers for filtering by ranges, like price or reviews.

Learn more here.

Filter object examples

Filter by manufacturer (Apple):

{ "custom_fields.manufacturer": "apple" }

Manufacturer and model & color:

{
  "and": [
    { "custom_fields.manufacturer": "apple" },
    {
      "or": [
        { "custom_fields.model": "iphone-15" },
        { "custom_fields.model": "iphone-15-plus" }
      ]
    },
    { "custom_fields.color": "yellow" }
  ]
}

Products priced 800–1500:

{
  "range": {
    "custom_fields.price": { "gt": 800, "lt": 1500 }
  }
}

Review ratings between 3–5:

{
  "range": {
    "custom_fields.reviews": { "gt": 3, "lt": 5 }
  }
}

Apple products, excluding yellow, with price or review filtering:

{
  "and": [
    { "custom_fields.manufacturer": "apple" },
    { "not": { "custom_fields.color": "yellow" } },
    {
      "or": [
        {
          "range": {
            "custom_fields.price": { "gt": 800, "lt": 1500 }
          }
        },
        {
          "range": {
            "custom_fields.reviews": { "gt": 3, "lt": 5 }
          }
        }
      ]
    }
  ]
}

Language

Language is indexed from page metadata. Details here.

Filter object examples

English documents:

{ "language": "en" }

Exclude English:

{ "not": { "language": "en" } }

Documents in Swedish or Finnish:

{
  "or": [
    { "language": "se" },
    { "language": "fi" }
  ]
}

Date

The date is indexed from page tags, or falls back to the first indexed date. More info here.

Filter object example

Docs between Jan 1–Dec 31, 2024:

{
  "range": {
    "doc_date": {
      "gte": "2024-01-01",
      "lte": "2024-12-31"
    }
  }
}