Reference summary

Reference summaries — historically called faceted filtering — are the core data structure that powers parameterised filtering UIs. The query asks evitaDB to return, alongside the matched entities, a tree of every related reference (brand, parameter, group, …) with hit counts, optional impact predictions and optional numeric histograms. Toggling these references in the UI gives users a real-time, count-aware way to drill into the result set. The benefits are twofold: it improves the user experience by making search far more targeted, and it measurably increases conversion on e-commerce sites by helping shoppers home in on the products that match their criteria.

Facet filter example

The key success factor of a reference-driven (faceted) search is to help users avoid combinations that return zero results. It works best when the UI gradually limits the options that wouldn't make sense given what's already been selected, and provides accurate, on-the-spot, real-time feedback about the number of results that selecting another option would expand or restrict the current result by.

References are usually presented as lists of checkboxes, radio buttons, drop-down menus, or sliders, and are organised into groups. Options within a group typically expand the current selection (logical disjunction), and groups are typically combined with logical conjunction. Some options can be negated (logical negation) to exclude entities that match them.

High-cardinality options are sometimes presented as a search box or interval slider, often paired with a histogram of value distribution to let users specify an exact value or numeric range. evitaDB supports all of these shapes through the constraints documented in this chapter.

evitaLab visualization

If you want to get a feel for how the reference summary is calculated, try the visualization tab in evitaLab:

Reference summary visualization in the evitaLab console

The visualization mirrors the structure of the summary itself:

Icon	Meaning
	At the top level you see the references, marked with the chain icon.
	Below them are the groups found inside those references, marked with the group icon, and below the groups are the individual reference options.
	The number of returned entities that match this reference option when the user has no other options selected (i.e. the userFilter is empty).
	The current number of entities matching the filter constraints; the slash separates this from the difference in result count if this option were added to the user filter.
	The total number of entities the result would contain if this option were selected (i.e. the size of the dataset that matches the option).

Default reference calculation rules

The reference summary is calculated only for entities returned by the current query (excluding the effect of the userFilter part of the query if present).
The calculation respects every filter constraint placed outside the userFilter container.
The default relation between options within a group is logical disjunction (logical OR), unless changed.
The default relation between options in different groups / references is logical conjunction (logical AND), unless changed.

You can change the default calculation relations with facetCalculationRules in the require part of the query. The historical facet* naming is kept on the four behaviour-altering constraints (facetGroupsConjunction, facetGroupsDisjunction, facetGroupsNegation, facetGroupsExclusivity, facetCalculationRules) for backwards compatibility — they apply to references regardless of the constraint's name.

Reference summary

argument:enum(COUNTS|IMPACT)?

Default: COUNTS

optional argument of type

controlling how deep the per-option statistics go:

COUNTS (default, implicit): each option carries only the number of returned entities that contain it
IMPACT: each non-selected option additionally carries an impact prediction (matchCount, difference, hasSense) showing what would happen if the user selected it; affected by conjunction, disjunction, negation and calculation rules

filterConstraint:filterBy

optional filter limiting which individual reference options appear in the summary; can only target properties shared by all referenced entity types — for reference-specific filters use referenceSummaryOfReference instead

filterConstraint:filterGroupBy

optional filter limiting which reference groups appear in the summary; same cross-reference restriction as above applies

orderConstraint:orderBy

optional order constraint that controls the sort order of reference options within each group

orderConstraint:orderGroupBy

optional order constraint that controls the sort order of reference groups

requireConstraint:entityFetch

at most one entityFetch requirement that controls which fields of the reference (option) entity are loaded; identical semantics to entityFetch elsewhere — supports nested referenceContent with further entityFetch / entityGroupFetch to follow the entity graph

requireConstraint:entityGroupFetch

at most one entityGroupFetch requirement that controls which fields of the reference group entity are loaded

requireConstraint:histogramStatistics*

zero or more histogramStatistics children, one per named bucketed index declared on the reference schema (bucketed on the reference). Each child produces a per-group histogram keyed by the group entity's primary key and is the data source for slider widgets driven by histogramHaving. Only allowed when the targeted reference is configured with bucketed indexes; otherwise rejected at construction time.

The

requirement triggers the calculation of the

extra result. The summary is always computed as a side effect of the main entity query and respects the same filtering scope as the main result (excluding the userFilter part). It covers every reference whose schema marks it as faceted. Per-reference overrides — different fetch / filter / ordering settings or different histogram requirements — can be supplied with referenceSummaryOfReference; the per-reference constraint completely replaces the matching configuration from a generic referenceSummary rather than merging with it.

To demonstrate the calculation, let's request the summary for products in the e-readers category:

Reference summary structure

The summary contains only entities referenced by entities returned in the current query response (excluding the effect of the userFilter part) and is organised into a three-tier structure:

reference: the top tier — names of the references marked as faceted in the entity schema
reference group: the second tier — groups specified in the returned entity's references
reference option: the third tier — entities of the returned entity's references

1st tier: reference

For every reference marked as faceted, there is a separate container holding the 2nd-tier reference groups. If the options for this reference aren't organised into groups (the reference lacks group information), the summary contains a single group named non-grouped options.

2nd tier: reference group

A reference group lists every reference option available for the given group / reference combination. It also carries a count of all entities in the current query result that match at least one option in the group / reference.

Optionally, it includes the body of the group entity if the entityGroupFetch requirement is specified.

There may also be a special "group" for options that aren't related to a group.

This group sits on the summary as a nonGroupedStatistics property.

3rd tier: reference option

A reference option contains the per-option statistics:

count: The number of entities in the current query result (including user-filter constraints) that have this option (i.e. reference an entity with this primary key).
requested: TRUE if this option appears in the userFilter container of this query, FALSE otherwise (so the UI can render the corresponding checkbox as checked).

Optionally the body of the option entity if the entityFetch requirement is specified. If the IMPACT statistics depth is requested in the summary, the per-option statistics also include the impact analysis with the following data:

matchCount: The number of entities that would match a new query derived from the current one if this option were selected (had a reference to the entity with this primary key). The current query is left intact, including the userFilter, but the option is virtually added to it to compute the hypothetical impact.
difference: The difference between matchCount (the hypothetical result) and the current number of returned entities — the impact size. It can be positive (the option would expand the result), negative (the option would restrict it), or 0 (no change).
hasSense: TRUE if the option combined with the current query still returns some results (matchCount > 0), FALSE otherwise. Lets the UI mark the corresponding checkbox as disabled when selecting it would yield zero results.

Fetching reference (group) bodies

The bare summary makes little sense without the bodies of reference options and their groups. To retrieve them, add entityFetch or entityGroupFetch to the query. Let's extend the basic example so we get the codes of the options and their groups:

Now the summary contains not only primary keys but also the readable codes of the options and their groups:

If you add the desired locale to the query and request the localised names instead of the codes, you'll get a result that's very close to what the user would see in the UI:

Filtering the reference summary

The summary can grow very large; besides being useless to display in full, it is also expensive to compute. To narrow it down, use the filterBy and filterGroupBy constraints (the latter is the same as filterBy but operates on whole reference groups instead of individual options).

When you put filtering inside the generic referenceSummary requirement, the constraints can only target filterable properties shared by every referenced entity type. If that's not workable, split the generic referenceSummary into one or more referenceSummaryOfReference requirements, each with its own reference-specific filters.

It's hard to find a non-artificial example for filtering the generic reference summary even on our demo dataset, so the example is intentionally contrived. Let's display only options whose code attribute contains the substring ar, and only inside groups whose code starts with the letter o:

We don't restrict the search to a specific hierarchy — the filter alone is selective enough:

Ordering the reference summary

Typically, the summary is ordered to surface the most relevant options first; the same goes for ordering reference groups. Use orderBy to sort options and orderGroupBy (same shape, applied to groups instead of options) for the group level.

When ordering inside the generic referenceSummary, the constraints can only target sortable properties shared by every referenced entity type. If that's not workable, split the generic referenceSummary into one or more referenceSummaryOfReference requirements with reference-specific ordering.

Let's sort both reference groups and options alphabetically by their English names:

The summary is now sorted where it makes sense:

Histogram statistics

argument:int!

mandatory requestedBucketCount — the desired number of histogram columns to compute. Pick a value that matches the pixel width of the histogram widget in the UI; typical values are 10–50. The actual bucket count may be lower under OPTIMIZED / EQUALIZED_OPTIMIZED (empty buckets dropped) but never higher.

argument:enum(STANDARD|OPTIMIZED|EQUALIZED|EQUALIZED_OPTIMIZED)?

Default: STANDARD

optional

controlling how the bucket boundaries are placed and whether empty buckets are kept:

STANDARD: exactly requestedBucketCount equal-width buckets, including empty ones
OPTIMIZED: same as STANDARD, but empty buckets are removed for a denser display (actual count ≤ requested)
EQUALIZED: exactly requestedBucketCount buckets with frequency-equalised boundaries (each bucket ends up with roughly the same number of occurrences)
EQUALIZED_OPTIMIZED: frequency-equalised boundaries with empty-bucket suppression

requireConstraint:entityFetch?

optional fetch describing how richly the referenced (option) entities that contributed to the histogram should be loaded; mirrors the standard entityFetch

argument:string!+

one or more histogram index names as declared on the reference schema's bucketed clause. Each name produces a separate histogram entry in the result, keyed by the histogram name; an instance with no index names is rejected at construction time.

The

require constraint can only appear as a child of referenceSummary or referenceSummaryOfReference and only on references that declare at least one bucketed index. Each histogram is computed per group of the targeted reference: if the reference is parameterValues and the bucketed index is intervalParameterValues, you get one histogram per parameter group (height, weight, thickness, …) inside the corresponding reference group of the summary.

The numeric value plotted in each bucket comes from the valueExpression declared on the reference schema's bucketed index (typically a numeric attribute on the reference or its referenced entity, such as basicUnitValue). The output histogram exposes:

the catalog-wide [min, max] span of the underlying value (the slider's outer handles)
the bucket list with threshold (lower bound, inclusive), occurrences and relativeFrequency
a requested flag per bucket indicating whether it intersects an active histogramHaving range carrier

The [min, max] span is computed by peeling out every value-range carrier under userFilter — both histogramHaving and attributeBetween siblings — so moving a slider does not contract its own outer handles and sibling sliders in the same family also keep their catalog-wide spans. See the peel-by-family rule in behavioral filtering for the full matrix.

To attach histograms to a reference summary, use the dedicated withHistograms factory variants in Java / C# (referenceSummaryWithHistograms / referenceSummaryOfReferenceWithHistograms), which exist to side-step a varargs overload ambiguity with the EntityFetchRequire... factories — the constraints emitted to EvitaQL are still ordinary referenceSummary / referenceSummaryOfReference:

Reference summary of reference

argument:string!: mandatory reference name as declared in the entity schema; the reference must be marked as faceted
argument:enum(COUNTS|IMPACT)?: statistics depth, same semantics as in referenceSummary; defaults to COUNTS
filterConstraint:filterBy: filter on the referenced (option) entity — because the constraint targets exactly one reference type, you can use any filterable property of that entity, not just properties shared across all faceted references
filterConstraint:filterGroupBy: filter on the reference group entity; same per-reference freedom as above
orderConstraint:orderBy: ordering of reference options within each group; can use any sortable property of the reference entity
orderConstraint:orderGroupBy: ordering of reference groups by sortable properties of the group entity
requireConstraint:entityFetch / entityGroupFetch: at most one of each, identical semantics to referenceSummary
requireConstraint:histogramStatistics*: zero or more histogramStatistics — same rules as for referenceSummary, scoped to this reference only

The

requirement either stands alone (when only one reference needs a summary) or coexists with a generic referenceSummary to override its baseline for that single reference. The override is total: every constraint on the per-reference variant replaces the matching constraint from the generic one — they are never merged. This pattern lets you keep a one-line generic baseline and customise only the references that need it.

Let's display the reference summary for products in the e-readers category, but compute it only for the brand and parameterValues references. Options inside brand should be ordered alphabetically by name; options inside parameterValues should be ordered by their order attribute (both at the group and option level), and only groups (parameter) whose isVisibleInFilter flag is TRUE should appear:

A fairly complex scenario that exercises every key feature of the per-reference summary:

Entity group fetch

The entityGroupFetch constraint used inside referenceSummary or referenceSummaryOfReference is identical to entityFetch. The only difference is that entityGroupFetch refers to the group entity schema declared on the faceted reference schema, and is named differently to distinguish the requirement for the referenced entity from the requirement for its group.

Entity fetch

The entityFetch constraint used inside referenceSummary or referenceSummaryOfReference is identical to entityFetch. The only difference is that entityFetch refers to the entity schema declared on the faceted reference schema.

argument:string!

Mandatory argument specifying the name of the reference to which this constraint refers.

argument:enum(WITH_DIFFERENT_FACETS_IN_GROUP|WITH_DIFFERENT_GROUPS)

Default: WITH_DIFFERENT_FACETS_IN_GROUP

Optional enumeration argument specifying whether the relationship type should be applied to options at a particular level (within the same reference group, or to options in different reference groups / references).

filterConstraint:filterBy

Optional filter constraint that selects one or more reference groups whose options will be combined with logical AND instead of the default logical OR.

If the filter is not defined, the behaviour applies to all groups of a given reference in the summary.

The

changes the default behaviour of the reference summary calculation for the groups specified in the filterBy constraint. Instead of the default relationship (either system defaults or overridden defaults), the options in the targeted groups at the given level are combined with a logical AND.

To see the difference from the default, compare the same query with and without this requirement. We need a query that targets some reference (let's say groups) and pretends some options have already been requested (checked). If we now compute the IMPACT analysis for the rest of the options in the group, we'll see that the numbers change:

The facetGroupsConjunction in this example doesn't carry a filterBy, so it applies to every group in the summary — or, in this particular case, to the options in the groups reference that are not part of any group. We don't specify a level either, so it defaults to WITH_DIFFERENT_FACETS_IN_GROUP.

Default behaviour	Altered behaviour
Before	After

Instead of increasing the number of results, impact analysis now predicts a reduction:

argument:string!

Mandatory argument specifying the name of the reference to which this constraint refers.

argument:enum(WITH_DIFFERENT_FACETS_IN_GROUP|WITH_DIFFERENT_GROUPS)

Default: WITH_DIFFERENT_FACETS_IN_GROUP

filterConstraint:filterBy

Optional filter constraint that selects one or more reference groups whose options will be combined with logical disjunction (logical OR) with options from different groups instead of the default logical conjunction (logical AND).

If the filter is not defined, the behaviour applies to all groups of a given reference in the summary.

The

changes the default behaviour of the reference summary calculation for the groups specified in the filterBy constraint. Instead of the default relationship (either system defaults or overridden defaults), options in the targeted groups at the given level are combined with logical OR.

To compare with the default behaviour, we use a query that targets some reference (let's say parameterValues) and pretends the user has already requested some options. The IMPACT analysis for the other group then predicts an expansion instead of a reduction:

Default behaviour	Altered behaviour
Before	After

Instead of reducing the number of results, impact analysis now predicts an expansion:

argument:string!

Mandatory argument specifying the name of the reference to which this constraint refers.

argument:enum(WITH_DIFFERENT_FACETS_IN_GROUP|WITH_DIFFERENT_GROUPS)

Default: WITH_DIFFERENT_FACETS_IN_GROUP

filterConstraint:filterBy

Optional filter constraint that selects one or more reference groups whose options are negated. Instead of returning items that reference the entity in question, the result returns items that do not reference it.

If the filter is not defined, the behaviour applies to all groups of a given reference in the summary.

The

changes the behaviour of the options in every group selected by filterBy. Instead of returning items that reference the entity in question, the query returns items that don't.

As long as the other argument stays at the system default, it doesn't matter whether you set NEGATION at the level within the same reference group or between different groups: by De Morgan's laws the result is the same (!a && !b is equivalent to !(a || b)).

To demonstrate the effect, we use a query targeting some reference (let's say parameterValues) and mark some of its groups as negated:

Default behaviour	Altered behaviour
Before	After

The predicted results in the negated groups are far larger than under the default behaviour: selecting any option in the RAM group now predicts thousands of results, whereas the ROM group with default behaviour predicts only a dozen:

argument:string!

Mandatory argument specifying the name of the reference to which this constraint refers.

argument:enum(WITH_DIFFERENT_FACETS_IN_GROUP|WITH_DIFFERENT_GROUPS)

Default: WITH_DIFFERENT_FACETS_IN_GROUP

filterConstraint:filterBy

Optional filter constraint that selects one or more reference groups whose options are mutually exclusive.

If the filter is not defined, the behaviour applies to all groups of a given reference in the summary.

The

changes the behaviour of the options in every group selected by filterBy. This relationship doesn't affect the query output. It's up to the client to ensure only one option is selected at a given level. If the client provides more than one, the system falls back to the system defaults (logical OR within the same group, logical AND between different groups).

The impact statistics are calculated for the situation in which only this particular option is selected and no others in the same group / different groups are.

Because this operator doesn't affect the actual result-set output, it can only be used for the impact calculation when you want to see the effect of selecting only one option at a particular level.

To demonstrate the effect, we use a query targeting some reference (let's say parameterValues) and mark some of its groups as exclusive:

Default behaviour	Altered behaviour
Before	After

The predicted results in the exclusive groups differ from the default whenever there is an existing selection. With exclusivity in place, the current selection of an option in the RAM group does not affect the predicted counts — they remain identical to the no-selection case:

argument:enum(DISJUNCTION|CONJUNCTION|NEGATION|EXCLUSIVITY)!: Mandatory argument specifying the default relationship behaviour for options within the same reference group. You can change the default logical disjunction (logical OR) to a different value.
argument:enum(DISJUNCTION|CONJUNCTION|NEGATION|EXCLUSIVITY)!: Mandatory argument specifying the default relationship behaviour for options between different reference groups or references. You can change the default logical conjunction (logical AND) to a different value.

The

requirement changes the default behaviour of the reference summary calculation to the specified logical operators. The first argument sets the default relationship for options within the same reference group; the second sets it for options between different groups or references.

Supported logical operators:

DISJUNCTION: Logical OR.
Effect on facet-having behaviour: an entity is present in the result once it has at least one of the selected options at a particular level (within the same reference group / between different groups).
Effect on impact statistics: logical OR is likely to expand the number of results in the final set.
CONJUNCTION: Logical AND.
Effect on facet-having behaviour: an entity is present in the result once it has all selected options at a particular level (within the same reference group / between different groups).
Effect on impact statistics: logical AND is likely to reduce the number of results in the final set.
NEGATION: Logical AND NOT.
Effect on facet-having behaviour: an entity is present in the result once it has none of the selected options at a particular level. As long as the other argument stays at the system default, it doesn't matter whether NEGATION is set within the same reference group or between different groups: by De Morgan's laws the result is the same (!a && !b is equivalent to !(a || b)).
Effect on impact statistics: logical AND NOT is likely to expand the number of results when entities tend to carry only a small fraction of all possible options on average.
EXCLUSIVITY: Special operator stating that only one option can be selected at a given level (within the same reference group / between different groups). Useful for mutually exclusive references.
Effect on facet-having behaviour: none — it's up to the client to ensure that only one option is selected at a given level. If the client provides more than one, the system falls back to the system defaults (logical OR within the same group, logical AND between different groups).
Effect on impact statistics: the calculated match count and impact will be computed for the situation where only this particular option is selected and no others in the same group / in different groups are.
Note: because this operator doesn't affect the actual result-set output, it can only be used for the specific impact calculation if you want to see the impact of selecting only one option at a particular level.

Changing the default reference-summary calculation rules is similar to configuring each individual group relationship via dedicated requirements:

Facet groups conjunction
Facet groups disjunction
Facet groups negation
Facet groups exclusivity

A sample query that changes the default calculation rules:

Author: Ing. Jan Novotný

Date updated: 11.5.2026

Documentation Source

Reference summary

evitaLab visualization

Default reference calculation rules

Reference summary

The reference summary in the e-readers category

Reference summary structure

1st tier: reference

2nd tier: reference group

3rd tier: reference option

Fetching reference (group) bodies

The reference summary in the e-readers category including referenced entity bodies

The reference summary with localised names

Filtering the reference summary

The result of filtering the reference summary

Ordering the reference summary

The result of sorting the reference summary

Histogram statistics

The histogram statistics for e-readers

Reference summary of reference

The result of summarising selected references

Entity group fetch

Entity fetch

Facet groups conjunction

The result with inverted option-relation behaviour

Facet groups disjunction

The result with inverted group-relation behaviour

Facet groups negation

The result with negated option-relation behaviour in the group

Facet groups exclusivity

The result with exclusive option-relation behaviour in the group

Facet calculation rules