Search Filtering Using BaseFilter Object

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

You can use the baseFilter 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 baseFilter object and document properties and provides examples of how to use them in a baseFilter object in different filtering scenarios.

Basefilter object

A baseFilter 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 baseFilter object also allows for logical and comparison operators to construct complex filters from these properties.

The baseFilter 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 baseFilter object.

The baseFilter object below selects items from www.example.com (domain) in the products or services categories (/products/ or /services/ as first path segments), excluding clearance items (/../clearance/ as second path segment), 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 that identify each path segment’s domain and depth level as follows:

• 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…

The prefixes 0x, 1x, 2x, and 3x indicate the depth level of the domain and each segment in the URL and this pattern continues with the prefix number increasing for each additional segment.

For example, the URL www.addsearch.com/documentation/category-filters contains the following prefixes with the domain and path segments:

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

BaseFilter 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 to return results from www.example.com/manufacturers/apple/:

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

2. Document type

Document types are automatically indexed with the following category identifiers:

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

BaseFilter examples

Returns only PDF documents:

{
  "category": "doctype_pdf"
}

Returns all Microsoft Office document types (Word, PowerPoint, Excel; both old and new versions):

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

Returns only newer Microsoft Office document types (docx, pptx, xlsx):

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

Returns Microsoft Office documents by excluding PDFs and HTML pages:

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

An alternative approach to exclude PDFs and HTML pages:

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

Custom fields

Custom fields consist of content indexed from ‘custom-fields’ tags or the elements of your web pages indexed with the Custom Fields manager. Custom fields can contain numeric values, which allow for sorting results and returning results between ranges such as prices and reviews.

For more information on custom fields, please visit our documentation here.

BaseFilter examples

Returns documents that contain a specific manufacturer (Apple).

{
    "custom_fields.manufacturer": "apple"
}

Returns documents that contain a specific manufacturer (Apple), specific phone models (iPhone 15 or iPhone 15 Plus), and a specific color (yellow):

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

Returns documents where the price is between 800 and 1500:

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

Returns products with a review rating between 3 and 5:

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

Returns results for Apple products, excluding yellow items, priced between 800 and 1500 and rating between 3 and 5:

{
    '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 tags on the web page mentioned here.

BaseFilter examples

Returns documents in English (en):

{
    "language": "en"
}

Excludes English (en) documents:

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

Returns documents in Swedish (se) and Finnish (fi):

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

Date

The date is indexed from tags on the web page mentioned here. Note that, if the tag to determine date doesn’t exist on the page, we use the date when the document was initially indexed.

BaseFilter examples

Returns documents between the dates January 1, 2024, and December 31, 2024:

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