Query Pipeline Language (QPL)

The query pipeline language, also known as QPL (pronounced qupel) is a simple language used to define query pipeline statements.

To express the following rule in a given query pipeline:

Replace the foo keyword in the basic query expression (q) with the (foo OR bar) expression.

You would create a query pipeline statement with the following QPL expression as a definition:

expand "foo" to "bar"

This QPL definition is an expression of the thesaurus query pipeline feature (see Thesaurus - Query Pipeline Feature).

Examples

What follows is a list of query pipeline features that can be expressed with QPL, along with an example of each.

filter

The following QPL statement expressing the Filter feature adds @source=="Public Content to the advanced (aq) part of the query expression (see Understanding the Query Expression).

filter aq `@source=="Public Content"`

queryParamOverride

The following QPL statement expressing the QueryParamOverride feature overrides the enableQuerySyntax and wildcards query parameter values to true before the search request is processed any further by the Search API.

queryParamOverride works only for the number, string, and Boolean types of query parameters.

override query enableQuerySyntax: true, wildcards: true

ranking

The following QPL statement expressing the Ranking feature generates a query ranking expression (QRE) that boosts the ranking score by 10 for items that match the specified regex (see Using Query Ranking Expressions).

boost `@title/="^.*Coveo.*$"` by 10

rankingweight

The following QPL statement expressing the Rankingweight feature modifies weights of various ranking factors used by the index to determine the ranking scores of query result items.

rank adjacency: 9, concept: 6, title: 5, termCasing: 1, uri: 0

stop

The following QPL statement expressing the Stop feature removes the specified list of words from the basic (q) part of the query expression before executing a query against the index (see Understanding the Query Expression).

stop "be", "do", "how", "i", "in", "my", "not", "or", "the", "to"

thesaurus

The following QPL statement expressing the Thesaurus feature appends OR automobile OR (motor vehicle) to phrases in the basic (q) part of the expression matching either the "car" or /(dodge) \w+/ expressions.

expand "car", /(dodge) \w+/ to "automobile", "motor vehicle"

top

The following QPL statement expressing the Top feature greatly increases the ranking scores of an item matching either of the specified query expressions.

top `@urihash==7Vf6bWsytplARQu3`, `@title=="Top - Query Pipeline Feature"`

trigger

The following QPL statement expressing the Trigger feature executes the showAnimation action in the search interface from which any queries originate.

execute showAnimation("triggerStatement", 100, true)

Reference

Primitive Types

QPL supports four primitive types:

  • Boolean (i.e., true, false)

  • integer (e.g, 123)

  • quoted string (e.g., "foo")

  • string (e.g., foo)

Regular Expressions

Regular expressions must be enclosed within forward slashes (/).

QPL uses the java.util.regex package to parse regular expressions (see Lesson: Regular Expressions).

# Using a quantifier
/foo*/
 
# Using a named capturing group; the `<` and `>` symbols must be escaped
/(?\<myGroup\>foo)/
 
# Using an embedded flag expression (i.e., modifier)
/(?i)foo/
 
# Using a predefined character class
/\d/

Query Expressions

Query expressions must be enclosed within backticks (`).

The main difference between a query expression and a quoted string is that the QPL parser will reject a query pipeline statement whose definition contains a syntactically wrong backticks-enclosed query expression, whereas it won’t try to parse that same expression if it’s enclosed within double quotes (see Coveo Cloud Query Syntax Reference).

# A simple query expression
`foo bar`
 
# A query expression using a Boolean query syntax operator
`foo OR bar`
 
# A field query expression
`@title==foo`
 
# A complex query expression using the `$qre` standard query extension
`$qre(expression: $context.key=="foo", modifier: 100)`
 
# A complex query expression using the `$qre` and `$splitValues` standard query extensions
`$qre(expression: @coveodptaxonomyleaves=$splitValues(text: $query, separator: '\s'), modifier: 15)`

Boolean query syntax operators (AND, NEAR, NOT, and OR) should always be in uppercase in a QPL query expression.

While using lowercase Boolean operators may work, doing so is ill-advised as it can yield unexpected results.

Lists

Some features and constructs accept a list of values rather than a single value.

When this is the case, distinct values are separated by commas (,).

expand /foo.*/, "bar baz" to "\"hello world\""

Hashes

Some features and constructs accept a list of key-value pairs rather than a single value.

When this is the case:

  • Each key must be a non-quoted string.

  • Each key must be separated from its value by a colon (:)

  • Each value must be a Boolean, integer, quoted string, or regular expression.

  • Distinct key-value pairs are separated by commas (,)

key1: true, key2: 123, key3: "bar", key4: /foo.*/, key5: `hello world`

QPL Objects

QPL objects are domain-specific constructs which allow you to define conditions using the supported operators.

The following table lists all available QPL objects.

Object Contains the value of the... Returns many values
$advancedQuery ...aq query parameter (unprocessed value and current processed value). No
$browser

...browser in the user agent.

Yes
$constantQuery ...cq query parameter (unprocessed value and current processed value). No
$context[key] ...key entry in the context query parameter. Possibly
$device ...device in the user agent. Yes
$disjunctionQuery ...dq query parameter (unprocessed value and current processed value). No
$groups ...userGroups part of the identity performing the query. Yes
$identity ...name part of the identity performing the query. Yes
$language ...language part of the locale query parameter. No
$largeQuery ...lq query parameter (unprocessed value and current processed value). No
$locale ...locale query parameter No
$originalQuery ...q query parameter (unprocessed value only). No
$originalAdvancedQuery ...aq query parameter (unprocessed value only). No
$originalConstantQuery ...cq query parameter (unprocessed value only). No
$originalDisjunctionQuery ...dq query parameter (unprocessed value only). No
$originalLargeQuery ...lq query parameter (unprocessed value only). No
$os ...operating system in the user agent. Yes
$query ...q query parameter (unprocessed value and current processed value). No
$recommendation ...recommendation query parameter No
$referrer ...referrer query parameter No
$searchHub ...searchHub query parameter No
$tab ...tab query parameter No

Supported Operators

When using a QPL operator:

  • The left-hand operand must be a QPL object.

  • The right-hand operand, if required, must be a Boolean, integer, quoted string, regular expression, or query expression.

Using a query expression as a right-hand operand is typically only legitimate when:

  • The left-hand operand is one of:

    • $advancedQuery/$originalAdvancedQuery

    • $constantQuery/$originalConstantQuery

    • $disjunctionQuery/$originalDisjunctionQuery

    • $largeQuery/$originalLargeQuery

    • $query/$originalQuery

AND

  • You want to ensure that the query pipeline statement will be rejected if the right-hand operand contains a syntactically incorrect query expression (see Coveo Cloud Query Syntax Reference).

The following table lists the supported QPL operators.

Operator Best suited right-hand operand types Examples
is/is not operators
  • Boolean
  • Integer
  • Quoted string
  • Query expression
  • $context[isAdmin] is true
  • $context[level] is not 3
  • $language is "fr"
  • $advancedQuery is not `@source=="Community Site`
contains/doesn't contain operators
  • Quoted string
  • Query expression
  • $device contains "Mobi"
  • $contantQuery doesn't contain `@filetype=="PDF"`
matches/doesn't match operators
Regular expression
  • $query matches ^(?i)how do i.*$
  • $device doesn't match ^.*Mac.*$
starts with / doesn't start with
  • Quoted string
  • Query expression
  • $identity starts with "john"
  • $originalQuery doesn't start with `the`
ends with / doesn't end with
  • Quoted string
  • Query expression
  • $context[partner] ends with "@partner.com"
  • $query doesn't end with `product`
isPopulated1 / isEmpty2 / isNull3 / isUndefined4 None
  • $identity isPopulated
  • not $originalQuery isEmpty
  • not ($context[partner] isNull or $context[partner] isUndefined)

Note 1: Returns false if the left-hand operand is null, undefined, an empty string, a blank string (i.e., a string containing only white spaces), an empty array, or an array of empty/blank strings. Returns true otherwise.

Note 2: Returns false if the left-hand operand is null, undefined, a non-empty string, or a non-empty array. Returns true otherwise.

Note 3: Returns true if the left-hand operand matches the null value. Returns false otherwise.

Note 4: Returns true if the left-hand operand is an undefined object property. Returns false otherwise.

Using QPL Objects In Query Expressions

You can inject the value of any QPL object (except for $query/$originalQuery) inside a query expression.

When a QPL object such as $os returns many values, use the $joinValues query extension (e.g., $joinValues(values: $os)).

When you want to inject the value of a specific $context object key inside an expression:

  • If the expression is a string in a QPL statement definition (i.e., not a query expression enclosed within back-ticks), use square brackets notation (e.g., boost @audience==$context[userRole] by 100).

  • If the expression is a query expression enclosed within back-ticks in a QPL statement definition, or if it’s a query expression that isn’t part of a QPL statement, use dot notation (e.g., boost `@audience==$context.userRole` by 100 / $qre(expression: @audience==$context.userRole, modifier: 100)).

When referencing a QPL object in a ranking query pipeline statement (i.e., in a ranking expression rule), always associate the statement with a condition that tests whether the QPL object is nonempty. Otherwise, you risk inadvertently boosting undesired results.

Condition

when $context.userRole isPopulated

Statement

boost `@audience==$context.userRole` by 100

Comments

QPL comments:

  • Must be preceded by the # symbol.

  • Take an entire line.

Valid:

# This is a valid comment.

Invalid:

expand foo to bar # This is an invalid comment.

Empty Lines

The QPL parser ignores empty lines.

expand foo to bar
 
 
 
 
 
# The five previous lines are ignored.
Recommended Articles