Featured result: Query pipeline feature

This is for:

Developer System Administrator

The featured result query pipeline feature promotes specific items to the top of search results for particular queries. You can configure a featured result statement in a query pipeline using the Result Rankings API. Unlike ranking expression, which influences relevance scoring across all results, featured result targets specific items by identifier or query expression, and applies a large ranking boost to ensure those items appear first in the result list.

The following diagram shows the process of a query being sent to the Search API and the order of execution of query pipeline features.

Coveo | diagram showing order of execution

When a featured result statement is applied in a query pipeline, the following happens:

  • Promoted items are included in the result set, regardless of whether they match the original query.

  • Matching items receive a significant ranking boost.

  • The isTopResult property is set to true.

  • The rankingModifier property is set to FeaturedResult.

When multiple items are promoted through the featured result feature, each promoted item receives a distinct ranking boost to preserve the declared order in the search results. The first promoted item receives a boost of 100,000. Each subsequent promoted item receives a boost that is 1,000 lower than the previous one, whether it’s listed later in the same statement or in a later statement. This fixed gap between boost values guarantees that items appear in the intended order, regardless of their underlying relevance scores.

Important

If the search interface applies a sort order other than Relevancy to the search results (for example, Date or Title), featured results won’t be promoted to the top of the result list.

On a case deflection, the featured result statement doesn’t apply as it uses the basic query expression (q) as input. Case deflection panels usually query the index through the lq parameter, meaning that the q parameter is left empty. Therefore, if there’s no q, the statement can’t apply.

By default, featured result items are added to the result set regardless of whether they match the basic query (q) or advanced query (aq). This behavior is controlled by the matchQuery and matchAdvancedQuery properties, which both default to false.

The featured result feature affects relevance ranking only. Use the featured result feature when you want to make sure that specific items appear at the top of search results for particular queries. Some examples include:

  • Promoting troubleshooting articles: For known issues when users search for related error messages or symptoms.

  • Boosting help center content

    Content that answers frequently asked questions for common query patterns.

  • Highlighting critical announcements

    Service updates, security advisories, or maintenance notifications.

  • Surfacing curated content

    Provide the most accurate or up-to-date information for specific topics.

Tip
Leading practice

A statement expressing the featured result should only apply when a condition is fulfilled. When basing a featured result statement on the value of one or more $context keys, you should use a condition to assert that those keys contain values. Otherwise, the statement won’t apply as expected.

For example:

Condition

when $query contains "help"

Statement

featured result `@urihash==7Vf6bWsytplARQu3`

Configuration options

When creating a featured result statement through the Result Rankings API, you can configure the following options:

  • matchQuery (default: false)

    When true, the featured result only applies if the target item also matches the basic query (q parameter). When false, the featured result is included regardless of whether it matches the query.

  • matchAdvancedQuery (default: false)

    When true, the featured result only applies if the target item also matches the advanced query (aq parameter). When false, the featured result is included regardless of whether it matches the advanced query.

  • includeInFacets (default: false)

    When true, featured result items are included in facet calculations. When false, featured result items are excluded from facet computations.

Note

If you’re configuring matchQuery or matchAdvancedQuery options, it helps to understand how Coveo combines query parts.

The combined query expression is: ((q AND aq) OR dq) AND cq

The featured result feature modifies the dq (disjunction query) portion so target items are included in the result set even if they wouldn’t normally match the q (basic query) or aq (advanced query) portions. This is why featured results can appear regardless of query relevance, unless you explicitly enable matchQuery or matchAdvancedQuery.

Syntax

Use the following query pipeline language (QPL) syntax to define a statement expressing the featured result feature:

featured result <targets>

<targets>

A comma-separated list of target specifications identifying which items to promote. Each target can be one of the following:

  • Query expression: A query expression such as @urihash==value or @permanentid=="id". Items matching this expression are promoted.

  • Unique ID: A specific item identified by its unique ID. When you specify a unique ID, the system checks the following fields:

    • @urihash

    • @permanentid

    • @uri

An item matches if any of these fields contains the specified value.

Example

In this example, you want to promote two specific items to the top of results whenever a user searches for "product guide" in the Product Support query pipeline.

You first create a condition at the organization level with the following request:

Request:

POST /rest/search/v1/admin/pipelines/statements

Request body:

{
  "definition": "when $query contains \"product guide\"",
  "description": "Applies when query contains 'product guide'"
}

Response (excerpt):

{
  "id": "45a7892e-a63f-4c8e-8795-ab38c8c18d7e"
}

You then create a featured result statement in the Product Support pipeline and associate it with the condition you created:

Request:

POST /rest/search/v1/admin/pipelines/{pipelineId}/statements

Request body:

{
  "feature": "featured result",
  "definition": "featured result `@urihash==a1b2c3d4e5f6`, `@permanentid==\"installation-guide-v2\"`",
  "description": "Promote product guide items",
  "parent": "45a7892e-a63f-4c8e-8795-ab38c8c18d7e"
}

The parent field links the statement to the condition. The statement only applies when the condition is met.

When a user performs a query with the following payload, the statement applies:

{
  "aq": "@contenttype==\"documentation\"",
  "pipeline": "Product Support",
  "q": "product guide installation"
}

Since this query goes through the Product Support query pipeline and satisfies the condition of the statement, the statement applies. As a result, the different parts of the query expression are modified as follows:

  • dq (that is, $disjunctionQuery) becomes @urihash==a1b2c3d4e5f6 OR @permanentid=="installation-guide-v2". This modification includes items matching either of these expressions in the result set.

  • q (that is, $query) remains product guide installation.

  • aq (that is, $advancedQuery) remains @contenttype=="documentation".

The two items specified in the featured result statement receive a significant ranking boost (starting at 100,000). Additionally, the isTopResult property is set to true and the rankingModifier property is set to FeaturedResult for these items, which can be used by search interfaces to display them with special formatting or tracking.

The result set includes:

  • Items that match both the basic query (product guide installation) AND are documentation content (because of the aq parameter).

  • The featured result items (added through the dq expression modification).

The featured result items appear at the top of the result list due to their significantly boosted ranking scores, even if their relevance to the actual query is lower than other results.

What’s next

Test your featured result statement by performing queries that satisfy the associated conditions and verifying that the expected items are promoted in the search results.