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, if a user searches for “water,” you may 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

Pinned results are stored in a Pinned results collection. You can 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:

PUT /<GATEWAY_URL>/api/pinned/collections

Include the following values in the request body:

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

After the collection is created, note the returned collection ID. You will need this ID to add pinned items and apply pinned results in queries.

Add a pinned item

When a collection exists, you can 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 should trigger this pinned result.
• targetKey: The GUID of the content to pin. You can 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. If multiple items share the same phrase, priority determines which displays first. Only the top five items are shown.
• isActive: Set 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

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

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

The usePinned has 2 options inside:

• phrase: The user search query to match against pinned item phrases.
• collectionId: The collection to use. If omitted, all active collections are evaluated.

Example

To make your query reusable, define variables for the search text and collection ID:

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