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.

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

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.

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.

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+
mandatory one 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
filterConstraint:any
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:any
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
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:

Reference content all

filterConstraint:any
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:any
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
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+

mandatory one or more string arguments representing the names of the references to fetch for the entity

filterConstraint:any
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:any
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
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:any
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:any
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
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:

Author: Ing. Jan Novotný

Date updated: 23.7.2023

Documentation Source