evitaDB - Fast e-commerce database
logo
page-background

Reference filtering

Reference filtering is used to filter entities based on their references to other entities in the catalog or attributes specified in those relations.

Reference having

argument:string!
the name of the entity reference that will be subjected to the filtering constraints in the second and subsequent arguments
filterConstraint:any+

one or more filter constraints that must be satisfied by one of the entity references with name specified in the first argument

The
constraint eliminates entities which has no reference of particular name satisfying set of filtering constraints. You can examine either the attributes specified on the relation itself or wrap the filtering constraint in entityHaving constraint to examine the attributes of the referenced entity. The constraint is similar to SQL EXISTS operator.
To demonstrate how the referenceHaving constraint works, let's query for products that have at least one alternative product specified. The alternative products are stored in the relatedProducts reference on the Product entity and have the category attribute set to alternativeProduct. There can be different types of related products other than alternative products, for example spare parts and so on - that's why we need to specify the category attribute in the filtering constraint.

Returns the following result:

If we wanted to query for products that have at least one related product reference of any category type, we could use the following simplified query:

Which returns the following result:

Another frequently used use-case is to query for entities that have at least one reference to another entity with certain primary key. For example, we want to query for products that are related to brand with primary key 66465. This can be achieved by following query:

Which returns the following result:

Entity having

filterConstraint:any+
one or more filter constraints that must be satisfied by the target referenced entity of any of the source entity references identified by the parent referenceHaving constraint
The entityHaving constraint is used to examine the attributes or other filterable properties of the referenced entity. It can only be used within the referenceHaving constraint, which defines the name of the entity reference that identifies the target entity to be subjected to the filtering restrictions in the entityHaving constraint. The filtering constraints for the entity can use entire range of filtering operators.
Let's use our previous example to query for products that relate to brand with particular attribute code:

Which returns the following result:

Facet having

argument:string!
the name of the entity reference that will be subject to the filtering constraints in the second and subsequent arguments
filterConstraint:any*

zero or more filter constraints that identify the facet (reference) that must be present on the entities in the result set

The
filtering constraint is typically placed inside the userFilter constraint container and represents the user's request to drill down the result set by a particular facet. The facetHaving constraint works exactly like the referenceHaving constraint, but works in conjunction with the facetSummary requirement to correctly calculate the facet statistics and impact predictions. When used outside the userFilter constraint container, the facetHaving constraint behaves like the referenceHaving constraint.
To demonstrate the cooperation between the facetHaving constraint inside userFilter and the facetSummary requirement, let's query for products in category e-readers and request the facet summary for reference brand. At the same time, let's pretend that the user has already checked the amazon facet:
As you can see, when the facetHaving constraint is detected in the query and the corresponding facet statistics result is marked as requested, our visualizer chooses to display the facet as checked. The other facet option statistics reflect the fact that the user has already checked the amazon facet option and the predicted numbers are changed accordingly:
Facet summary without facet requestedFacet summary after facet requested
BeforeBeforeAfterAfter

Because the facet summary JSON is quite long and not very readable, we will only show a simplified version of the facet summary result in this documentation. As you can see, the selected facet is checked and the predicted numbers have changed accordingly:

Including children

The
filtering constraint can only be placed within a facetHaving parent constraint and only if the parent constraint refers to the hierarchical entity. This constraint will automatically propagate all child entities of any entity that matches the facetHaving constraint to that parent constraint, as if the facetHaving contained the children directly.
Let's illustrate this situation with some real data. Imagine you have a category Laptops with subcategories Netbooks, Ultrabooks and so on:
Laptops category listingLaptops category listing
Products can be related to any of these sub-categories, or directly to the Laptops category (if they don't match any of the sub-categories). If you generated a facet summary for the category reference, you'd get all the categories with matching products on the same level. But you may want to visualise the category part of the facet summary as a tree using the `hierarchy requirement. When the user selects one of the category options, it should automatically select all subcategories as well, and also change the predicted facet statistics accordingly.
To achieve this, you can use the includingChildren constraint within the facetHaving constraint. The query is also restricted to the products of the ASUS manufacturer so that the facet summary is not too long:
Facet summary without including children requestedFacet summary after facet including children requested
BeforeBeforeAfterAfter
Because the facet summary JSON is quite long and not very readable, we will only show a simplified version of the facet summary result in this documentation. As you can see, not only the facet laptops matched by equals function is checked, but also all of its children. The predicted numbers have changed accordingly:

Including children having

filterConstraint:any+
one or more filter constraints that further narrow down the child entities that will be included in the facetHaving parent constraint
The
filtering constraint is a specialisation of includingChildren that allows you to restrict the child entities that are included in the facetHaving parent constraint. This can be useful if you are using filters in the facetSummary and your selection logic needs to match it.
To better understand how the includingChildrenHaving constraint works, let's look at an example (the query is also restricted to the products of the ASUS manufacturer so that the facet summary is not too long):
Facet summary with standard including children requestedFacet summary with limited facet including children having requested
BeforeBeforeAfterAfter
Because the facet summary JSON is quite long and not very readable, we will only show a simplified version of the facet summary result in this documentation. As you can see, not only the laptops facet matched by the equals function is checked, but also all of its children whose code attribute contains the string books. The predicted numbers have changed accordingly:

Including children except

filterConstraint:any+
one or more filter constraints that excludes specific child entities from being included in the facetHaving parent constraint
The
filtering constraint is a specialisation of includingChildren and exact opposite to [includingChildrenHaving] that allows you to exclude the matched child entities from being included in the facetHaving parent constraint. This can be useful if you are using filters in the facetSummary and your selection logic needs to match it.
You can also combine the includingChildrenExcept constraint with the includingChildrenHaving constraint. In this case, the includingChildrenHaving constraint is evaluated first and the includingChildrenExcept constraint is applied to the result of the includingChildrenHaving constraint.
To better understand how the includingChildrenExcept constraint works, let's look at an example (the query is also restricted to the products of the ASUS manufacturer so that the facet summary is not too long):
Facet summary with standard including children requestedFacet summary with limited facet including children except requested
BeforeBeforeAfterAfter
Because the facet summary JSON is quite long and not very readable, we will only show a simplified version of the facet summary result in this documentation. As you can see, not only the laptops facet matched by the equals function is checked, but also all of its children whose code attribute doesn't contain the string books. The predicted numbers have changed accordingly:

Author: Ing. Jan Novotný

Date updated: 10.2.2025

Documentation Source