Skip to content

Facet Management

Facet management lets you control which filters appear in search results, their configuration, and how they aggregate data to create optimal navigation experiences.

Overview

Facets (filters) help users refine search results by showing available options for attributes like brand, price, color, and category. Facet management gives you control over which facets appear, how they're configured, and how they aggregate data.

Facet Configuration

Facets are configured in the search API using the facets parameter. The configuration includes:

Global Facet Parameters

  • fields: Map of field names to their facet configuration
  • maxResults: Maximum number of facet results to return per field (default: 100, max: 10000)
  • maxDepth: Maximum number of documents to consider for aggregation per shard (optional, improves performance)
  • order: Order of facet results - asc (ascending) or desc (descending) based on count (default: desc)

Field-Level Parameters

Each field in the fields map can have:

  • type: Facet type - string, number (for integer and float fields), or array
  • maxResults: Overrides global maxResults for this specific field
  • order: Overrides global order for this field
  • ranges: For numeric fields only - defines ranges for bucketing numeric values
  • excludeTerms: Excludes specific terms from the filter query for that facet field

Range Parameters (for numeric fields)

When using ranges for numeric fields, each range object can have:

  • from: Lower bound of the range (inclusive). If not specified, treated as -Inf
  • to: Upper bound of the range (exclusive). If not specified, treated as Inf
  • name: Custom name for the range (defaults to "from:to" format)

Facet Types

String Facets

String facets aggregate text values and return counts for each unique value:

{
  "facets": {
    "fields": {
      "color": {"type": "string"}
    }
  }
}

Response: 

{
  "facets": {
    "color": {
      "red": {"count": 5},
      "blue": {"count": 3},
      "green": {"count": 2}
    }
  }
}

Numeric Facets

Numeric facets provide statistics (min, max, avg, sum, count) for numeric fields:

{
  "facets": {
    "fields": {
      "price": {"type": "number"}
    }
  }
}

Response: 

{
  "facets": {
    "price": {
      "min": 1.2,
      "max": 99.9,
      "avg": 37.5,
      "sum": 262.5,
      "count": 7
    }
  }
}

Numeric Range Facets

Define custom ranges for numeric fields:

{
  "facets": {
    "fields": {
      "price": {
        "type": "number",
        "ranges": [
          {"to": 50, "name": "budget"},
          {"from": 50, "to": 100},
          {"from": 100, "name": "premium"}
        ]
      }
    }
  }
}

Response: 

{
  "facets": {
    "price": {
      "budget": {
        "min": 10.99, "max": 49.99, "avg": 29.99, "sum": 149.95, "count": 5
      },
      "50.0:100.0": {
        "min": 59.99, "max": 99.99, "avg": 79.99, "sum": 319.96, "count": 4
      },
      "premium": {
        "min": 129.99, "max": 199.99, "avg": 164.99, "sum": 494.97, "count": 3
      }
    }
  }
}

Array Facets

Array facets aggregate values from array fields:

{
  "facets": {
    "fields": {
      "tags": {"type": "array"}
    }
  }
}

Response: 

{
  "facets": {
    "tags": {
      "color": {"red": {"count": 5}, "blue": {"count": 3}},
      "brand": {"Marqo": {"count": 4}, "FashionBrand": {"count": 2}},
      "type": {"shirt": {"count": 8}}
    }
  }
}

Advanced Configuration

Excluding Terms

Exclude specific terms from facet results:

{
  "facets": {
    "fields": {
      "color": {"type": "string", "excludeTerms": ["color:red"]},
      "brand": {"type": "string", "maxResults": 10, "excludeTerms": ["brand:Marqo"]}
    }
  }
}

Custom Ordering

Set custom ordering per field:

{
  "facets": {
    "fields": {
      "category": {"type": "string", "maxResults": 5, "order": "asc"}
    },
    "order": "desc"
  }
}

Performance Optimization

Use maxDepth to limit documents considered for aggregation (improves performance):

{
  "facets": {
    "maxDepth": 1000,
    "fields": {
      "brand": {"type": "string"}
    }
  }
}

Best Practices

  1. Choose relevant fields: Select fields that users actually want to filter on
  2. Limit facet count: Use maxResults to avoid overwhelming users with too many options
  3. Use ranges for prices: Create meaningful price ranges for better UX
  4. Optimize performance: Use maxDepth for large catalogs to improve response times
  5. Exclude irrelevant terms: Use excludeTerms to hide values that shouldn't appear
  6. Order logically: Use order to show most popular or relevant options first