title	perex	date	author	proofreading	preferredLang
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.	23.7.2023	Ing. Jan Novotný	done	evitaql

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

entityFetch(
    requireConstraint:(
        attributeContent|
        attributeContentAll|
        associatedDataContent|
        associatedDataContentAll|
        dataInLocales|
        dataInLocalesAll|
        hierarchyContent|
        priceContent|
        priceContentAll|
        priceContentRespectingFilter|
        referenceContent|
        referenceContentWithAttributes|
        referenceContentAll|
        referenceContentAllWithAttributes
    )*
)

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:

[attributeContent](#attribute-content)
[attributeContentAll](#attribute-content-all)
[associatedDataContent](#associated-data-content)
[associatedDataContentAll](#associated-data-content-all)
[dataInLocales](#data-in-locales)
[dataInLocalesAll](#data-in-locales-all)
[hierarchyContent](#hierarchy-content)
[priceContent](#price-content)
[priceContentAll](#price-content-all)
[priceContentRespectingFilter](#price-content-respecting-filter)
[referenceContent](#reference-content)
[referenceContentAll](#reference-content-all)
[referenceContentWithAttributes](#reference-content-with-attributes)
[referenceContentAllWithAttributes](#reference-content-all-with-attributes)

The entityFetch (evita_query/src/main/java/io/evitadb/api/query/require/EntityFetch.javaEvitaDB.Client/Queries/Requires/EntityFetch.cs) 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).

In the Java APIIn the C# client, including the `entityFetch` requirement in the query changes the output type in the response container. Instead of returning an evita_api/src/main/java/io/evitadb/api/requestResponse/data/structure/EntityReference.javaEvitaDB.Client/Models/Data/Structure/EntityReference.cs for each entity, the evita_api/src/main/java/io/evitadb/api/requestResponse/data/SealedEntity.javaEvitaDB.Client/Models/Data/ISealedEntity.cs type is returned.

Entity group fetch

entityGroupFetch(
    requireConstraint:(
        attributeContent|
        attributeContentAll|
        associatedDataContent|
        associatedDataContentAll|
        dataInLocales|
        dataInLocalesAll|
        hierarchyContent|
        priceContent|
        priceContentAll|
        priceContentRespectingFilter|
        referenceContent|
        referenceContentWithAttributes|
        referenceContentAll|
        referenceContentAllWithAttributes
    )*
)

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:

[attributeContent](#attribute-content)
[attributeContentAll](#attribute-content-all)
[associatedDataContent](#associated-data-content)
[associatedDataContentAll](#associated-data-content-all)
[dataInLocales](#data-in-locales)
[dataInLocalesAll](#data-in-locales-all)
[hierarchyContent](#hierarchy-content)
[priceContent](#price-content)
[priceContentAll](#price-content-all)
[priceContentRespectingFilter](#price-content-respecting-filter)
[referenceContent](#reference-content)
[referenceContentAll](#reference-content-all)
[referenceContentWithAttributes](#reference-content-with-attributes)
[referenceContentAllWithAttributes](#reference-content-all-with-attributes)

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

Entity content

The simplest data you can fetch with an entity is its primary key and type. These are returned by evitaDB with every query, no matter how rich you requested the entity to be.

Getting code and name of the brand

The result of an entity fetch with only basic data

The query returns the following basic data of the Brand entity:

The result of an entity fetch with only basic data

Moreover, you can fetch other fields with entity (which would lead to fetching entire entity body under the hood):

Getting code and name of the brand

The result of an entity fetch with entity body data

The query returns the following entity body of the Brand entity:

The result of an entity fetch with entity body

Attribute content

attributeContent(
    argument:string+
)

argument:string+: one or more mandatory entity or reference attribute names to be fetched along with the entity

The attributeContent (evita_query/src/main/java/io/evitadb/api/query/require/AttributeContent.javaEvitaDB.Client/Queries/Requires/AttributeContent.cs) 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:

Getting code and name of the brand

The result of an entity fetch with named attributes

The query returns the following attributes of the Brand entity:

The result of an entity fetch with named attributes

As you can see, the name is in the English localization thanks to the entityLocaleEquals filter constraint in the query.

To fetch entity or reference attributes, use the attributes field within an entity or reference object and specify the required attribute names as sub-fields. Localized attributes need a locale context in the query, either by using the entityLocaleEquals filter constraint or by explicitly specifying locale argument of the attributes field. Using GraphQL aliases, you can fetch the same attributes in multiple locales in a single query.

All entity attributes are fetched from disk in bulk, so specifying only a few of them in the attributes field only reduces the amount of data transferred over the network. It's not bad to fetch all the attributes of an entity.

To select a code and localized name attribute for the Brand entity, use the following query:

Getting code and name of the brand

The result of an entity fetch with named attributes

As you can see, the name is in the English localization thanks to the entityLocaleEquals filter constraint in the query.

If the locale filter is missing in the query, but you still want to access the localized data, you can specify the locale argument on the attributes field as mentioned above:

Getting localized name of the brand

The result of an entity fetched with explicit locale

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

The result of an entity fetch with localized attributes

If the locale argument was not used in the query, accessing the name attribute would return an error. 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, German, and English name attribute values. The following query will do the job:

Getting code and name of the brand in multiple locales

The result of an entity fetched with multiple locales

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

The result of an entity fetch with localized attributes in multiple locales

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

Attribute content all

attributeContentAll()

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:

Getting code and name of the brand

The result of an entity fetch with all attributes

The query returns the following attributes of the Brand entity:

The result of an entity fetch with all attributes

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

Associated data content

associatedDataContent(
    argument:string+
)

argument:string+: one or more mandatory entity associated data names to be fetched along with the entity

The associatedDataContent (evita_query/src/main/java/io/evitadb/api/query/require/AssociatedDataContent.javaEvitaDB.Client/Queries/Requires/AssociatedDataContent.cs) 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:

Getting code and name of the brand

The result of an entity fetch with named associated data

The query returns the following associated data of the Brand entity:

The result of an entity fetch with named associated data

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.

To fetch entity associated data, use the associatedData field within an entity object and specify required associated data names as sub-fields. Localized associated data need a locale context in the query, either by using the entityLocaleEquals filter constraint or by explicitly specifying locale argument of the associatedData field. Using GraphQL aliases, you can fetch the same associated data in multiple locales in a single query.

To fetch an allActiveUrls and localized localization associated data for the Brand entity, use the following query:

Getting code and name of the brand

The result of an entity fetch with named associated data

The query returns the following associated data of the Brand entity:

The result of an entity fetch with named associated data

If the locale filter is missing in the query, but you still want to access the localized data, you can specify the locale argument on the associatedData field as mentioned above:

Getting localized name of the brand

The result of an entity fetched with explicit locale

The query returns the following localized associated data of the Brand entity:

The result of an entity fetch with localized attributes

If the locale argument was not used in the query, accessing the localization associated data would return an error. In the example above, the localization associated data 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, German, and English localization associated data values. The following query will do the job:

Getting code and name of the brand in multiple locales

The result of an entity fetched with multiple locales

The query returns the following localized associated data of the Brand entity:

The result of an entity fetch with localized attributes in multiple locales

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

Associated data content all

associatedDataContentAll()

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:

Getting code and name of the brand

The result of an entity fetch with all the associated data

The query returns the following associated data of the Brand entity:

The result of an entity fetch with all the associated data

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

Data in locales

dataInLocales(
    argument:string+
)

argument:string+: a mandatory specification of the one or more [locales](https://en.wikipedia.org/wiki/IETF_language_tag) 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 (evita_query/src/main/java/io/evitadb/api/query/require/DataInLocales.javaEvitaDB.Client/Queries/Requires/DataInLocales.cs) requirement is used in two scenarios:

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

Getting localized name of the brand

The result of an entity fetched with explicit locale

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

The result of an entity fetch with localized attributes

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:

Getting code and name of the brand in multiple locales

The result of an entity fetched with multiple locales

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

The result of an entity fetch with localized attributes in multiple locales

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

dataInLocalesAll()

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:

Getting localized name of the brand

The result of an entity fetched in all available locales

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

The result of an entity fetch in all available locales

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

hierarchyContent(
    requireConstraint:(entityFetch|stopAt)*
)

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:

[entityFetch](fetching.md#entity-fetch)
[stopAt](hierarchy.md#stop-at)

The hierarchyContent (evita_query/src/main/java/io/evitadb/api/query/require/HierarchyContent.javaEvitaDB.Client/Queries/Requires/HierarchyContent.cs) 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:

Getting localized name of the brand

The result of an entity fetched with its hierarchy placement

The query returns the following hierarchy of the Category entity:

The result of an entity fetch with hierarchy placement

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:

Getting localized name of the brand

The result of an entity fetched with its hierarchy placement

The query returns the following product with the reference to the full Category entity hierarchy chain:

The result of an entity fetch with hierarchy placement

This quite complex example uses the referenceContent requirement that is described in a following chapter.

To access the information about the hierarchical placement of an entity, use either the parentPrimaryKey or the parents field (or both).

The parentPrimaryKey field returns only the primary key of the direct parent of the entity. If the entity has no parent (i.e. it's a root entity), the field returns null.

The parents fields allows you to access the entire chain of parent entities up to the root of a hierarchy tree. Inside you can use standard entity fields besides the parents field for the fetched parent entities. If no additional arguments are specified the list will contain a entire chain of parent entities up to the root of a hierarchy tree. You can limit the size of the chain by using a stopAt argument - for example, if you're only interested in a direct parent of each entity returned, you can use a stopAt: { distance: 1 } argument. The arguments takes special require constraints to specify on which node to stop the hierarchy traversal. The result is similar to using a parents requirement, 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.

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

Getting localized name of the brand

The result of an entity fetched with its hierarchy placement

The query returns the following hierarchy of the Category entity:

The result of an entity fetch with hierarchy placement

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:

Getting localized name of the brand

The result of an entity fetched with its hierarchy placement

The query returns the following product with the reference to the full Category entity hierarchy chain:

The result of an entity fetch with hierarchy placement

This quite complex example uses a category reference field that is described in a following chapter.

Price content

priceContent(
    argument:enum(NONE|RESPECTING_FILTER|ALL),
    argument:string*
)

argument:enum(NONE|RESPECTING_FILTER|ALL)

optional argument of type evita_query/src/main/java/io/evitadb/api/query/require/PriceContentMode.javaEvitaDB.Client/Queries/Requires/PriceContentMode.cs 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)

</dd>
<dt>argument:string*</dt>
<dd>
    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
</dd>

The priceContent (evita_query/src/main/java/io/evitadb/api/query/require/PriceContent.javaEvitaDB.Client/Queries/Requires/PriceContent.cs) 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.

For entities that have either LOWEST_PRICE or SUM inner record handling, the multiplePricesForSaleAvailable property is returned, indicating whether there are multiple unique prices for sale (grouped by the innerRecordId). It is important to note that it doesn't simply return the count of all prices for sale. Instead, it uses the priceType constraint to determine the uniqueness of each price value. This means that even if there are, say, 3 prices for sale, but they all have the same value, this property will return false. This is especially useful for the UI to determine whether to display a price range or just a single price without having to fetch all prices for sale.

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

Getting entity with prices and reference price

The result of an entity fetched with its selected prices

The query returns the following list of prices of the Product entity:

The result of an entity fetched with its selected prices

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

priceContent(
    argument:string*
)

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 (evita_query/src/main/java/io/evitadb/api/query/require/PriceContent.javaEvitaDB.Client/Queries/Requires/PriceContent.cs) 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:

Getting entity with filtered prices and reference price

The result of an entity fetched with its selected prices and reference price

The query returns the following list of prices of the Product entity:

The result of an entity fetched with its selected prices and reference price

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

priceContentAll()

The priceContentAll (evita_query/src/main/java/io/evitadb/api/query/require/PriceContent.javaEvitaDB.Client/Queries/Requires/PriceContent.cs) 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:

Getting entity with prices and reference price

The result of an entity fetched with all its prices

The query returns the following list of prices of the Product entity:

The result of an entity fetched with all its prices

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.

To fetch price information for an entity, there are several different fields available within an entity: priceForSale, allPricesForSale, multiplePricesForSaleAvailable, price and prices. Each has a different purpose and returns different information.

The price object returns various data that can be formatted by the server for you to display to the user. Specifically, the actual price numbers within the price object can be retrieved formatted according to the specified locale and can even include the currency symbol. This is controlled by the formatted and withCurrency arguments on the respective price object fields. The locale is either resolved from the context of the query (either from a localized unique attribute in the filter or from the entityLocaleEquals constraint in the filter) or can be specified directly on the parent price field by the locale argument.

Prices for sale

The priceForSale field returns a single price object representing the price for sale of the entity. By default, this price is computed based on input filter constraints, more specifically: priceInPriceLists, priceInCurrency and priceValidIn. This is expected to be the most common use case, as it also filters returned entities by these conditions.

Getting entity with price for sale

The result of an entity fetched with its price for sale based on filter constraints

The query returns the following price for sale of the Product entity:

The result of an entity fetched with its price for sale

As you can see, the price for sale matching the filter constraints is returned.

Alternatively, if you don't want to filter entities by the price filter constraints, but you still want to compute and fetch specific price for sale, you can specify which price for sale you want to compute by using the priceList, currency and validIn/validNow arguments directly on the priceForSale field. You can even combine these two approaches, in which case the arguments on the priceForSale fields simply override the corresponding price constraints used in the filter. Theoretically, you can then filter entities by different price conditions than you use to compute the returned price for sale.

Getting entity with price for sale based on custom arguments

The result of an entity fetched with its price for sale based on custom arguments

The query returns the following price for sale of the Product entity:

The result of an entity fetched with its price for sale

As you can see, the price for sale matching the custom arguments is returned.

Similarly, you can use allPricesForSale, which is almost the same as priceForSale, but returns all prices for sale of the entity grouped by the innerRecordId. This usually only makes sense for master products with variants (i.e. LOWEST_PRICE inner record handling) where the master product has prices for all of its variants, where you may want to know (and display) prices for sale for each variant (or some kind of range). For the NONE inner record handling, this will always return at most the actual single price for sale. For the SUM inner record handling, this will return prices for sale for each innerRecordId in the same way as for the FIRST_OCCURNCE, but the use cases are limited.

The returned list of prices is sorted by the price value from the lowest to the highest depending on the priceType constraint used.

There is also the simpler multiplePricesForSaleAvailable field, which returns a boolean indicating whether there are multiple unique prices for sale. It is important to note that it doesn't simply return the count of allPricesForSale. Instead, it uses the priceType constraint to determine the uniqueness of each price value. This means that even if there are, say, 3 prices for sale, but they all have the same value, this field will return false (as opposed to allPricesForSale, which would return all prices). This is especially useful for the UI to determine whether to display a price range or just a single price without having to fetch all prices for sale.

Getting entity with all prices for sale

The result of an entity fetched with all of its prices for sale based on filter constraints

The query returns the following prices for sale of the Product entity:

The result of an entity fetched with all of its prices for sale

As you can see, the price for sale matching the filter constraints is returned, as well as all other prices for sale and flag indicating that there are multiple prices for sale available.

Accompanying prices

There may be times when you need not only the concrete price for sale, but also it's accompanying prices, e.g. reference price (used only for comparison because it's usually higher than the price for sale). This calculation becomes quite complex when we need to handle prices with different inner record handling (LOWEST_PRICE, SUM). In such cases, the accompanying prices must correctly reflect the prices for sale for each inner record.

You can easily calculate these prices with the accompanyingPrice field within the priceForSale or allPricesForSale fields. This way the requested accompanying price will always refer to the parent price for sale (even a custom one). The only possible argument is priceLists, which defines for which price lists the accompanying price should be calculated (the order of the price lists defines a priority in the same way as for the priceForSale and allPricesForSale fields). Other parameters will be inherited from the parent price for sale request.

The following query requests calculation of price for sale as well as a reference price for the calculated price for sale:

Getting entity with price for sale as well as reference price

The result of an entity fetched with its price for sale and reference price

The query returns the following price for sale and reference price of the Product entity:

The result of an entity fetched with its price for sale and reference price

As you can see, the price for sale as well as custom reference price are returned.

The next query is almost identical to the previous one, except that it calculates all the prices for sale and their reference prices for inner records:

Getting entity with all prices for sale as well as reference prices

The result of an entity fetched with its prices for sale and reference prices

The query returns the following all prices for sale and references price of the Product entity:

The result of an entity fetched with its prices for sale and reference prices

As you can see, the prices for sale as well as custom reference prices are returned.

Prices

The prices field returns all prices of the entity. Both indexed and non-indexed.

Getting entity with all prices

The result of an entity fetched with all its prices

The query returns the following list of all prices of the Product entity:

The result of an entity fetched with all its prices

As you can see, the price list is returned.

However, if you only need a specific list of prices, you can filter the returned prices with priceLists and currency arguments. Unlike the other price fields, this field doesn't fall back to data from filter constraints because that would make it difficult to return all the prices.

Getting entity with filtered all prices

The result of an entity fetched with filtered all its prices

The query returns the following list of all prices of the Product entity:

The result of an entity fetched with all its prices

As you can see, the filtered price list is returned.

Reference content

referenceContent(
    argument:enum(ANY|EXISTING)?,
    argument:string*,
    filterConstraint:filterBy?,
    orderConstraint:orderBy?,
    requireConstraint:entityFetch?,
    requireConstraint:entityGroupFetch?,
    requireConstraint:(page|strip)?
)

argument:enum(ANY|EXISTING)?

**Default:** `ANY`

    <p>
    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](../requirements/reference.md#managed-references-behaviour) chapter for more details)
    </p>
</dd>
<dt>argument:string*</dt>
<dd>
    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
</dd>
<dt>filterConstraint:filterBy?</dt>
<dd>
    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`](../filtering/references.md#entity-having) constraint
</dd>
<dt>orderConstraint:orderBy?</dt>
<dd>
    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`](../ordering/references.md#entity-property) constraint
</dd>
<dt>requireConstraint:entityFetch?</dt>
<dd>
    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
</dd>
<dt>requireConstraint:entityGroupFetch?</dt>
<dd>
    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
</dd>
<dt>requireConstraint:(page|strip)?</dt>
<dd>
    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
</dd>

The referenceContent (evita_query/src/main/java/io/evitadb/api/query/require/ReferenceContent.javaEvitaDB.Client/Queries/Requires/ReferenceContent.cs) 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.

Reference fields allow 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). However, reference fields are a bit different from the other entity fields. They are dynamically generated based on the reference schemas, so you can access them directly from the entity object by a schema-defined name, and also, each reference object has a slightly different structure based on the specific reference schema.

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

Getting entity category and brand references

The result of an entity fetched with category and brand references

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

The result of an entity fetched with category and brand 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:

Getting entity parameter values

The result of an entity fetched with referenced parameter bodies and group bodies

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 result of an entity fetched with referenced parameter bodies and group bodies

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:

Getting entity groups and their tags

The result of an entity fetched with referenced groups, their tags and tag categories

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 result of an entity fetched with referenced parameter bodies and group bodies

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

Reference attributes fetching

Besides fetching the referenced entity bodies, you can also fetch the attributes set on the reference itself. Attributes of each reference can be fetched using attributes field where all possible attributes of particular reference are available, similarly to entity attributes.

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:

Getting entity with references and their attributes

The result of an entity fetched with parameter references and their attributes

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:

The result of an entity fetched with all references

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.

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 on reference fields 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:

Getting entity parameter values visible on detail page

The result of an entity fetched with referenced parameter bodies that belong to group visible on detail page

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 result of an entity fetched with referenced parameter bodies that belong to group visible on detail page

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 on reference fields 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:

Getting entity parameter values ordered by name

The result of an entity fetched with referenced parameter ordered by name

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

The result of an entity fetched with referenced parameter ordered by name

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:

Getting entity parameter values count without fetching them

The result of an entity fetched with parameter count only

The returned Product entity will only contain a total number of parameter values and no actual data:

The result of an entity fetched with parameter count only

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:

Getting entity parameter values count without fetching them

The result of an entity fetched with top 3 parameters only

The returned Product entity will contain a maximum of 3 parameters and provide access to a total number of parameter values:

The result of an entity fetched with top 3 parameters only

Reference content all

referenceContentAll(
    filterConstraint:filterBy?,
    orderConstraint:filterBy?,
    requireConstraint:entityFetch?,
    requireConstraint:entityGroupFetch?,
    requireConstraint:(page|strip)?
)

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`](../filtering/references.md#entity-having) 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`](../ordering/references.md#entity-property) 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 (evita_query/src/main/java/io/evitadb/api/query/require/ReferenceContent.javaEvitaDB.Client/Queries/Requires/ReferenceContent.cs) 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:

Getting entity with all references

The result of an entity fetched with all references

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

The result of an entity fetched with all references

Reference content with attributes

referenceContentWithAttributes(
    argument:string*,
    filterConstraint:filterBy?,
    orderConstraint:orderBy?,
    requireConstraint:attributeContent?,
    requireConstraint:entityFetch?,
    requireConstraint:entityGroupFetch?,
    requireConstraint:(page|strip)?
)

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`](../filtering/references.md#entity-having) 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`](../ordering/references.md#entity-property) 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 (evita_query/src/main/java/io/evitadb/api/query/require/ReferenceContent.javaEvitaDB.Client/Queries/Requires/ReferenceContent.cs) 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:

Getting entity with references and their attributes

The result of an entity fetched with parameter references and their attributes

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:

The result of an entity fetched with all references

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

referenceContentAllWithAttributes(
    filterConstraint:filterBy?,
    orderConstraint:orderBy?,
    requireConstraint:attributeContent?,
    requireConstraint:entityFetch?,
    requireConstraint:entityGroupFetch?,
    requireConstraint:(page|strip)?
)

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`](../filtering/references.md#entity-having) 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`](../ordering/references.md#entity-property) 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 (evita_query/src/main/java/io/evitadb/api/query/require/ReferenceContent.javaEvitaDB.Client/Queries/Requires/ReferenceContent.cs) 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:

Getting entity with all of the references and their attributes

The result of an entity fetched with all the references and their attributes

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

The result of an entity fetched with all references

Files

fetching.md

Latest commit

History

fetching.md

File metadata and controls

Entity fetch

Entity group fetch

Entity content

The result of an entity fetch with only basic data

The result of an entity fetch with entity body data

Attribute content

The result of an entity fetch with named attributes

The result of an entity fetch with named attributes

The result of an entity fetched with explicit locale

The result of an entity fetched with multiple locales

Attribute content all

The result of an entity fetch with all attributes

Associated data content

The result of an entity fetch with named associated data

The result of an entity fetch with named associated data

The result of an entity fetched with explicit locale

The result of an entity fetched with multiple locales

Associated data content all

The result of an entity fetch with all the associated data

Data in locales

The result of an entity fetched with explicit locale

The result of an entity fetched with multiple locales

Data in locales all

The result of an entity fetched in all available locales

Hierarchy content

The result of an entity fetched with its hierarchy placement

The result of an entity fetched with its hierarchy placement

The result of an entity fetched with its hierarchy placement

The result of an entity fetched with its hierarchy placement

Price content

The result of an entity fetched with its selected prices

Price content respecting filter

The result of an entity fetched with its selected prices and reference price

Price content all

The result of an entity fetched with all its prices

Prices for sale

The result of an entity fetched with its price for sale based on filter constraints

The result of an entity fetched with its price for sale based on custom arguments

The result of an entity fetched with all of its prices for sale based on filter constraints

Accompanying prices

The result of an entity fetched with its price for sale and reference price

The result of an entity fetched with its prices for sale and reference prices

Prices

The result of an entity fetched with all its prices

The result of an entity fetched with filtered all its prices

Reference content

The result of an entity fetched with category and brand references

Referenced entity (group) fetching

The result of an entity fetched with referenced parameter bodies and group bodies

The result of an entity fetched with referenced groups, their tags and tag categories

Reference attributes fetching

The result of an entity fetched with parameter references and their attributes

Managed References Behaviour

Filtering references

The result of an entity fetched with referenced parameter bodies that belong to group visible on detail page

Ordering references

The result of an entity fetched with referenced parameter ordered by name

Paging / limiting fetched reference count

The result of an entity fetched with parameter count only

The result of an entity fetched with top 3 parameters only

Reference content all

The result of an entity fetched with all references

Reference content with attributes

The result of an entity fetched with parameter references and their attributes

Reference content all with attributes

The result of an entity fetched with all the references and their attributes