evitaDB - Fast e-commerce database
logo
page-background

Fetching

Fetch request constraints help control the amount of data returned in the query response. This technique is used to reduce the amount of data transferred over the network and to reduce the load on the server. Fetching is similar to joins and column selection in SQL, but is inspired by data fetching in the GraphQL protocol by incrementally following the relationships in the data.

If no content requirement is used in the query, the result will contain only the primary key of the entity. While this may be sufficient for some queries, it is usually necessary to fetch some data from the entity or even other entities related to the entity. For this purpose, the entityFetch request and nested content requests described in this section are used:

Entity fetch

requireConstraint:(...)*

optional one or more constraints allowing you to instruct evitaDB to fetch the entity contents; one or all of the constraints may be present:

The entityFetch (
) requirement is used to trigger loading one or more entity data containers from the disk by its primary key. This operation requires a disk access unless the entity is already loaded in the database cache (frequently fetched entities have higher chance to stay in the cache).

Entity group fetch

requireConstraint:(...)*

optional one or more constraints allowing you to instruct evitaDB to fetch the group entity contents; one or all of the constraints may be present:

Same as the entityFetch but used for fetching entities that represents reference group.

Two content requirements of the same kind in one entityFetch

Two content requirements of the same kind can easily end up next to each other in a single entityFetch - the query may be assembled from several places in your code, or you may have added a requirement next to a fetch-all shorthand that already contains one of the same kind. Such a pair is not an error and neither half of it is lost. The requirements are folded into the single requirement the query is executed with, and wherever the two have a superset the rule is the same: the superset wins. Where they have none - two different selections of the same references, say - evitaDB refuses the query instead of silently picking one; the cases are listed at the end of this section.
The query above fetches code and name, exactly as attributeContent("code", "name") would. Each kind of content requirement has its own notion of a superset:

Folding referenceContent per reference

The key of a referenceContent is the set of references it addresses - a single reference name, the set of names it lists, or, when the reference is fetched under its own logical instance name, that name as well. Only requirements sharing a key are folded, and within one key:
  • the reference attributes and the nested entityFetch / entityGroupFetch bodies are united, recursively, so that nothing either side asked for is lost
  • a filterBy or a chunking (page / strip) constraint has to be the same on both sides, or absent from both. The two requirements share a single output slot, and a restriction only one of them carries has no superset: dropping it would return the references the restricting side asked to exclude, honouring it would hide the ones the unrestricted side asked for. Both readings change what comes back, so evitaDB refuses the pair instead of picking one for you - write the restriction on both sides, or on neither
  • an orderBy present on one side only is kept. This is the single exception to the rule above, and it is safe for one reason: an order shapes the sequence of the references without dropping any of them, so keeping the only order present hides nothing from either side
  • a disagreement on the managed references behaviour narrows to EXISTING, so a request to suppress references pointing at missing entities is never lost by folding
They are folded per name. referenceContent("a", "b") written next to referenceContent("b", "c") projects each requirement onto every name it lists, and the projections sharing a name are folded by the rules above - so b is fetched with the union of both bodies while a and c keep theirs.
Because these rules govern the requirements you write, and the engine's own are not among them. Internally it may load more references than your query projects - evaluating a referenceHaving filter or an ordering by a reference property in memory needs the reference records themselves, so the query planner adds a requirement of its own for that reference, without your filter, order or page.
That widening is invisible: whatever the engine loaded, the response is assembled from the requirements you wrote, so the references you get back - and their order and page - are exactly the ones your query asked for. A referenceContent that filters or pages the very reference a referenceHaving or an ordering also names is therefore perfectly ordinary, and is never refused as a disagreement with the requirement the planner added.
A referenceContentAll requirement and a name-specific referenceContent("brand") carry different keys and are therefore never folded together. Both stay in effect - the name-specific requirement decides how brand is fetched and the wildcard one remains the fallback for every other reference:
The query above fetches brand without its reference attributes, and every other reference with them.

Folding accompanyingPriceContent per price name

The key of an accompanyingPriceContent is the name of the price it calculates, which is what makes several of them in one entityFetch the normal case - two requirements naming different prices calculate two independent prices and both survive. Two requirements naming the same price are folded into one when they list exactly the same price lists.
A requirement carrying no price lists does not ask for an empty sequence - it defers to the query level defaultAccompanyingPriceLists. Requesting one price name once in that form and once with its own price lists is refused, and deliberately so even when the default currently resolves to exactly the same price lists:

The two agree only by coincidence of what the default currently is. They stop agreeing the moment either the default or the explicit sequence changes - and price lists are typically assembled from variables, so that change is a routine edit somewhere else in the code. Nothing in the query would show the reader that the two requirements had drifted apart, so the pair is refused while the disagreement is still hypothetical. State the price lists on both requirements, or defer on both.

Note that the first argument of accompanyingPriceContent is the name the price is labelled with in the result, not a price list: accompanyingPriceContent("default", "reference") calculates the price named default from the single price list reference.

Requirements that cannot be reconciled

Some pairs have no superset at all, and evitaDB refuses them with an exception instead of letting one of them silently win:

  • two referenceContent requirements for one reference disagreeing about the filterBy or the chunking constraint - whether the two carry a different one or only one of them carries it at all. A filter and a page each select a subset of the references, and no union of two different selections - "everything" included - preserves both intents
  • two referenceContent requirements for one reference carrying different orderBy constraints. An order sequences the references rather than selecting them, so an order carried by a single side is kept rather than refused; only two genuinely different orders contradict each other
  • two hierarchyContent requirements bounding the parent chain with different stopAt constraints
  • a priceContent(NONE) requirement beside one that does fetch prices. The other two modes differ in how many prices come back and the wider one answers both, but NONE is the opposite instruction rather than a third width - widening it would answer a request for no prices with prices. This is what makes entityFetchAllContentAnd(priceContent(NONE)) an error rather than a way to spell "everything except prices": the all-content shorthand already contains priceContentAll(), and by the time the two are folded neither carries any record of having come from a shorthand. List the requirements you want instead
  • two accompanyingPriceContent requirements calculating one price from different price lists, including two lists that differ only in their order - the sequence is a priority order and any merge would invent a priority neither side asked for - and equally when one of them names its price lists while the other defers them to defaultAccompanyingPriceLists

Attribute content

argument:string+

one or more mandatory entity or reference attribute names to be fetched along with the entity

The attributeContent (
) requirement is used to retrieve one or more entity or reference attributes. Localized attributes are only fetched if there is a locale context in the query, either by using the entityLocaleEquals filter constraint or the dataInLocales require constraint.
All entity attributes are fetched from disk in bulk, so specifying only a few of them in the attributeContent requirement only reduces the amount of data transferred over the network. It's not bad to fetch all the attributes of an entity using attributeContentAll.
To select a code and localized name attribute for the Brand entity, use the following query:
The query returns the following attributes of the Brand entity:
As you can see, the name is in the English localization thanks to the entityLocaleEquals filter constraint in the query.

Attribute content all

This constraint is a shorthand for the attributeContent constraint with all entity or reference attributes defined in the entity or reference schema. This constraint variant is an alternative to using the SQL wildcard * in the SELECT clause.
To select all non-localized attributes for the Brand entity, use the following query:
The query returns the following attributes of the Brand entity:

All the localized attributes are missing, because there is no localization context present in the query.

Associated data content

argument:string+

one or more mandatory entity associated data names to be fetched along with the entity

The associatedDataContent (
) requirement is used to retrieve one or more entity associated data. Localized associated data are only fetched if there is a locale context in the query, either by using the entityLocaleEquals filter constraint or the dataInLocales require constraint.
To select an allActiveUrls and localized localization associated data for the Brand entity, use the following query:
The query returns the following associated data of the Brand entity:
As you can see, the localization related data item contains the texts in the English localization thanks to the entityLocaleEquals filter constraint in the query. The allActiveUrls is a non-localized related data item that contains active URL addresses for a particular brand in different languages that could be used to generate a language selection menu for this brand record.

Associated data content all

This constraint is a shorthand for the associatedDataContent constraint with all entity associated data defined in the entity schema. This constraint variant is an alternative to using the SQL wildcard * in the SELECT clause.
Because the associated data is expected to store large amounts of unstructured data, each of the data is stored as a separate record. You should always fetch only the associated data you need, as fetching all of it will slow down the processing of the request. The associatedDataContentAll request should only be used for debugging or exploratory purposes and should not be included in production code.
To select all non-localized associated data for the Brand entity, use the following query:
The query returns the following associated data of the Brand entity:

All the localized associated data are missing, because there is no localization context present in the query.

Data in locales

argument:string+
a mandatory specification of the one or more locales in which the localized entity or reference localized attributes and entity associated data will be fetched; examples of a valid language tags are: en-US or en-GB, cs or cs-CZ, de or de-AT, de-CH, fr or fr-CA etc.
The dataInLocales (
) requirement is used in two scenarios:
  1. there is no locale context in the filter part of the query, because you don't want to exclude entities without the requested locale from the result, but you want to fetch the localized data in one or more languages if they are available for the entity or reference
  2. there is a locale context in the filter part of the query, but you want to fetch the localized data in different or additional languages than the one specified in the locale context

If the locale filter is missing in the query, but you still want to access the localized data, you can use the following query:

The query returns the following localized attributes of the Brand entity:
If the dataInLocales requirement was not used in the query, accessing the name attribute would throw an exception. In the example above, the name attribute is accessible in the Czech locale even though the entityLocaleEquals filter constraint was not used at all.
To demonstrate the second scenario, let's say you want to filter a brand that has a Czech localization, but you want to get Czech and English name attribute values. The following query will do the job:
The query returns the following localized attributes of the Brand entity:

As you can see, the localized attributes are available both for the Czech and English locales. The entity is still present in the result, because the filter constraint enforces the Czech locale context, which is satisfied by the entity.

Data in locales all

The dataInLocalesAll allows you to retrieve attributes and associated data in all available locales. This is usually useful in scenarios where you are publishing the data from the primary data source and you need to create/update all the data in one go. If you are accessing the data as a client application, you will probably always want to fetch the data in a specific locale, which means you will use the dataInLocales requirement with a single locale or entityLocaleEquals filtering constraint instead.

To fetch entity in all locales available, use the following query:

The query returns the following localized attributes of the Brand entity:

As you can see, the entity is returned with the Czech and English locales for which the localized attributes or associated data are available.

Hierarchy content

argument:enum(COMPLETE|MATCHING)?

Default: MATCHING

optional argument that decides what happens to a parent entity whose requested body cannot be fetched; the default MATCHING cuts the chain just below such a parent, so that every returned parent carries the body you asked for, while COMPLETE keeps such a parent in the chain as a bodyless pointer and continues the traversal above it (see hierarchy parents behaviour chapter for more details); the argument has no effect unless the entityFetch constraint is present, because without it no parent body is requested and nothing can fail to be fetched

requireConstraint:(entityFetch|stopAt)*

optional one or more constraints that allow you to define the completeness of the hierarchy entities and the scope of the traversed hierarchy tree; any or both of the constraints may be present:

The hierarchyContent (
) requirement allows you to access the information about the hierarchical placement of the entity.
If no additional constraints are specified, entity will contain a full chain of parent primary keys up to the root of a hierarchy tree. You can limit the size of the chain by using a stopAt constraint - for example, if you're only interested in a direct parent of each entity returned, you can use a stopAt(distance(1)) constraint. The result is similar to using a parents constraint, but is limited in that it doesn't provide information about statistics and the ability to list siblings of the entity parents. On the other hand, it's easier to use - since the hierarchy placement is directly available in the retrieved entity object.
If you provide a nested entityFetch constraint, the hierarchy information will contain the bodies of the parent entities in the required width. The attributeContent inside the entityFetch allows you to access the attributes of the parent entities, etc. Not every parent is guaranteed to be able to provide the body you ask for, though - the hierarchy parents behaviour argument decides what the chain looks like when one of them can't.

To fetch an entity with basic hierarchy information, use the following query:

The query returns the following hierarchy of the Category entity:
The Category entity is returned with the hierarchy information up to the root of the hierarchy tree.
To demonstrate a more complex and useful example let's fetch a product with its category reference and for the category fetch its full hierarchy placement up to the root of the hierarchy tree with code and name attributes of these categories. The query looks like this:
The query returns the following product with the reference to the full Category entity hierarchy chain:
This quite complex example uses the referenceContent requirement that is described in a following chapter.

A parent entity may sit in the hierarchy tree and still be unable to provide the body you asked for. There are three ways this happens:

  • the parent holds no data in the locale the query filters by - you asked for the English variant of the tree with the entityLocaleEquals constraint and one of the parent categories exists in Czech only;
  • the parent was deleted, while the entity below it still refers to its primary key;
  • the parent primary key never belonged to an entity - evitaDB doesn't enforce referential integrity on the parent primary key, so an entity may legitimately be created with a parent that is going to be indexed later.
The parent axis is walked from the direct parent upwards, and
the first optional argument of the hierarchyContent requirement
decides what the walk does when it reaches such a parent:
  • MATCHING: the chain is cut just below that parent - neither it nor anything above it is returned. Every parent you receive therefore carries the body you asked for, at the price of the ones you never see.
  • COMPLETE: every parent is returned. The one that can't provide a body is reported as a bodyless pointer carrying nothing but its primary key, and the traversal continues above it. A parent with a body may therefore appear above a bodyless one, and your code has to be prepared for that.
The last two cases - a deleted parent, and a parent primary key that never belonged to an entity - break the tree at that point, so there is nothing above the break for evitaDB to reach in the first place. COMPLETE then ends the chain at that bodyless pointer instead of continuing past it, and MATCHING ends it just below. The pointer is still worth having: it tells you the entity's ancestry goes on beyond what evitaDB is able to show you, which is precisely what MATCHING hides.
MATCHING is the default, so an existing query keeps returning exactly what it returned before this argument existed. Reach for COMPLETE when you need the parents above an unfetchable one - a breadcrumb that has to reach the root even though one of its nodes isn't translated is the typical case - and be ready to render the bodyless pointers it brings with it.
The behaviour is defined in terms of the requested body, so it decides something only when there is a body to request.
A hierarchyContent() with no nested entityFetch constraint
requests no parent body at all, nothing can fail to be fetched, and the whole chain of parent primary keys the entity has - up to the root, or up to a break in the tree - is returned under either behaviour.
A caveat on combining two hierarchyContent requirements. Two hierarchyContent requirements in a single entityFetch are reduced to one, and the reduction widens rather than narrows. The entityFetchAllContent() shortcut already contains a bare hierarchyContent(), so writing entityFetchAllContentAnd(hierarchyContent(stopAt(distance(1)))) produces exactly such a pair - and because an absent bound is the wider of the two, the stopAt(distance(1)) bound is dropped and the whole parent chain is fetched. This is the same widening that makes attributeContentAll swallow an attributeContent("code") written beside it. If you need the bound, don't ask for the full entity content next to it.
The parents behaviour, on the other hand, survives the reduction: a requirement that asks for no parent body states no preference, so entityFetchAllContentAnd(hierarchyContent(COMPLETE, entityFetch(attributeContentAll()))) really does fetch the complete chain. Only when both requirements ask for parent bodies and name different behaviours does the query fail - as it also does when both carry a stopAt and the two bounds differ. Neither behaviour is a superset of the other, so evitaDB refuses to guess which one you meant instead of silently picking one.

Price content

argument:enum(NONE|RESPECTING_FILTER|ALL)
optional argument of type
enum allowing you to specify whether to fetch all, selected or no price records for the entity:
  • NONE: no prices will be fetched for the entity (even if the filter contains a price constraint)
  • RESPECTING_FILTER: only a prices in price lists selected by a filter constraint will be fetched
  • ALL: all prices of the entity will be fetched (regardless of the price constraint in a filter)
argument:string*

optional one or more string arguments representing price list names to add to the list of price lists passed in a filter price constraint, which together form a set of price lists for which to fetch prices for the entity

The priceContent (
) requirement allows you to access the information about the prices of the entity.
If the RESPECTING_FILTER mode is used, the priceContent requirement will only retrieve the prices selected by the priceInPriceLists constraint. If the enum NONE is specified, no prices are returned at all, if the enum ALL is specified, all prices of the entity are returned regardless of the priceInPriceLists constraint in the filter (the constraint still controls whether the entity is returned at all).
You can also add additional price lists to the list of price lists passed in the priceInPriceLists constraint by specifying the price list names as string arguments to the priceContent requirement. This is useful if you want to fetch non-indexed prices of the entity that cannot (and are not intended to) be used to filter the entities, but you still want to fetch them to display in the UI for the user.

To get an entity with prices that you filter by, use the following query:

The query returns the following list of prices of the Product entity:
As you can see, the prices for the filtered price lists employee-basic-price and basic are returned. This query is equivalent to using the priceContentRespectingFilter alias.

Price content respecting filter

argument:string*

optional one or more string arguments representing price list names to add to the list of price lists passed in a filter price constraint, which together form a set of price lists for which to fetch prices for the entity

The priceContentRespectingFilter (
) requirement allows you to access the information about the prices of the entity. It fetches only the prices selected by the priceInPriceLists constraint.
You can also add additional price lists to the list of price lists passed in the priceInPriceLists constraint by specifying the price list names as string arguments to the priceContent requirement. This is useful if you want to fetch non-indexed prices of the entity that cannot (and are not intended to) be used to filter the entities, but you still want to fetch them to display in the UI for the user.
This requirement is only a variation of the generic priceContent requirement.
To get an entity with prices that you filter by and a reference price on top of it, use the following query:
The query returns the following list of prices of the Product entity:
As you can see, the prices for the filtered price lists employee-basic-price and basic are returned, as well as the price in the reference price lists requested by the priceContent requirement.

Price content all

The priceContentAll (
) requirement allows you to access all of the entity's price information regardless of the filtering constraints specified in the query.
This requirement is only a variation of the generic priceContent requirement.

To get an entity with all of the entity's prices, use the following query:

The query returns the following list of prices of the Product entity:
As you can see, all prices of the entity are returned in all available currencies - not only the filtered price lists employee-basic-price and basic. Thanks to priceContentAll you have an overview of all prices of the entity.

Reference content

argument:enum(ANY|EXISTING)?

Default: ANY

optional argument, if set to EXISTING only existing references to managed entities are returned; the default behavior is set to ANY, which returns all references set to the entity, regardless of whether they point to to existing or non-existing entities (see managed references behaviour chapter for more details)

argument:string*
optional zero or more string arguments representing the names of the references to fetch for the entity; if more than one name is given in the argument, any corresponding constraints in the same referenceContent container will apply to all of them; if none are given, all references are fetched and any corresponding constraints in the same referenceContent container will apply to all of them
filterConstraint:filterBy?
optional filter constraint that allows you to filter the references to be fetched for the entity; the filter constraint is targeted at the reference attributes, so if you want to filter by properties of the referenced entity, you must use the entityHaving constraint
orderConstraint:orderBy?
optional ordering constraint that allows you to sort the fetched references; the ordering constraint is targeted at the reference attributes, so if you want to order by properties of the referenced entity, you must use the entityProperty constraint
requireConstraint:entityFetch?
optional requirement constraint that allows you to fetch the referenced entity body; the entityFetch constraint can contain nested referenceContent with an additional entityFetch / entityGroupFetch constraints that allows you to fetch the entities in a graph-like manner to an "infinite" depth
requireConstraint:entityGroupFetch?
optional requirement constraint that allows you to fetch the referenced entity group body; the entityGroupFetch constraint can contain nested referenceContent with an additional entityFetch / entityGroupFetch constraints that allows you to fetch the entities in a graph-like manner to an "infinite" depth
requireConstraint:(page|strip)?
optional requirement constraint that allows you to limit the number of returned references if there is a large number of them; the page constraint allows you to paginate the references, while the strip constraint allows you specify offset and limit for the returned references
The referenceContent (
) requirement allows you to access the information about the references the entity has towards other entities (either managed by evitaDB itself or by any other external system). This variant of referenceContent doesn't return the attributes set on the reference itself - if you need those attributes, use the referenceContentWithAttributes variant of it.

To get an entity with reference to categories and brand, use the following query:

The returned Product entity will contain primary keys of all categories and brand it references:

Referenced entity (group) fetching

In many scenarios, you'll need to fetch not only the primary keys of the referenced entities, but also their bodies and the bodies of the groups the references refer to. One such common scenario is fetching the parameters of a product:

The returned Product entity will contain a list of all parameter codes it references and the code of the group to which each parameter belongs:
The example lists only a code attribute for each referenced entity and group for brevity, but you can retrieve any of their content - associated data, prices, hierarchies, or nested references as well.

To demonstrate graph-like fetching of multiple referenced levels, let's fetch a product with its group assignment and for each group fetch the group's tags and for each tag fetch the tag's category name. The query contains 4 levels of related entities: product → group → tag → tag category. The query looks like this:

The returned Product entity will contain a list of all groups it references, for each group a list of all its tags and for each tag its category assignment:

The tag category is not an entity managed by evitaDB and that's why we retrieve only its primary key.

Managed References Behaviour

evitaDB is meant to be a secondary database for fast read access, so it doesn't enforce foreign key constraints on references. This means that you can have references to entities that don't exist in evitaDB - maybe because they will be indexed later. In certain situations and clients, it may be cumbersome to handle references pointing to non-existent entities, and that's why you can instruct evitaDB to do it for you. If you set the first optional argument of the referenceContent constraint to EXISTING, evitaDB will ensure that only references to existing entities are returned.

Additional filtering of these references is not free, so it's not the default behavior. Even if you fetch the entity to make some changes to it, you may want to see all references, even those pointing to non-existing entities. Otherwise, you might send unnecessary upsert mutations to the server.

Filtering references

Sometimes your entities have a lot of references and you don't need all of them in certain scenarios. In this case, you can use the filter constraint to filter out the references you don't need.

The
referenceContent
filter implicitly targets the attributes on the same reference it points to, so you don't need to specify a referenceHaving constraint. However, if you need to declare constraints on referenced entity attributes, you must wrap them in the entityHaving container constraint.
For example, your product has got a lot of parameters, but on product detail page you need to fetch only those that are part of group which contains an attribute isVisibleInDetail set to TRUE.To fetch only those parameters, use the following query:
The returned Product entity will contain a list of all parameter codes it references and the code of the group to which each parameter belongs:
As you can see only the parameters of the groups having isVisibleInDetail set to TRUE are returned.

Ordering references

By default, the references are ordered by the primary key of the referenced entity. If you want to order the references by a different property - either the attribute set on the reference itself or the property of the referenced entity - you can use the order constraint inside the referenceContent requirement.
The
referenceContent
ordering implicitly targets the attributes on the same reference it points to, so you don't need to specify a referenceProperty constraint. However, if you need to declare constraints on referenced entity attributes, you must wrap them in the entityProperty container constraint.

Let's say you want your parameters to be ordered by an English name of the parameter. To do this, use the following query:

The returned Product entity will contain a list of all parameters in the expected order:

Paging / limiting fetched reference count

By default, all references of the entity with the requested reference name are returned with the entity. If the possible number of references is large, you can limit the number of references returned by using page or strip as the last constraint of the referenceContent container and access them in a paginated manner. You can combine paging with filterBy and orderBy constraints to your advantage.
Avoid fetching too much data if you don't need it; your queries will be faster if you only fetch the data you really need. In server/client communication over the network, every byte counts. So if you only need to know if there are references of a certain type, use strip with limit: 0 or page with size: 0 to fetch only the number of references and avoid fetching the actual data.

Let's say you need only to check whether there is any parameter for the product. To do this, use the following query:

The returned Product entity will only contain a total number of parameter values and no actual data:
If the number of possible parameter values is large, you'd better limit the returned count to the size that can actually be processed/rendered by the client. In this situation you'd probably want to list the most important ones first, so the orderBy constraint should be handy:
The returned Product entity will contain a maximum of 3 parameters and provide access to a total number of parameter values:

Reference content all

filterConstraint:filterBy?
optional filter constraint that allows you to filter the references to be fetched for the entity; the filter constraint is targeted at the reference attributes, so if you want to filter by properties of the referenced entity, you must use the entityHaving constraint
orderConstraint:orderBy?
optional ordering constraint that allows you to sort the fetched references; the ordering constraint is targeted at the reference attributes, so if you want to order by properties of the referenced entity, you must use the entityProperty constraint
requireConstraint:entityFetch?
optional requirement constraint that allows you to fetch the referenced entity body; the entityFetch constraint can contain nested referenceContent with an additional entityFetch / entityGroupFetch constraints that allows you to fetch the entities in a graph-like manner to an "infinite" depth
requireConstraint:entityGroupFetch?
optional requirement constraint that allows you to fetch the referenced entity group body; the entityGroupFetch constraint can contain nested referenceContent with an additional entityFetch / entityGroupFetch constraints that allows you to fetch the entities in a graph-like manner to an "infinite" depth
requireConstraint:(page|strip)?
optional requirement constraint that allows you to limit the number of returned references if there is a large number of them; the page constraint allows you to paginate the references, while the strip constraint allows you specify offset and limit for the returned references
The referenceContentAll (
) is a variation of the referenceContent requirement that allows you to access the information about the references the entity has towards other entities (either managed by evitaDB itself or by any other external system). The referenceContentAll is a shortcut that simply targets all references defined for the entity. It can be used to quickly discover all the possible references of an entity.
For detail information, see the referenceContent requirement chapter.

To get an entity with all the references available, use the following query:

The returned Product entity will contain primary keys and codes of all its references:

Reference content with attributes

argument:string*
optional zero or more string arguments representing the names of the references to fetch for the entity; if more than one name is given in the argument, any corresponding constraints in the same referenceContent container will apply to all of them; if none are given, all references are fetched and any corresponding constraints in the same referenceContent container will apply to all of them
filterConstraint:filterBy?
optional filter constraint that allows you to filter the references to be fetched for the entity; the filter constraint is targeted at the reference attributes, so if you want to filter by properties of the referenced entity, you must use the entityHaving constraint
orderConstraint:filterBy?
optional ordering constraint that allows you to sort the fetched references; the ordering constraint is targeted at the reference attributes, so if you want to order by properties of the referenced entity, you must use the entityProperty constraint
requireConstraint:attributeContent?
optional requirement constraint that allows you to limit the set of reference attributes to be fetched; if no attributeContent constraint is specified, all attributes of the reference will be fetched
requireConstraint:entityFetch?
optional requirement constraint that allows you to fetch the referenced entity body; the entityFetch constraint can contain nested referenceContent with an additional entityFetch / entityGroupFetch constraints that allows you to fetch the entities in a graph-like manner to an "infinite" depth
requireConstraint:entityGroupFetch?
optional requirement constraint that allows you to fetch the referenced entity group body; the entityGroupFetch constraint can contain nested referenceContent with an additional entityFetch / entityGroupFetch constraints that allows you to fetch the entities in a graph-like manner to an "infinite" depth
requireConstraint:(page|strip)?
optional requirement constraint that allows you to limit the number of returned references if there is a large number of them; the page constraint allows you to paginate the references, while the strip constraint allows you specify offset and limit for the returned references
The referenceContentWithAttributes (
) is a variation of the referenceContent requirement that allows you to access the information about the references the entity has towards other entities (either managed by evitaDB itself or by any other external system) and the attributes set on those references. The referenceContentWithAttributes allows you to specify the list of attributes to fetch, but by default it fetches all attributes on the reference.
For detail information, see the referenceContent requirement chapter.

To obtain an entity with reference to a parameter value that reveals which association defines the unique product-variant combination and which parameter values are merely informative, use the following query:

The returned Product entity will contain references to parameter values and for each of it, it specifies the type of the relation between the product and the parameter value:
As you can see, the cellular-true, display-size-10-2, ram-memory-4, rom-memory-256 and color-yellow parameter values define the product variant, while the other parameters only describe the additional properties of the product.

Reference content all with attributes

filterConstraint:filterBy?
optional filter constraint that allows you to filter the references to be fetched for the entity; the filter constraint is targeted at the reference attributes, so if you want to filter by properties of the referenced entity, you must use the entityHaving constraint
orderConstraint:orderBy?
optional ordering constraint that allows you to sort the fetched references; the ordering constraint is targeted at the reference attributes, so if you want to order by properties of the referenced entity, you must use the entityProperty constraint
requireConstraint:attributeContent?
optional requirement constraint that allows you to limit the set of reference attributes to be fetched; if no attributeContent constraint is specified, all attributes of the reference will be fetched
requireConstraint:entityFetch?
optional requirement constraint that allows you to fetch the referenced entity body; the entityFetch constraint can contain nested referenceContent with an additional entityFetch / entityGroupFetch constraints that allows you to fetch the entities in a graph-like manner to an "infinite" depth
requireConstraint:entityGroupFetch?
optional requirement constraint that allows you to fetch the referenced entity group body; the entityGroupFetch constraint can contain nested referenceContent with an additional entityFetch / entityGroupFetch constraints that allows you to fetch the entities in a graph-like manner to an "infinite" depth
requireConstraint:(page|strip)?
optional requirement constraint that allows you to limit the number of returned references if there is a large number of them; the page constraint allows you to paginate the references, while the strip constraint allows you specify offset and limit for the returned references
The referenceContentAllWithAttributes (
) is a variation of the referenceContent requirement that allows you to access the information about the references the entity has towards other entities (either managed by evitaDB itself or by any other external system) and the attributes set on those references. The referenceContentAllWithAttributes allows you to specify the list of attributes to fetch, but by default it fetches all attributes on the reference. It doesn't allow you to specify the reference names - because it targets all of them, and so you can specify the constraints and the attributes that are shared by all of the references. This constraint is only useful in exploration scenarios.
For detail information, see the referenceContent requirement chapter.

To obtain an entity with all the references and their attributes, use the following query:

The returned Product entity will contain all the references and the attributes set on this relation:

Accompanying price content

argument:string?
Optional specification of an accompanying price name that should be used to distinguish this accompanying price from others. If not specified, the default accompanying price name is used.
argument:string*
An optional prioritized list of price list names, that should be used to calculate the accompanying price. If not specified, the defaultAccompanyingPriceLists requirement is used to specify this prioritized list of price lists. Otherwise, an error will occur.
The
requirement defines which other prices should be calculated beside the price for sale. These prices are closely tied to the price for sale and cannot be calculated independently. Prices can be calculated from both indexed and non-indexed price lists. They follow the same calculation rules as the price for sale, but are calculated only from the entities that are involved in the price for sale calculation.

You may calculate multiple accompanying prices at once, but you must specify the name of each accompanying price in order to distinguish them one from another.

Let's demonstrate this principle with a complex example:

For our example, we selected a product using the LOWEST_PRICE inner record handling strategy to calculate the sale price. We also requested two accompanying prices.
  1. the first has no name and no price lists specified, it will be calculated as the default accompanying price using the price list sequence defined in the defaultAccompanyingPriceLists requirement;
  2. the second has the name special and uses the price lists employee-basic-price and b2b-basic-price to calculate the price;

The results of the query that calculates these prices are shown below:

Because the LOWEST_PRICE strategy was used, the sale price is calculated separately for each inner record of the product, and then the lowest price is selected. Then, the accompanying prices are calculated, but only from prices that share the same inner record as the sale price.
If the SUM strategy was used, the accompanying prices would only be calculated for prices relating to inner records that are part of the price-for-sale calculation. Therefore, even if there are prices for price lists used in the default or special accompanying prices, they would not be part of the default or special sum price because their price-for-sale counterpart does not exist.

Author: Ing. Jan Novotný

Date updated: 5.5.2026

Documentation Source