This type of aggregates are dedicated to displaying counters in selection filters (lists or tree). These counters display the number of resources selected by the filters, as well as the number of resources that would be selected if the corresponding value was selected in the filter.

See the description of the notion of aggregates in the chapter Accessing data | Aggregates .

Principle

The principle is to automatically build aggregated selection queries by combining specific fragments per filter. A fragment represents a filter, as queries, among which we have a selection query for the aggregate (the property, the filter operator and the selection to compute the counter, which thus define a query), a constraint query and an unconstrained aggregate query. None of the three is mandatory.

The global query definition is a map that associates keys with these fragments. Keys are hierarchical paths that describe how queries will be combined to form a global query.

API End point

• verb: GET

• general form of the URI: /api/rest/{type of service}{/name of the resource type}/aggs

The parameters are exactly the same as for a list service. The response will be similar, but will only contain aggregates and the counters (so not the resources whose aggregates are determined). However, the aggregates will not be classified by field, but by keys.

Aggregate filter query

To obtain these counters we use a special syntax query. It is a JSON object that must have one and only one $meta-query property. The value of this property must be a JSON object.

The query fragments

Each property of $meta-query defines a query fragment. The name of the property is called the key and the value, a JSON object, describes this fragment, which can define three kind of query:

• an aggregate query, to define an aggregate calculation (and related query)

• a constraint, which is a complementary filter to aggregate query

• a unconstrained aggregate, which is associated to an aggregate calculation which is not constrained with the constraint

In summary,

• the aggregate defines the counter to be calculated (the field for which we want the value counters), the associated query, whose purpose is to exclude the values already selected

• the constraint, which allows to indicate what will be selected (in order to have the count of what will be selected)

• the unconstrained aggregate, in order to have the count of what is selected

Key

The constraint key is an expression composed of selectors separated by dots. A key is therefore a path of selectors, that defines a name space. Each selector defines a property (or field), a selection filter, a constraint, and counting options. In all keys, the same identifier in the same name spaces defines the same selector.

The key defines a hierarchy of selectors, from left to right. For example, consider these two keys:

1. selector_1.selector_2

2. selector_1.selector_2.selector_3

The selector selector_3 is a sub-selector of selector_2 (in the name space selector_1.selector_2).

Selector

A selector is composed of two parts, separated by a colon:

• a combinatorial operator, among

  • OR

  • AND

  • NOT

  • NOR

  • NAND

• a uniq identifier
  The name is free, but must not contain a dot or a colon.

The operator can be omitted (and the colon too in this case): in this case, the operator is an AND. This operator defines how the filters will be combined at the hierarchical level corresponding to the selector to create the query (criteria) that will be used to calculate the aggregates.

For example, consider these four keys:

1. or:selector_1

2. or:selector_1.and:selector_2

3. or:selector_1.and:selector_2.selector_3

4. or:selector_1.and:selector_2.selector_4

A the first level, we’ll combine the constrainte with an OR, at the second, with and AND, and at the third, with also an AND.

The corresponding pseudo-query will be:

Query fragment description

The JSON object that describes the key consists of the following possible properties:

• aggids: (optional) the list of selected value identifiers

• unconstrainedAggids: (optional) the list of ids of selected unconstrained values

• constraint: (optional) the definition of the constraint

• aggregate: (optional) the definition of the constrained aggregate

• unconstrainedAggregate: (optional) the definition of the unconstrained aggregate

Constraint description

It is either a JSON array or a JSON object that defines a selection query by criteria, according to the format described in the chapter Request Language.

The negation of the constraint will be combined with the aggregate query. Par exemple, si la contrainte est un in, on obtiendra un not in.

Aggregate description

This section define the agregate with these properties:

• field: (mandatory) the field name

• operator: the operator to use in the criterion associated to this field
  By default, if missing, the operator will be in. Although any operator that can be used with a list of identifiers can be used, the operator should be a set operator of type in or dof.

• ids: the list of identifiers of the values selected for this field, as an array.
  By default, if missing, the ids will be get from aggIds list (see above). If aggIds is missing, and ids is an object JSON, we’ll try to retrieve identifiers by using this object as query.

• exclusive: an optional boolean, default to true, to set the exclusive option

• treecount: an optional boolean, default to false, to set the treecount option

Unconstrained aggregate description

The definition works like the one for aggregate (except that instead of taking aggIds by default for ids, we use unconstrainedAggIds).

The unconstrained aggregate defines an aggregate calculation which is not associated to the constraint.

Short cut

The unconstrained aggregate can be a boolean, set to true. In this case, we try to use the constraint query to define the unconstrained aggregate, and unconstrainedAggIds possibly for the identifier list. The aggregate operator will be that of the constraint query (which must therefore have only one criterion) and the property as well, which must be identical to the field.

Field query

If we have a list of identifiers for the aggregate (not empty), we can create a query for the field. Similarly, if we have a list of identifiers for the unconstrained aggregate, we can create an unconstrained query for the field.

Global constraint not associated with an aggregate

We can introduce a fragment which is not associated with an aggregate calculation but which participates in the global query, by introducing a key and associating a fragment which only defines a constraint.

The typical case is the selection of activated assets, for example :

Example 1: aggregates, no field constraint

This example is a query of aggregates applied to the asset resource (passed in the query_asset parameter).

Query

Here we describe seven fragments.

Key !! static_query !!

This key describes a global fragment for which no aggregation will be calculated. It is a static selection criterion.
The definition consists only of a constraint:

This query selects only the activated assets. The corresponding SQL will be:

Other keys

All these keys will be combined with the first query, which is not associated to a field.

• or:assets._tab_assetnature_dof

  • The corresponding aggregates are defined with

  • The aggregates will be calculed for field assetnature (this means that we will obtain the counters of the values present in the assetnature field)

  • Here is the corresponding SQL query (the dof operator is converted to an in among the descendants of specified ids)

  • Here is the final query

• or:assets.assetnature_1.assetformat

  • The corresponding aggregates are defined with

  • The aggregates will be calculed for field assetformat (this means that we will obtain the counters of the values present in the assetformat field)

  • Here is the corresponding SQL query

  • Here is the final query

• or:assets.assetnature_3.videoratio

  • The corresponding aggregates are defined with

  • The aggregates will be calculed for field videoratio (this means that we will obtain the counters of the values present in the videoratio field)

  • Here is the the corresponding SQL query

  • Here is the final query

• or:assets.assetnature_1.colorspace

  • The corresponding aggregates are defined with

  • The aggregates will be calculed for field colorspace (this means that we will obtain the counters of the values present in the colorspace field)

  • Here is the the corresponding SQL query

  • Here is the final query

• or:assets.assetnature_1.assetnature

  • The corresponding aggregates are defined with

  • The aggregates will be calculed for field assetnature (this means that we will obtain the counters of the values present in the assetnature field)

  • Here is the the corresponding SQL query

  • Here is the final query

• or:assets.assetnature_6.assetnature

  • The corresponding aggregates are defined with

  • The aggregates will be calculed for field assetnature (this means that we will obtain the counters of the values present in the assetnature field)

  • Here is the the corresponding SQL query

  • Here is the final query

Example 2: unconstrained aggregates

This example is a query of aggregates applied to the asset resource (passed in the query_asset parameter)

Here we describe two fragments. The second has no specified aggregate definition, but a constraint and an unconstrained aggregate.

Key !! static_query !!

This key describes a global fragment for which no aggregation will be calculated. It is a static selection criterion.
The definition consists only of a constraint:

This query selects only the activated assets. The corresponding SQL will be:

Key keywords

The aggregate to be calculated is deduced from the unconstrained aggregate. That the name of the key is also the name of the field is just for consistency, but it doesn't matter, the name of the key could be anything

For that key, the constraint is defined by

It is ignored, because there isn’t any aggregate definition.

For that key, the unconstrained aggregate is defined by

The corresponding SQL query is

The final query is

Example 3: aggregate, constraint and unconstrained aggregate

This example is a query of aggregates applied to the asset resource (passed in the query_asset parameter). We have selected two values in the "seasons" filter. We need to display counters for the each four seasons, how many assets are selected for the checked seasons, and how many will be selected if we check another of each other seasons.

Here we describe two fragments. The second has an aggregate definition, a constraint and an unconstrained aggregate.

Key !! static_query !!

This key describes a global fragment for which no aggregation will be calculated. It is a static selection criterion.
The definition consists only of a constraint:

This query selects only the activated assets. The corresponding SQL will be:

Key season

Aggregate

For that key, the aggregate is defined by

The corresponding SQL query is

Constraint

For that key, the constraint is defined by

The corresponding SQL query is (as negation of the defined query)

Unconstrained aggregate

For that key, the unconstrained aggregate is defined by

The corresponding SQL query is

Result sample

The result presents finally aggregates (for asset with season as id 1 or 4, but not id 2 or 3) and unconstrained aggregates (for asset with season as id 2 or 3).

Display

The season filter will shows like this:

Open

The ids are:

• Spring: 1

• Summer: 2

• Autumn: 3

• Winter: 4

Example 4: mixing

Still applied to assets, here we make a query of aggregates, as we selected a value in the "visibility" filter (grouped with “Authorized channels”), in addition to those selected in example 3.

Here we describe four fragments.

Key !! static_query !!

This key describes a global fragment for which no aggregation will be calculated. It is a static selection criterion.
The definition consists only of a constraint:

This query selects only the activated assets. The corresponding SQL will be:

Key season

We only need to get the counters for the new selection (visibility), and the counters for the future selection. So we don't ask for aggregates for the already selected seasons (unlike in example 3).

The corresponding SQL query is

Key visibility

We have selected a visibility among the three possible choices, so we ask for the aggregates.

Aggregate

For that key, the aggregate is defined by

The corresponding SQL query is

Constraint

For that key, the constraint is defined by

The corresponding SQL is (negation of the constraint query):

This query will be combined with the others for the calculation of the aggregate to give the final result:

The assets that do not have the newly selected choice value are counted here (which tells you how many more assets you can get if you select the other possible choices).

Unconstrained aggregate

For that key, the unconstrained aggregate is defined by

The corresponding SQL is

Key authorizedchannel

We display these choices in the same menu, so we make a request for aggregates for them.

Aggregate

For that key, the aggregate is defined by

The corresponding SQL query is

This query will be combined with the others for the calculation of the aggregate to give the final result:

We therefore count here the assets that are at the same time all the values of the selected choices.

Result sample

Display

Here is how the visibility/authorized channels is displayed:

Open

Here is the seasons filter:

The ids are:

• Terms of use (field visibility, resource assetvisibility)

  • Public: 1

  • Internal use only: 2

  • On request: 3

• Right managed channels (field authorizedchannels, resource assetchannel)

  • Print: 1

  • Corporate Web: 2

  • Social Networks: 3

  • Advertissement: 4

  • All: 5

  • Events: 6

  • Partner Channels: 7

• Seasons (field season, resource assetseason)

  • Spring: 1

  • Summer: 2

  • Autumn: 3

  • Winter: 4