catalog.fn.facets()
Get unique values with counts for building filter UIs. Returns all distinct values for a given attribute along with how many items match each value.
Syntax
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
attribute | string | Yes | The attribute to get facets for |
count | number | No | Limit the number of facet values returned |
excludeZeros | boolean | No | Exclude facets with 0 count (default: true) |
excludeUndefineds | boolean | No | Exclude undefined values (default: true) |
calculateResults | boolean | No | Include resultKeys array (default: true) |
excludeUnresolved | boolean | No | Exclude facets from unresolved references (default: false) |
Return Type
Returns an array of DcuplFacet objects:
Usage Notes
- Facets respect current query filters - counts update as filters change
- Ideal for building filter sidebars, search refinements, and data exploration
- Performance: Set calculateResults: false when you only need counts, not item keys
- Performance: Use count parameter to limit results for attributes with many unique values
- Troubleshooting: If enabled is always false, check that your current query filters the exact attribute you are faceting on.
Related Methods
catalog.query.addCondition()- Apply filters based on facet selectioncatalog.query.many()- Get the actual json values behind the resultKeys
Related Guides/Docs
Examples
Building a Filter Sidebar
Create a complete filter UI with facets showing available options, counts, and selected state.
Deep Property Facets
Get facets from referenced models using dot notation for related data.
Performance Optimization
Disable result key calculation when only counts are needed for better performance.
Limiting Facet Results
Limit the number of facet values returned for "Top N" style filters.
Facets with Active Filters
Facets automatically update to show available options based on current query filters.