Trigger - Query Pipeline Feature

A query pipeline statement expressing the trigger query pipeline feature defines an action to execute in the search interface from which a query originates when the query meets the associated query pipeline condition.

If a statement expressing the trigger feature is not associated with a global condition, it is ignored.

The following trigger actions are available:

  • execute executes a custom JavaScript function call.

  • notify displays a message to the end user.

  • query performs a new query.

  • redirect redirects the web browser to a specific URL.

When a statement expressing the trigger feature is applied, an object representing the action to perform is generated inside the triggers property of the query response. The search interface from which the query originates is then responsible for translating this object into an action (e.g., executing a corresponding JavaScript function call, notifying the end user with a corresponding message, etc.).

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

Apply trigger statements

Syntax

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

execute <function> | notify <message> | query <expression> | redirect <url>

<function>

A string that contains the JavaScript function call to execute (e.g., myFunction(true, 123, "abc")).

Boolean, integer, and quoted string function arguments are allowed.

<message>

A quoted string that contains a message to display to the end user (e.g., "Hello world!").

<expression>

A query expression to perform against the index (e.g., coveo OR "machine learning").

<url>

A quoted string that contains a URL to which the browser is redirected (e.g., "http://www.example.com").

Example

You create a global condition with the following QPL definition:

when $query contains "trigger statement"

In an empty query pipeline named Testing Triggers, you create three distinct statements, each expressing the trigger feature, with the following QPL definitions:

  • Statement 1:

    execute showAnimation("triggerStatement", 100, true)
    
  • Statement 2:

    notify "Here is some information about the `trigger` query pipeline feature!"
    
  • Statement 3:

    query `@title=="Trigger - Query Pipeline Feature"`
    

You associate each of these statements with the global condition you created.

A user performs a query against your index with the following payload:

{
  "pipeline": "Testing Triggers",
  "q": "how do trigger statements work"
}

This query goes through the Testing Triggers query pipeline and satisfies the condition of each statement in that pipeline, so all of the statements are applied. As a result, the triggers property of the query response is populated as follows:

[
  {
    "type": "execute",
    "content": {
      "name": "showAnimation",
      "params": ["triggerStatement", 100, true]
    }
  },
  {
    "type": "notify",
    "content": "Here is some information about the `trigger` query pipeline feature!"
  },
  {
    "type": "query",
    "content": "@title==\"Trigger - Query Pipeline Feature\""
  }
]

The search interface from which the query originated ensures that the corresponding actions are executed.

Recommended Articles