Documentation Center

The recommend parameter of the search query

This topic describes the syntax and use of the recommend parameter in the search query.

Syntax

The search query can have a recommend parameter, which must contain one or both of:
an id child
This identifies an item to use as a basis for recommendations.
a concepts child array
This identifies specific schemes and concepts to use as a basis for recommendation. Also, in this array, you can tweak the exact recommendation behavior by using the boostBy and broadenBy parameters.
The concepts child array contains items with the following properties:
connectorId
Specifies a PoolParty Connector ID, that is, a scheme.
boostBy
Specifies how much weight to add to relations of this type. The value can be any positive number. This optional property defaults to 1.
broadenBy
Specifies how much more broadly we can explore relationships for recommendations (say, not just the concepts of the item itself, but also the parent concepts of those concepts). The value can be any positive number. This optional property defaults to 0 meaning no broadening. A value of 1 means one extra level, and so on.
conceptIds
Specifies which concepts to take into account for recommendations:
Is id set?Is conceptIds set?Behavior
YesNoRecommendations are based on the concepts of the item identified by id.
YesYes, for a scheme in use by the item identified by idRecommendations are based on the concepts of conceptIds; the concepts of the item identified by id are ignored.
YesYes, for a scheme not in use by the item identified by idThe entire concepts child array is ignored.
NoYesRecommendations are completely based on conceptIds arrays. Every concepts child array must have a conceptIds array set.

Sample query

Here's a simple example of a recommend parameter being used:
search(
  recommend: {
    id: "tcm:5-449"
    concepts: [
      {
        connectorId:"glassware"
        boostBy: 1
        conceptIds:["e-learning-poolparty-biz_cocktails_2dce3576-2603-41f9-8dce-ab21f639c2a7"]
      }
      {
        connectorId:"ingredients"
        boostBy: 10
        broadenBy: 3
      }
    ]
  }
)

Interaction with other search parameters

All other search query parameters can be used together with the recommend parameter:
  • criteria or rawCriteria filters the recommendations. If these parameters are not set, the recommendations are not filtered.
  • sortBy sorts recommendation results with the conditions specified. If this parameter is not set, recommendation results are sorted by score.
  • resultFilter excludes metadata and highlighting. Highlighting will always be done for criteria.
  • facets: when recommendations are requested, queries return concept facets based on recommended items, rather than based on general criteria.

Code samples

To learn how to create sophisticated queries for your recommendation engine, refer to the GraphQL code samples for the recommend parameter. These samples illustrate the functionality in detail in the form of an implementation journey, starting with a basic example and working towards a more complex query.