...

The grouping is done by the parameters group and grouplevel.

Another type of grouping is available from version 2023.4.0 (see extended groupings).

The group parameter

This parameter defines the groups.

...

This is a number that determines the level of the group you want to obtain (it must be less than the number of levels requested), which allows you to obtain a subgroup directly.

Extended groupings

Since

The group parameter can be used to define a grouping system based on aggregates. It is no longer necessary to sort the main data. But you are limited to a single grouping level for each property.

Only the group parameter is used, but it is always combined with the other parameters. The query parameter (and derivatives) serves as a data filter, props lists the properties of asset to return, while the max parameter indicates the maximum number of data items (including groups), etc.

The group parameter

This parameter defines the groups. It’s a JSON object, with at least a property groups to define groups. This property can have two forms: array or object.

Array form

In this form, each array element defines a grouping, via a JSON object. A property of this object, groupId, defines a grouping identifier that enables the results of this grouping to be retrieved in the response. The other properties describe how to group, and are detailed in section Grouping properties below. If no identifier is specified with property groupId, an automatic identifier will be assigned.

Object form

In this form, the object properties are the group identifiers and the associated value a JSON object that describes the grouping properties as shown in section Grouping properties below.

Other properties at root

• props: exposed properties for group data.

• max: maximum number of data instances per group

• groupMax: maximum number of groups per result

• aggLimit:

• format: style of response (1, 2 or 0 by default)

• sortedByNames: true (by default) to sort groups by names (ascending), false to not (sort by id)

Grouping properties

There are different ways to describe a grouping.

By property

In this mode, we indicate the asset property by which we want to group, using the prop property.

For example, if you want to group assets by assetnature:

{
   "prop": "assetnature"
}

By metadata type

It is possible to specify the type of metadata (i.e. the type of grouping property, or nature), using type property (or nature property).

For example, if you want to group assets by assetkeyword nature:

{
   "type": "assetkeyword"
}

Please note that if there are several properties of this nature, the service will return an error to indicate that it cannot determine which property should be used. In this case, you'll need to specify the property name. You can specify both, but this will require a type check.

By UUID of metadata instances

The id property, a string or an array of strings, indicates the uuid (or uid) of objects to be selected as grouping values. A simple id can be indicated if a sufficient description of the property and nature (by prop and/or type) has also been specified.

Describing a group with a simple string

This string will be considered as a metadata UUID You can also use an array of strings to indicate several UUIDs.

Common properties

These properties describe the characteristics of the grouping and the data returned, for the group in particular. Some of them can be specified in the global section of the group parameter (see Other properties at root above).

• ope (or operator)
  Depending on the type of grouping property, a default operator is used to select the aggregate (This operator can be derived as "is empty" if the value to be tested is empty or null.). This property allows you to modify this default value.
  Default operators by type

  • for a child(arbo_field or thesaurus) DOF

  • for a child(neither arbo_field nor thesaurus) EQ

  • for a collection IN

  • for a childmulti (arbo_field or thesaurus) DOF

  • for a childmulti (neither arbo_field nor thesaurus) IN

  • else: EQ

• groupQuery (and its suffixed derivatives by type)
  A filter to be applied to the grouping data query. This filter uses JSONQuery syntax.

• dataQuery (and its suffixed derivatives by type)
  A filter to be combined with the main query on group data. This filter uses JSONQuery syntax.

• find
  A fulltext filter to be combined with the main group data query

• groupAfter
  A token allowing you to request the groups following those obtained previously.

• dataAfter
  A token to request the assets following those obtained previously.

• max (or dataMax)
  Maximum number of assets per group (default is 3, max is 20)

• groupMax
  Maximum number of grouping instances per group, i.e. groupId (default is 20, max is 50).

• aggLimit
  Aggregate limit configuration

• props
  Properties of grouping instances to be exposed (default id and name).

• notAssigned
  A Boolean used to indicate that a grouping instance of type metadata has no value (a UUID corresponding to an ID of value 0 can also be indicated, with property id).

Result

To summarize, the response/data section of the main query is an array of sections (JSON Object) made up as follows:

1. in groupData property, an object to describe the group

2. in data property, an array with the asset (or any other data) corresponding to the group (having the corresponding metadata)

3. in nextData, the value of the group parameter that should be specified to obtain the rest of the data for this group, or null, if all the data have already been obtained

4. some additional data

   1. total: the total number of data that can be obtained for this group

   2. count: the number of data obtained in this response

   3. complete: true if all the data in this group have been obtained (specifically, if there are no more data in this group after the last one obtained in this response)

   4. nextToken: if existing, the token to build a nextData section yourself

In response, at the same level as data, a section group (array) with, for each groups, an object containing these properties

1. groupId, the ID of the group

2. nextGroups, the value of the group parameter that should be specified to obtain the rest of the group data, or null, if all the groups have already been obtained

3. total: the total number of group instances (metadata instances) for this group

4. count: the number of group instances for this group in the current response

5. complete: true if all the group instances have been obtained

6. nextToken: if existing, the token to build a nextGroupssection yourself

In addition, the link section contains sections of the nextData or nextGroups type, grouped together to obtain the rest of the data in a single query if required.

Exemple

Let's take the request https://example.wedia-group.com/api/rest/dam/data/asset. It returns 8140 instances, 50 by 50.

We add the following group parameter:

{
   groups: {
	   location: {
		    prop: location
		 },
		 autor: {
				prop: photograph,
				max: 4
		 }
	 }
}

We require two different groupings

• one for identifier location, which groups according to the location property (assetgeography type)

• the other for identifier author, which groups according to the photograph property (assetauthor nature).

With max=4, author groups will have 4 assets max for each photographer, and location groups will have 3 assets max for each location (3 is the default value).

Here is a summary (simplified) of the response:

{
  "response": {
    "data": [
       {
          "groupdata": { // DATA of group "location" for instance assetgeography/11
            "groupId": location,
            "data": { // DATA describing the instance assetgeography/11
               "id": 11,
			   "$uuid": "783if7sieq1dun6m5bt9p1k8uafr1p93eocgqro",
			   "name": "Latin America and the Caribbean"
            },
            "count": 3, // this means this block contains 3 assets
            "total": 10, // this means there are 10 assets with the location assetgeography/11
            "nextToken": ...,
            "nextData": {
				"groups": { 
					"location": {
						"prop": "location",
						"id": "783if7sieq1dun6m5bt9p1k8uafr1p93eocgqro",
						"dataAfter": "91e8ea74d51d412115659a2abc7910fe"
					}
			  }
			},
			"complete": false // all asset for assetgeography/11 hasn't been get (only 3/10)
		  },
          "data": [ 3 assets with location=assetgeography/11: rnipqec3pw1uh83wrpwtp7ni4w, f1cxjquj5riabqtrji8oh5qbdh, f1cxjquj5riabtmwgib68i5w5w ]
       },
       {
          "groupdata": // DATA of group "location" for instance assetgeography/13
       },
       // then 10 others (for location)
       {
          "groupdata": { // then now, DATA of group "photo" for instance assetauthor/78
             "groupId"; "author", 
             "data": { // DATA describing the instance assetauthor/78
               "id": 78
             },
             "count": 1,
             "total": 1,
             "nextToken": null,
             "nextData": null // there is no more asset for this photographer
             "complete": true
          }
       },
       then 19 others (for author)
    ],
    "groups": [ // a summary of each group
       {
         "groupId": "location",
         "count": 12, // we got 12
         "total": 12, // there are 12 to get
         "nextToken": null,
         "nextGroup": null,
         "complete": true // we get all involved instances of assetgeography
       },
       {
          "groupId": "author",
          "count": 20, // we got 20
          "total": 97, // there are 97 to get
          "nextToken": ...,
          "nextGroups": {
            "groups": {
			  "author": {
				"prop": "photograph",
				"max": 4,
				"groupAfter": "ny8ig5b584wotcasfwh57mezjy"
			  }
			}
          },
          "complete": false // we don't get all involved instances of "assetauthor"
       }
    ]
  }
}

Let’s have a look to nextData just above:

{
  "groups": { 
	"location": {
		"prop": "location",
		"id": "783if7sieq1dun6m5bt9p1k8uafr1p93eocgqro",
		"dataAfter": "91e8ea74d51d412115659a2abc7910fe"
    }
}

If you redo the request https://example.wedia-group.com/api/rest/dam/data/asset with this value for group parameter, you will get the following 3 assets, and if you do it again, you will get other 3, and so on, until you’ll get the last of 10, and a null nextData, and a complete equal to true.

With nextGroups just above, you’ll get the missing assetauthor instances, with their assets, and a nextData for each one where it’s necessary.

In the links section, you’ll get also a summary of groups and data:

• groups, an array of each group, to know which are complete

• nextGroups: the parameter to get next groups

• nextData: the parameter to obtain all subsequent data for all groups already obtained (those in this response for which data remains to be obtained).

Clusters

It is possible to export collection properties in clusters, when they are of tree type (i.e. a property of the collection object is of the same type as the collection itself).

...