Skip to content

Basic Faceting

Faceting allows users to narrow down search results based on values within specific fields.

How Faceting Works

In the example below, faceting is applied to the Brand field, showing a list of brands alongside the number of results associated with each brand.

Faceting example

This enables users to quickly narrow down results by selecting one or more brands.

Basic vs. Advanced Faceting

Gainly supports two types of faceting:

  • Basic Faceting: Specified through the facet parameter, and described below.
  • Advanced Faceting: Specified through the facet_advanced parameter, and described here.

How to Specify Basic Facets

Use facet parameter to apply basic faceting to one or more of the supported fields:

"facet": [
  "metadata.brand",
  "metadata.category"
]

The following API requests support the facet parameter:

API response will include the facet_result property:

"facet_result": {
  "metadata.brand": {                     // Facet results for the `metadata.brand` field
      "buckets": [
          {
            "value": "Brand A",           // Value in metadata.brand field
            "doc_count": 500              // (integer) Number of documents with this value
          },
          {
            "value": "Brand B",
            "doc_count": 300
          },
          {
            "value": "Brand C",
            "doc_count": 200
          }
      ]
  },
  "metadata.category": {                  // Facet results for the `metadata.category` field
      "buckets": [
          {
            "value": "Category 1",        // Value in metadata.category field
            "doc_count": 400              // (integer) Number of documents with this value
          },
          {
            "value": "Category 2",
            "doc_count": 350
          },
          {
            "value": "Category 3",
            "doc_count": 250
          }
      ]
  }
}

The buckets property is an array of buckets, where each bucket represents a distinct value in the faceted field and its associated document count. Top-10 buckets for each faceted field will be returned.

When user selects a bucket

When a user selects a bucket (e.g., by clicking a checkbox in your app UI), perform a query with the appropriate value in the filter parameter.

For example, if user selected Brand A, you would perform a new query with:

1
2
3
4
5
6
7
8
9
"filter": {
  "must": [
    {
      "term": {
        "metadata.brand": "Brand A"
      }
    }
  ]
}
This filter limits the results to documents where the metadata.brand field matches "Brand A"

Supported Fields for Basic Faceting

You can use the following fields for faceting:

  • tenant_id
  • language
  • metadata subfields of supported field types. Specify using dot notation, for example:
    • metadata.color
    • metadata.brand.model

Metadata Field Types - Basic Faceting

These metadata field types are the primary use case for basic faceting:

  • keyword
    • String fields that store one or more predefined values. For example: Brand, Category, Department, etc.
  • boolean

Common Pitfalls

  • Field names and types:
    • Always use dot notation for metadata fields (e.g., metadata.brand not just brand)
    • Only keyword and boolean field types are supported in basic faceting
    • Ensure fields used for faceting have the correct field types in your metadata schema
  • Results and buckets:
    • Basic faceting returns only the top 10 buckets per field
    • For more control over bucket count, use Advanced Faceting
    • Empty buckets (count = 0) are not returned in the results
    • Sort buckets in your application based on your needs, for example:
      • By doc_count for popularity-based display
      • By value for alphabetical/numerical ordering
  • Performance considerations:
    • Each faceted field adds computation time to the query
    • Faceting on high-cardinality fields (fields with many unique values) will impact performance
    • Consider using filters to reduce the dataset before applying facets
  • UI implementation:
    • Update facet counts when filters are applied
    • Consider the UX impact of showing too many facet fields at once
    • Handle cases where no facet results are returned
  • For advanced faceting needs: