Pinned results

Pinned results let you promote selected content when a user's search query matches a specific phrase. These items display at the top of the search results because they receive a higher boost weight.

For example, when a user searches for "water," you want to promote bottled water products. To do this, define the search phrase and the content to promote in Optimizely Graph, and enable pinned results in the query using the usePinned argument.

Define pinned results in Optimizely Graph

Define pinned results in Optimizely Graph to control which items rise to the top of search results for chosen phrases, so merchandisers and content editors can guarantee visibility for priority content. Pinned items live inside collections you create through the Gateway REST endpoint, and each collection groups related pins for one editorial use case.

Optimizely Graph stores pinned results in a pinned results collection. Create multiple collections, but each pinned result must belong to a collection.

To create a collection, send an authorized request to the GraphQL Gateway REST endpoint using your HMAC and secret keys using the following endpoint. For more information, go to Pinned Results Endpoints.

POST /<GATEWAY_URL>/api/pinned/collections

Include the following values in the request body:

• title – The name of the collection, used for management purposes.
• isActive – Set to true to enable the collection and its pinned items.

After Optimizely Graph creates the collection, note the returned collection ID. This ID is required to add pinned items and apply pinned results in queries.

Add a pinned item

Add a pinned item to bind a target content GUID to one or more trigger phrases inside an existing collection, so the item surfaces at the top of the result set when a shopper searches for any of those phrases.

When a collection exists, add items to it using the following endpoint:

PUT /<GATEWAY_URL>/api/pinned/collections/{collectionId}/items

Include these fields in the request body:

• phrases – The search phrases that trigger this pinned result.
• targetKey – The GUID of the content to pin. Retrieve this value by querying ContentLink.GuidValue in Optimizely Graph.
• language – The language code for the pinned item.
• priority – A numeric value used to order pinned items. When multiple items share the same phrase, priority determines which displays first. Optimizely Graph shows only the top five items.
• isActive – Set this to true to activate the pinned item.

To find the targetKey (GUID), use a query like the following:

query {
  Content {
    items {
      _score
      ContentLink {
        GuidValue
      }
    }
  }
}

Apply pinned results to query

Apply pinned results inside a GraphQL query to merge promoted items into a regular search response, so shoppers see editorial picks at the top alongside organic matches. The pinned argument controls which phrase and which collection drive the promotion.

To apply pinned results, use the pinned argument in your GraphQL query. This argument requires a phrase and a collection ID.

query MyQuery() {
  Content(
    where: { _fulltext: { match: "test" } }
    pinned: { phrase: "test", collections: "e4c0b166-ce40-4620-b872-35af8d4fab22" }
  ) {
    items {
      _score
      _id
      Name
      MainBody
      Status
    }
    total
  }
}

The pinned argument includes two options:

• phrase – The user search query to match against pinned item phrases.
• collections – The collection to use. When omitted, Optimizely Graph evaluates all active collections.

Example

The following example shows a reusable pinned-results query, so you can pass the search text and collection ID at runtime instead of hard-coding them.

To make your query reusable, define variables for the search text and collection ID as shown in the following sample:

query MyQuery($searchText: String, $collectionId: String) {
  Content(
    where: { _fulltext: { match: $searchText } }
    pinned: { phrase: $searchText, collections: $collectionId }
  ) {
    items {
      _score
      _id
    }
  }
}