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 (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 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 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 (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 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 is a query expression that is not 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.