Related - CUE Front Developer Guide - Escenic Documentation

related(
  relation: String
  relations: [String!]
  type: String
  types: [String!]
  offset: Int
  count: Int
)

Returns content items related to the current content item. In other words, this filter can only return data when the context object is a content item. If the context item is a section then related() will always return 0 results.

Unlike most other data source filters, related() cannot be executed inside an and or or filter. This is because it is not implemented using Solr like the other filters. related() queries the Content Engine directly.

Note the following:

The datasource() function's sort, offset and count parameters do not work on results returned by the related() filter.
When working in the data source query editor, you will probably notice that the related() filter returns much less information about each result than the other Solr-based filters. This has no practical consequences. When a saved data source is executed by the datasource() function in a data retrieval query, the results are returned in the same format irrespective of how they were displayed in the data source query editor.

Parameters

If no parameters are specified, then related() returns all content items related to the current content item. The scope of the filter can be narrowed by specifying parameters. The relation and relations parameters are mutually exclusive: you are only allowed to specify one of them. The type and types parameters are also mutually exclusive.

relation: String: The name of a relation. Only related items belonging to the specified relation will be returned.
relations: [String!]: An array containing the names of relations. Only related items belonging to the specified relations will be returned. The sequence in which relations are specified is reflected in the order of the results.
type: String: The name of a content type. Only related items of the specified type will be returned.
types: [String!]: An array containing the names of content types. Only related items of the specified types will be returned. The sequence in which types are specified is reflected in the order of the results.
offset: Int: An offset to be applied to the initial result set. If the initial result set contains 4 results and you specify an offset of 1, then the first result will be omitted, leaving a final result set of 3.
count: Int: A size limit to be applied to the initial result set. If the initial result set contains 4 results and you specify a count of 2, then only the first two results will be included.

Examples

All these examples assume that the current content item has a stories relation containing 3 items (a, b and c) and a media relation containing 2 items (d and e)

related(relations: ["stories", "media"])

Returns a, b, c, d and e.

related(relations: ["media", "stories"])

Returns d, e, a, b and c.

related(relations: ["stories", "media"], offset: 1)

Returns b, c, d and e.

related(relations: ["stories", "media"], count: 2)

Returns a and b.

related(relations: ["stories", "media"], offset: 1, count: 2)

Returns b and c.

related(relation: "stories", offset: 1)
related(relation: "media", offset: 1)

Returns b, c and e.

The purpose of the related() filter

You may wonder why the related() filter has been implemented as part of data sources: it doesn't work in the same way as other data source filters (using Solr), and it can't be combined with them using and, or or not. Moreover, you can easily access a content item's relations from a content retrieval query, so why is it needed?

The related() filter allows you to access a content item's relations in a more flexible way than is possible by following the relations in a content retrieval query. You can use it, for example, to construct a list of related content items drawn from a sequence of relations: if the first relation is empty or doesn't contain enough content items, then the next relation in the list is used, and so on.