Curations Guide

You are the curator of your Engine. You are in control of how documents are consumed by your visitors.

A curation helps people discover what you would most like them to discover. Or, what you would not like them to discover.

There are two curation parameters:

• Promoted: Promote specific documents to have them appear in a prominent way. You can promote multiple documents per query, the array order representing the order in which they will appear.
• Hidden: Hide specific documents so that they do not appear. You can hide multiple documents per query, the array order being unimportant because... they are hidden.

Consider an example where your users are searching for "kettle".

You might promote a specific kettle.

Perhaps it is the most popular one, the one a visitor is most likely to purchase.

Or, you could hide a kettle - maybe it is out-of-stock or having issues - to prevent people from seeing it.

Each set of curations belongs to a query. A query may only be part of one curation set.

There are two ways to build a curation set:

1. Curations Dashboard UI
2. Curations API

Curations UI

Each Engine contains a Curations UI.

This will allow any person - developer or otherwise - to curate a result set.

To begin, click into Curations.

From there, click on Create new Curation.

You can provide one or more queries.

The idea of a Curation is to curate the result set of a given query.

And so, we must supply the query first to receive its result set.

You can enter one, or multiple queries. In this case, we want to curate the results for the "mountains" query.

Once at least one query has been provided, results of that query will appear as a list of organic results.

Organic results have nothing promoted and nothing hidden, they reflect the current result set for that query.

Now, to promote a result.

We want Rocky Mountain National Park to be the first result when a user queries for "mountains".

We can either:

1. Click the star next to the document.
2. Use the drag handle on the left of the document.

We can promote multiple documents and rearrange the order of our promoted documents.

If we promoted 3 documents, we can order them however we would like.

Click Demote All to return all promoted results back to the organic result set.

What if we need to hide a document?

It seems appears "Mesa Verde National Park" is closed for maintenance.

We should hide the document so that it no longer appears within the result set.

To do so, click on the eye icon:

All hidden documents collapse underneath the organic results in their own section.

You can view your hidden results.

Click Restore All to unhide them:

If you chose multiple queries, or want to curate another query, click Manage Queries.

From there, one can add or select a new query.

Selecting a query changes the result set to match that query.

This can be used to curate result sets for similar concepts that are not synonyms, like "big mountains", "small mountains", "mounds", and so on.

The moment you promote or hide a document, the new result set will be active.

Anyone who uses the query that you have curated will receive your newly minted result set.

You can Restore Defaults to revert all of your changes, or delete the curation from the main curations view.

Curations API

The App Search API provides full control over Curations.

When you craft a curation you must include one or more queries within an array.

That array of potential queries, along with the documents that fit the promoted and hidden parameters, form a curation.

In the example below, queries for banana, bonana and nanner will include three promoted documents:

• doc-123
• doc-a2b3c4
• doc-456

and will exclude three hidden documents:

• doc-a9b87c
• doc-789
• doc-a7b6c5

This set of queries, promoted documents, and hidden documents is a single curation with its own unique identifier.

The id of a curation is serialized via BSON.

The id of a document is serialized via BSON as well, but you can supply your own id value.

A response might look something like this:

{
  "id": "cur-a5b6c7",
  "queries": [
    "banana", "bananana", "bonana", "nanner"
  ],
  "promoted": [
    "doc-123", "doc-a2b3c4", "doc-456"
  ],
  "hidden": [
    "doc-a9b87c", "doc-789", "doc-a7b6c5"
  ]
}

Curations and Sorting

You may expect a curation to always be in its curated position, regardless of sort.

But that's not always the case.

It's helpful to understand cases where a curation will and will not have priority when using sorting.

Curations are applied when there is...

1. No sort field(s).
2. A sort against the _score field.

Curations are not applied when there is...

1. A sort against a custom field.
2. A multi sort against _score, followed by a custom field.

Helpful Reads

Your Curations can become mighty tools in improving the relevance, and thus the overall experience, of search queries. Business goals, too, as you can get your visitors where you would like them to be. If you want to take a deep look into how users are interacting with your engines, checkout:

• Analytics
• Clickthrough
• Search Guide

---

Stuck? Looking for help? Contact support or check out the App Search community forum!