Skip to end of metadata
Go to start of metadata

The standard query extensions are built-in elements of the Coveo query extension language that you can use in queries and more complex custom query extensions. This topic describes the available standard query extensions. 

Note:

You can use any of the query extensions described in this topic in the query (q), advanced query (aq), or constant query (cq) parameters (see Query Parameters).

Example:

You want the results to be ordered by descending date (rather than relevance, the default). You inject a $sort query extension in the advanced query (aq) so that it is transparent to the user.

General Extensions

$q

Injects the basic query expression inside another query expression.

This extension is useful for example when another part of the query (advanced or disjunction) should contain the keywords entered by the end-user. A typical usage is to use it inside nested queries to match additional content.

Example:

The following advanced expression will expand to foo bar baz if the basic expression is bar:

$qf

Calculates a mathematical value from the result's data and injects it in a field. 

 

Example:

The following query function will calculate the distance between two places and will store it in a field.

ArgumentDescription
function 

The mathematical expression that calculates the value to inject in the field.

You can use the geolocation distance function (dist) and the syntax of the C++ Mathematical Expression Library ExprTk. However, the following statements that have been disabled:

  • if / else
  • while
  • repeat until
  • switch
fieldNameThe dynamic field that will hold the result.

Note

Icon

It is not possible to override an existing field with the value of a dynamic field.

The dynamic field can be used as a facet or as a computed field. However, dynamic ranges on dynamic fields are not supported.

For more information on Query Functions, see Query Function.

$qre

Injects a query ranking expression (QRE) in the query. A QRE allows the creation of on-the-fly ranking algorithms by specifying a query expression for which a ranking score modifier value is assigned (see What Are Query Ranking Expressions?). 

 

Example:

The following query extension adds 1000 to the ranking score of results matching the @sfaccountname=='MyCompany' query.

ArgumentDescription
expression The query expression matching items to which the ranking expression should apply.
modifier

Integer value specifying how to affect the ranking modifier for matching items. Positive values boost results while negative ones reduce the score.

Notes:

  • A ranking modifier actually increases or decreases the relevance of search results, depending if its value is positive or negative respectively. Technically, its value can be in between -2^31 and 2^31, but it is typical - and a good practice - to set it somewhere between -100 and 100, as this will not completely override the different ranking weights of search results (except for results that have the same QRE weight).
  • The QRE modifier value is correlated to the item ranking score by a 1 to 10 ratio.

    Example:
    A QRE modifier value is 100. Consequently this QRE adds 1000 to the ranking score of matching items.
isConstant
Whether the query expression for the QRE is constant.

Tip:

When your index is in a Coveo Cloud Organization, you can easily configure conditional QREs in query pipelines (see Managing Query Pipeline Ranking Expressions).

 

$qrf

Injects a query ranking function (QRF) in the query. A QRF allows the creation of an on-the-fly ranking algorithm by specifying mathematical expressions to calculate custom ranking. The value calculated by the expression will be added to the item score. 

 

Example:

The following query ranking function will add a score representing the square root of the view count to the result.

ArgumentDescription
expression 

The mathematical expression that calculates the ranking value to add to the result score.

You can use the geolocation distance function (dist) and the syntax of the C++ Mathematical Expression Library ExprTk, but the following statements that have been disabled:

  • if / else
  • while
  • repeat until
  • switch
normalizeWeightWhether to normalize the value using the standard index scale or not. If you do not want to completely override the index ranking and use the qrf as a boost, you should turn this on.

$weight

Overrides a ranking weight for the query.  

 

Example:

The following query extension sets a value of 7 on the TFIDF ranking weight ( Term Frequency-Inverse Document Frequency ). Values may range between 0 and 9 thus any value lower than 5 decreases the weight whereas any value higher than 5 will increase the weight provided by the selected ranking.

ArgumentDescription
name

Possible ranking weight types to alter:

  • Adjacency [Term proximity]
  • CollaborativeRanking [Collaborative rating weight ]
  • Concept [Term in concepts ]  
  • CustomDocumentWeight  [Custom ranking weight ]
  • DocDate  [Item modified recently]
  • Formatted  [Term has formatting]
  • Language  [Item is in user language]
  • LastDirInURI  []
  • Quality  [Item quality evaluation]
  • SourceReputation  [Source rating]
  • Summary  [Term in summary]
  • TermCorrelation  [Term correlation within stemming classes]
  • TermCasing  [Term casing]
  • TFIDF (Term Frequency-Inverse Document Frequency)  [Term frequency]
  • Title  [Term in title]
  • URI  [Term in address]

Icon

Names in brackets [] correspond to CES Administration Tool parameter names (see step 4a in Customizing Search Results Ranking for a description of each parameter).


valueInteger value specifiying the value of a ranking weight. The value must be between 0 and 9.

$sort

Returns the input result set reordered following the specified criterion.

Example:

The following query extension returns the input result set sorted by date in descending order.

ArgumentDescription
criteria

Possible values are: 

  • relevancy to sort using the normal ranking score, including the query ranking expressions when defined.
  • dateascending 
  • datedescending 
  • fieldascending to sort alphanumerically based on the content of the specified field. 
  • fielddescending to sort in the reverse alphanumerical order based on the content of the specified field. 
  • rankingexpressions to sort using only query ranking expressions, ignoring the normal ranking score. 
  • noranking to ignore all ranking mechanisms, returning results in a random order. 
fieldThis optional attribute is required exclusively when using the fieldascending or fielddescending criterion to specify the field containing the values on which you want to sort.

$fold

Load child results into the current results that match the query and share the same value for the specified field.

Example:

The following query extension folds items with the same conversation id under the same result.

ArgumentDescription
field

A field that shares the same value for all the items that you want to fold.

rangeMaximum number of items to fold under the result.

$loadParent

Load an item which is the parent of another item. The parent-child relationship is determined by the presence of the parent ID value among the fields of the child item.

Example:

The following query extension loads the parent result that has the ID specified in the child item.

ArgumentDescription
parent

The field containing a unique value to identify the parent. 

childThe field on the child containing the parent's unique id.

Extensions for Lists of Values

$valuesOfField

Lists all the distinct values of a field in a result set.

Example:

The following query extension returns all the work emails associated with the result set specified by the Contacts alias.

ArgumentDescription
resultSetThe result set for which to compute the list of values.
fieldThe name of the field whose values should be retrieved.
aggregateConditionsOptional. Aggregate conditions to use to filter the values based on a computed field operation (see Aggregate conditions).
maximumOptional. The maximum number of values to retrieve. If not specified, all the values are retrieved.
sortOrderOptional. The sort order to use when retrieving values (see Group By Sort Orders).  The default value is donotsort.

$keepMatchingValues

Filters a list to select only the values matching a regular expression.

Example:

The following extension returns only email addresses from the company.com domain.

ArgumentDescription
regex

The regular expression to use.

Note:

Use the Java regular expression (REGEX) syntax (see Regular Expressions ).

valuesThe list of values to filter.

$removeMatchingValues

Filters a list to remove all values matching a regular expression.

Example:

The following extension returns all email addresses except those ending with @company.com.

ArgumentDescription
regex

The regular expression to use.

Note:

Use the Java regular expression (REGEX) syntax (see Regular Expressions).

valuesThe list of values to filter.

$removeEmptyValues

Filters a list to remove all the empty values.

Example:

The following extension eliminates empty values from the values returned by {{addresses}} .

ArgumentDescription
valuesThe list of values to filter.

$removeDuplicateValues

Filters a list to remove all the duplicate values.

Example:

The following extension eliminates duplicate values from the values returned by {{addresses}} .

ArgumentDescription
valuesThe list of values to filter.

$replaceInValues

Transforms a list using a regular expression.

Example:

In the list of values returned by {{addresses}} , the following extensions respectively replace occurrences of the string company by the string somethingelse, and .com value endings by .org.

ArgumentDescription
regex

The regular expression to use.

Note:

Use the Java regular expression (REGEX) syntax (see Regular Expressions).

replacementThe replacement string to use with the regular expression.
valuesThe list of values to transform.
removeNonMatchingValuesOptional. If true, all values that are not matching the regular expressions are removed. By default, non-matching values are kept as is.
removeEmptyValuesOptional. If true, all values that are empty following the replacement are removed. By default, empty values are kept.
removeDuplicateValuesOptional. If true, duplicate values following the replacement are removed. By default, duplicate values are kept.

$mergeValues

Merges two lists of values together. Duplicate values are included only once. 

Example:

The following query extension merges the {{addresses}} and the {{anotherListOfAddresses}} lists of values. 

ArgumentDescription
firstThe first list of values to merge.
secondThe second list of values to merge.

$joinValues

Joins a list of values into a string.

Example:

The following expression joins a list of values into a string:

ArgumentDescription
valuesThe list of values to join.
separatorThe separator to put between values.

$splitValues

Splits a string into a list of values. 

Example:

The following expression splits a string into a list of values:

 

ArgumentDescription
textThe string value to split.
separatorThe separator that separates each value.

Join Extensions

The query extensions of join type produce similar operation as a join keyword used in an SQL statement.

$valuesToResultSet

Converts a list of values to a result set matching the items where a given field is equal to a value in the list. The original order of the values in the result set is preserved using ranking expressions.

Example:

The following query extension returns a result set of items for which the @sysworkemail field contains a value present in the {{addresses}} list of values. 

ArgumentDescription
valuesThe values to filter with.
field

The name of the field to use.

modifierOptional. The modifier to use for the ranking expressions.
minimumModifierOptional. The minimum modifier to use for the ranking expressions.

$joinOnValues

Filters a result set to only the items for which a given field is equal to one of the values contained in a list. The order of the values can optionally be preserved in the resulting result set when the modifier argument is specified. The extension returns a result set filtered on the field values. Any ranking expressions associated with the result set are kept.

Example:

The following query extension returns only items for which the email domain name is listed in the specified domains alias.

ArgumentDescription
resultSetThe result set to filter.
field

The name of the field to use.

valuesThe values to filter with.
modifierOptional. The highest modifier to use for the ranking expressions.
minimumModifierOptional. The minimum modifier to use for the ranking expressions.

$join

Filters a result set to only the items for which a given field is equal to a value of another field in another result set. If the toResultSet contains ranking expressions or sort orders, they will be included in the resulting result set. The order of the values can optionally be preserved in the resulting result set when the modifier argument is specified.

Example:

The following query extension returns only accounts with a won opportunities for which the opportunity amount sum is greater or equal to the specified amount alias. 

ArgumentDescription
fromResultSetThe result set from which the list of values is extracted.
toResultSetThe result set to filter.
fromFieldRequired if field is not set. The name of the field to use in the fromResultSet.
toFieldRequired if field is not set. The name of the field to use in the toResultSet.
fieldRequired if fromField and toField are not set. The name of the field to use in both result sets. This is equivalent to specifying both fromField and toField with the same value.
fromAggregateConditionsOptional. Aggregate conditions to use to filter the from result set before performing the join (see  Aggregate conditions  ).
maximumValuesOptional. The maximum number of values to filter on. By default, all values are used.
sortOrderOptional. The sort criteria to use when retrieving values from the fromResultSet. The default value is donotsort.
modifierOptional. The highest modifier to use for the ranking expressions.
minimumModifierOptional. The minimum modifier to use for the ranking expressions.

$filterJoin

Filters a result set to only the items that can be joined in another result set using the specified fields. If the local result set contains ranking expressions or sort orders, they are included in the resulting result set. This query extension basically performs two joins, one from the local to the external result set, and another back from the external to the local result set.

Example:

The following query extension returns accounts with won opportunities for which the total amount is greater than 100,000$. 

ArgumentDescription
localResultSetThe result set to filter.
externalResultSetThe result set to perform a join on in order to filter items in localResultSet.
localFieldRequired if field is not set. The name of the field to use in the localResultSet.
externalFieldRequired if field is not set. The name of the field to use in the externalResultSet.
fieldRequired if localField and externalField are not set. The name of the field to use in both result sets. This is equivalent to specifying both localField and externalField with the same value.
aggregateConditionsOptional. Aggregate conditions to use to filter the result set resulting from joining the local result set to the external one (see Aggregate conditions).
maximumValuesOptional. The maximum number of values to filter on. By default, all values are used.

Correlation Extensions

$correlateListOfValues

Outputs a set of ranking expressions that boosts results having one of several values in a specified field.Arguments:

ArgumentDescription
fieldThe name of the field to use.
valuesThe values to use for boosting.
modifierThe maximum modifier to apply when a result matches. Items matching the first value in the list get the highest modifier, and those matching the last one get the lowest modifier.
useFullTextOptional. If true, query ranking expressions (QRE) will also be output for items matching the field values in full text. The default value is false.
forceOneMatchOptional. If true, a query expression will be added that ensures that all results have a least one matching field value. The default value is false.

$correlateResultSet

Outputs a set of ranking expressions that boosts results sharing a field value from another result set.

ArgumentDescription
resultSetThe result set from which to grab the list of values.
fromFieldRequired if field is not set. The name of the field to use in resultSet.
toFieldRequired if field is not set. The name of the field to use in the resulting result set.
fieldRequired if fromField and toField are not set. The name of the field to use in both result sets. This is equivalent to specifying both fromField and toField with the same value.
maximumValuesOptional. The maximum number of values to retrieve from the source result set. By default, all values are used.
sortOrderOptional. The sort criteria to use when retrieving values from resultSet.  The default value is chisquare.
modifierThe highest modifier to use for the ranking expressions. The maximum modifier to apply when a result matches. Items matching the first value in the list get the highest modifier, and those matching the last one gets the lowest modifier.
useFullTextOptional. If true, query ranking expressions (QRE) will also be outputted for items matching the field values in full text.  The default value is false .
forceOneMatchOptional. If true, a query expression will be added that ensures that all results have a least one matching field value. The default value is false .

$correlateUsingIdf

Outputs an expression that ranks up items sharing keywords with those specified. Uses the inverse document frequency (IDF) method to give a greater weight to keywords that are less frequent in the index.

ArgumentDescription
keywords The string from which to extract keywords.
forceOneMatchOptional. If true, a query expression will be added that ensures that all results have at least one matching keyword. The default value is false .
removeStopWords

Optional. If true, any English stop word present in the keywords will be automatically removed. The default value is true.

Icon

This argument is deprecated. You should use the Stop Words query pipeline feature to filter out stop words from the query expression (see Managing Query Pipeline Stop Words).

noStemming

Optional. If true, keywords will not be expanded using the index stemming before matching items. The default value is false.

maximumOptional. The maximum number of keywords to use. If a larger number of keywords is provided, some keywords will be completely ignored. The default value is 100.

$some

Matches a subset of a list of provided keywords depending on the provided arguments.

ArgumentDescription
keywords The string from which to extract keywords.
bestOptional. Either an absolute or percentage value specifying that only the X best keywords of those provided are to be matched. Keywords that occur less frequently in the index are considered better than those that are very common.
matchOptional. Either an absolute or percentage value specifying that items containing only X or greater keywords of those provided are to be matched.
removeStopWords

Optional. If true, any English stop word present in the keywords will be automatically removed. The default value is true.

Icon

This argument is deprecated. You should use the Stop Words query pipeline feature to filter out stop words from the query expression (see Managing Query Pipeline Stop Words).

maximumOptional. The maximum number of keywords to use. If a larger number of keywords is provided, some keywords will be completely ignored. The default value is 100.
Example:
$some(keywords: foo bar baz, match: 50%)

$removeStopWords

Removes the English stop words from a list of keywords.

ArgumentDescription
keywords The string from which to extract keywords.
Icon

This extension is deprecated. You should use the Stop Words query pipeline feature to filter out stop words from the query expression (see Managing Query Pipeline Stop Words).

$noStemming

Arranges for a list of keywords to match without using stemming.

ArgumentDescription
keywords The string from which to extract keywords.
  • No labels