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).

Primitive Types

QPL supports four primitive types:

  • boolean
  • integer
  • quoted string
  • string
# A boolean
true
 
# An integer
123
 
# A quoted string
"foo"
 
# A string
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).

# A simple regular expression
/foo.*/
 
# Defining a group
/(?\<groupA\>foo|bar)/
 
# Using a modifier
/(?i)foo.*/
 
# Using a predefined character class
/\w+/

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 incorrect backticks enclosed query expression, whereas it will not attempt to parse that same expression if it is 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 more complex query expression
`$qre(expression: $context.key=="foo" modifier: 100)`

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: /foo.*/, key4: "bar"

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 multiple 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 portion 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/$originalDisjunctinoQuery
    • $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 (see The Is operator)
  • 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
  • Quoted string
  • Query expression
  • $device contains "Mobi"
  • $contantQuery doesn't contain `@filetype=="PDF"`
matches / doesn't match
(see The Matches operator)
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 (with the exception of $query/$originalQuery) inside a query expression.

When a QPL object, such as $os, returns multiple values, use the $joinValues query extension.

The following query expression is evaluated to osx mac when it originates from a Macintosh computer running on OSX.

$joinValues(values: $os)

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 is a query expression that is not part of a QPL statement, use dot notation (e.g., $qre(expression: @audience==$context.userRole, modifier: 100) / $qre(expression: @audience==$context.userRole, modifier: 100)).

When the value of the $context object key you want to inject in the query expression is an array, use the $joinValues query extension. (e.g., $joinValues(values: $context[key]) / $joinValues(values: $context.key)).

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.