Ordering references / by reference attribute
You can sort entities by attributes on references, and you can also sort fetched referenced entities by their attributes or by attributes of references that point to them. Although these are fundamentally different scenarios, both are described in this section.
Reference property
- argument:string!
a mandatory name of the reference whose attribute is to be used for the ordering
- constraint:orderingConstraint+
- one or more ordering constraints that specify the ordering by the reference attribute
The referenceProperty is implicit in requirement referenceContent
In the orderBy clause within the referenceContent requirement,
the referenceProperty constraint is implicit and must not be repeated. All attribute order constraints
in referenceContent automatically refer to the reference attributes, unless the entityProperty
container is used there.
Sorting by reference attribute is not as common as sorting by entity attributes, but it allows you to sort entities that are in a particular category or have a particular group specifically by the priority/order for that particular relationship.
To sort products related to a "sale" group by the orderInGroup attribute set on the reference, you need to issue the
following query:
The example is based on a simple one-to-zero-or-one reference (a product can have at most one reference to a group
entity). The response will only return the products that have a reference to the "sale" group, all of which contain the
orderInGroup attribute (since it's marked as a non-nullable attribute). Because the example is so simple, the returned
result can be anticipated.
Behaviour of zero or one to many references ordering
The situation is more complicated when the reference is one-to-many. What is the expected result of a query that involves ordering by a property on a reference attribute? Is it wise to allow such ordering query in this case?
We decided to allow it and bind it with the following rules:
Non-hierarchical entity
If the referenced entity is non-hierarchical, and the returned entity references multiple entities, only
the reference with the lowest primary key of the referenced entity, while also having the order property set, will be
used for ordering.
Let's extend our previous example so that it returns products that refer not only to the group "sale", but also to the group "new":
The result will contain first products referring to a "new" group which has the lowest primary key, and then products
referring to a "sale" group. The order of products within each group will be determined by the orderInGroup attribute.
Hierarchical entity
If the referenced entity is hierarchical and the returned entity references multiple entities, the reference used
for ordering is the one that contains the order property and is the closest hierarchy node to the root of the filtered
hierarchy node.
It sounds complicated, but it's really quite simple. If you list products of a certain category and at the same time
order them by a property orderInCategory set on the reference to the category, the first products will be those
directly related to the category, ordered by orderInCategory, followed by the products of the first child category,
and so on, maintaining the depth-first order of the category tree.
This behaviour is best illustrated by a following example. Let's list products in the Accessories category ordered
by the orderInCategory attribute on the reference to the category:
The result will first contain products directly related to the Accessories category, ordered by orderInCategory in
ascending order, then products Christmas electronics (which is the first child of the Accessories category with
the least primary key), then Smart wearable (which has no directly related products), then Bands (which is the first
child of the Smart wearable category), and so on. The order follows the order of the categories in the following
image:
If so, please vote for the issue #160 on GitHub. This issue won't
be resolved until there is a demand for it.
Entity property
- constraint:orderingConstraint+
- one or more ordering constraints that specify the ordering by the referenced entity attributes
The entityProperty ordering constraint can only be used within the referenceContent
requirement. It allows to change the context of the reference ordering from attributes of the reference itself to
attributes of the entity the reference points to.
In other words, if the Product entity has multiple references to ParameterValue entities, you can sort those
references by, for example, the order or name attribute of the ParameterValue entity. Let's see an example:
Entity group property
- constraint:orderingConstraint+
- one or more ordering constraints that specify the ordering by the referenced entity group attributes
The entityGroupProperty ordering constraint can only be used within the referenceContent requirement. It
allows the context of the reference ordering to be changed from attributes of the reference itself to attributes of
the group entity within which the reference is aggregated.
In other words, if the Product entity has multiple references to ParameterValue entities that are grouped by their
assignment to the Parameter entity, you can sort those references primarily by the name attribute of the grouping
entity, and secondarily by the name attribute of the referenced entity. Let's look at an example: