Catalog facets

What a count means

A brand count may mean products in the current result set or products available after selecting that brand. These are different UI contracts. Independent facets commonly apply all active constraints except their own selection. Multiple brands often combine with OR, while brand and size combine with AND. Define the rule explicitly.

query, post_filter and global

query restricts hits and aggregations. post_filter affects hits after aggregation calculation, useful when counts need a wider scope. global escapes query scope, so mandatory access constraints must be reapplied within it. Multiple independent facets often need separate filter aggregations with different active constraints.

Products versus values

A multivalued document may contribute to several buckets, so their counts need not sum to unique products. Nested facets initially count nested documents; reverse_nested returns to root products. Do not present offer counts as product counts. Test with a product containing two qualifying offers.

{
  "query": {
    "match": {
      "name": "headphones"
    }
  },
  "aggs": {
    "brands": {
      "terms": {
        "field": "brand"
      }
    }
  },
  "post_filter": {
    "term": {
      "brand": "Sony"
    }
  }
}

Catalog reasoning example

A category contains Sony:5 and Bose:3. Selecting Sony gives five hits. Computing brand facets over those hits hides Bose. If users can add Bose, count brands within the category without the active brand selection, while retaining price and stock. With several facets, each scope omits only its own selection; one post_filter does not automatically implement every independent facet rule.

Aggregate in-stock products

A filter aggregation creates a single bucket containing documents that pass its query. Only its child aggregations inherit that restriction. In this example total hits still includes every product, but out_of_stock contains unavailable products and its average describes only those products.

A top-level query would restrict all aggregations and the search result itself. Choose the scope from the business question: one local comparison needs a filter bucket; one shared restriction for everything belongs in query. filter buckets expose doc_count, which helps verify that a metric used the intended population.

{
  "size": 0,
  "aggs": {
    "out_of_stock": {
      "filter": {
        "term": {
          "in_stock": false
        }
      },
      "aggs": {
        "average_price": {
          "avg": {
            "field": "price"
          }
        }
      }
    }
  }
}

{
  "hits": {
    "total": {
      "value": 300,
      "relation": "eq"
    },
    "hits": []
  },
  "aggregations": {
    "out_of_stock": {
      "doc_count": 100,
      "average_price": {
        "value": 724.3
      }
    }
  }
}

Conditional metrics within groups

Keep parent counts and local eligibility separate. The top-level query selects statuses active or preorder in this example. A brands bucket counts every matching document of that brand. Its eligible child then requires stock AND (rating at least 4.5 OR no indexed rating). The inner minimum_should_match makes the rating alternatives mandatory.

Write missing rating as bool.must_not containing exists. Keep stock outside the rating alternatives, so an unrated but unavailable item does not qualify. The same missing-value logic treats null as unindexed in our fixed mapping. A zero rating exists and fails the threshold; it must not pass the missing branch.

Place average_price, min_price and max_price inside eligible.aggs. If a brand has active or preorder products but none are eligible, its parent bucket remains with a positive doc_count, eligible.doc_count is zero, and all three metrics are null. Moving the eligibility filter into query would erase this distinction and answer a different question.

{
  "size": 0,
  "query": {
    "terms": {
      "status": [
        "active",
        "preorder"
      ]
    }
  },
  "aggs": {
    "brands": {
      "terms": {
        "field": "brand.keyword",
        "size": 20
      },
      "aggs": {
        "eligible": {
          "filter": {
            "bool": {
              "filter": [
                {
                  "term": {
                    "in_stock": true
                  }
                }
              ],
              "should": [
                {
                  "range": {
                    "rating": {
                      "gte": 4.5
                    }
                  }
                },
                {
                  "bool": {
                    "must_not": [
                      {
                        "exists": {
                          "field": "rating"
                        }
                      }
                    ]
                  }
                }
              ],
              "minimum_should_match": 1
            }
          },
          "aggs": {
            "average_price": {
              "avg": {
                "field": "price"
              }
            },
            "min_price": {
              "min": {
                "field": "price"
              }
            },
            "max_price": {
              "max": {
                "field": "price"
              }
            }
          }
        }
      }
    }
  }
}

{
  "hits": {
    "total": {
      "value": 200,
      "relation": "eq"
    },
    "hits": []
  },
  "aggregations": {
    "brands": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": [
        {
          "key": "Apple",
          "doc_count": 50,
          "eligible": {
            "doc_count": 19,
            "min_price": {
              "value": 49
            },
            "average_price": {
              "value": 864.8421052631579
            },
            "max_price": {
              "value": 1299
            }
          }
        },
        {
          "key": "Logitech",
          "doc_count": 50,
          "eligible": {
            "doc_count": 15,
            "min_price": {
              "value": 99
            },
            "average_price": {
              "value": 919.7333333333333
            },
            "max_price": {
              "value": 2499
            }
          }
        },
        {
          "key": "Sony",
          "doc_count": 50,
          "eligible": {
            "doc_count": 0,
            "min_price": {
              "value": null
            },
            "average_price": {
              "value": null
            },
            "max_price": {
              "value": null
            }
          }
        },
        {
          "key": "apple",
          "doc_count": 50,
          "eligible": {
            "doc_count": 0,
            "min_price": {
              "value": null
            },
            "average_price": {
              "value": null
            },
            "max_price": {
              "value": null
            }
          }
        }
      ]
    }
  }
}