Coveo

The Coveo modules allow you to perform various searches and updates to items in your Coveo account.

Getting Started with Coveo

Prerequisites

  • A Coveo account

In order to use Coveo with Make, you must have a Coveo account. If you do not have one, you can create a Coveo account at coveo.com.

Note

The module dialog fields that are displayed in bold (in the Make scenario, not in this documentation article) are mandatory!

Connecting Coveo to Make

To connect your Coveo account to Make you must obtain an API Key.

  1. Log in to your Coveo account.

  2. Under Organization in the left-hand menu, click API Keys.

    coveo_1.png
  3. Click Add key.

    coveo_2.png
  4. Configure your API key and make sure to provide privilege and access information.

  5. Click Copy to copy your API key to your clipboard. You will not be able to see the key again after this.

    coveo_3.png
  6. In Make, choose the Coveo module you want to use. Next to Connection, click Add.

  7. Choose a name for your connection and select the Organization type. Enter your API Key.

    coveo_4.png

You have now established the connection.

Search

Retrieves a list of query suggestions.

Connection

Establish a connection to your Coveo account.

Query

Enter your query.

Enable Word Completion

Select whether to attempt to complete the last word of the current basic query expression and boost the ranking score of the resulting expression so that it is returned as the first query suggestion.

Locale

Enter the locale of the current user. Must comply with IETF’s BCP 47 definition. For example: en-US.

Search Hub

Enter the search hub. The Search Hub is the first level of origin, typically the identifier of the graphical search interface from which the request originates.

Pipeline

Enter the name of the query pipeline to use. If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated).

Timezone

Select the timezone. If not specified, the default time zone of the server hosting the index is used.

Limit

Set the maximum number of suggestions Make returns during one scenario execution cycle.

Performs a simple query.

Connection

Establish a connection to your Coveo account.

Basic Query Expression

Enter your basic query expression. You can also use the built-in query suggestion tool.

Advanced Query Expression

Enter an advanced query expression. For example: @producttype=="Accessory"

Search Hub

Enter the search hub.

Sort Criteria

Select how you want to sort the query results. This only works when combining either two or more field criteria or a single date criteria with one or more field criteria.

Note

By default, the results are sorted by relevancy. A standard set of ranking rules is applied to compute a score value for each query result item; the higher a query result item score value is, the lower its 0-based index position.

Limit

Set the maximum number of results Make returns during one scenario execution cycle.

Performs an advanced query.

Connection

Establish a connection to your Coveo account.

Basic Query Expression

Enter your basic query expression. You can also use the built-in query suggestion tool and refer to the Perform a Simple Query module documentation.

Enable Did You Mean

Select whether to enable the Did You Mean feature of the index.

Note

The Did You Mean feature only processes the basic query expression.

When both the DidYouMean and MLDidYouMean parameter are set to Yes, the output of both features will appear in the queryCorrections array. 

Partial Match

Select whether to convert a basic expression containing at least partialMatchKeywords to a partial match expression, so that any item containing at least partialMatchThreshold of those keywords will match the expression.

If you do not set this parameter to Yes, an item must contain all of the basic expression keywords to match the expression.

Enable Wildcards

Select whether to enable the wildcards feature of the index. See Using Wildcards in Queries.

Enable Query Syntax

Select whether to interpret advanced Coveo Cloud query syntax as such in the basic query expression.

Enable ML Did You Mean

Select whether to enable the Coveo ML query suggestions Did You Mean feature.

Advanced Query Expression

Enter an advanced query expression. For example: @producttype=="Accessory"

Constant Query Expression

Enter a constant query expression. For example: @documenttype==forumpost.

The constant query expression, typically populated with expressions that must apply to all queries sent from a specific search interface (e.g., from a specific tab). Once evaluated, the result sets of those expressions are kept in a special cache.

Tip

Avoid including dynamic content in the constant query expression. Otherwise you risk filling up the cache with useless data, which can have a negative impact on performance.

Disjunction Query Expression

Enter a disjunction query expression. For example: @permanentid=aadd702687....

The disjunction query expression, typically populated by Coveo ML automatic relevance tuning models to ensure that relevant items are included in the query results. The resulting query expression is (((q aq) OR (dq)) cq).

Large Query Expression

Enter a large query expression. For example: I am looking for an enterprise-class native cloud SaaS/PaaS solution that ...

The large query expression, typically populated with a case description, long textual query, or any other form of text that can help refine a query.

Large Query Partial Match Max Keywords

Enter the maximum number of keywords from the large query expression that will be included in the partial match expression.

Large Query Partial Match Keywords

Enter the minimum number of keywords that need to be present in the large query expression to convert it to a partial match expression.

Large Query Partial Match Threshold

Enter a value indicating the minimum number of partial match expression keywords an item must contain to match the large query expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression. For example: 375% or all.

Excerpt Length

Enter the maximum length of result excerpts (in number of characters).

Retrieve First Sentences

Select whether to include the first sentences of textual items in the query results.

Fields to Include

Select the fields to include with each item in the query results. If specified, no other fields will be included.

Fields to Exclude

Select the fields to exclude from the query results. All other fields will be included with each item in the query result.

Group By

Select the Group By operations to perform on the query results, typically to extract facets.

Facets

Select the facet operations to perform on the query results.

Facet Options

Select the global configuration options that apply to all facet requests performed along with the query.

Category Facets

Select any data to easily query a hierarchical field using a path of hierarchical values.

Sort Criteria

Select the criteria to use for sorting the query results.

Note

You can specify a list of comma-separated sort criteria. However, this only works when combining:

  • Two or more field criteria (e.g., @views descending,@likes descending).

  • A single date criteria with one or more field criteria (e.g., date ascending,@views descending)

Ranking Functions

Select the array of ranking functions to execute on each query result item. The result of a ranking function is added to the result score, which can affect sorting.

Query Functions

Select the array of query functions to execute on each query result item. The result of a query function is stored in a temporary, dynamic field created at query time.

Enable Duplicate Filtering

Select whether to filter out duplicates, so that items resembling one another only appear once in the query results.

Note

Two items must be at least 85% similar to one another to be considered duplicates.

When a pair of duplicates is found, only the higher-ranked item of the two is kept in the result set.

Filter Field

Select the @-prefixed name of the field to use to group items into distinct folded query results.

Parent Field

Select the @-prefixed name of the field to use to be able to identify an item as a parent in a folded query result.

Child Field

Select the @-prefixed name of the field to use to be able to identify an item as a child of another item in a folded query result.

Filter Field

Select the @-prefixed name of the field to use to group items into distinct folded query results.

Search By ID

Select whether the q value contains the URI hash of a specific item that should be returned.

Syntax

Enter the name of the query syntax to apply when interpreting the basic query expression.

Summary Length

Enter the length of the automatically generated item summary. The index generates a result item summary independently from the query, as opposed to a result item excerpt, which is generated based on query keywords.

Static Query

Select whether to execute this query in a way that does not count against the allowed number of queries per month of a Coveo Cloud organization (QPM), but may produce cached/outdated query results.

User Actions

Enter the parameters allowing user actions to be retrieved in query results. For example: asmith@example.comc7ab60e2-e6b8-41e8-be6a-ad5c8edc662e.

Dictionary Field Context

Add a key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Pipeline

Enter the name of the query pipeline to use for this request (bypassing its conditions, if it has any).

Maximum Age

Enter the maximum age of cached results, in milliseconds.

Note

This parameter is automatically overridden when Static Query is set to Yes.

Search Hub

Enter the search hub. The Search Hub is the first level of origin, typically the identifier of the graphical search interface from which the request originates.

Tab

Enter the tab. The Tab is the second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Referrer

Enter the referrer. The Referrer is the third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Context

Enter the custom context information to send along with the request.

Note

Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings. For example: {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

Actions History

Select the query and page view actions previously made by the current user.

Recommendation

Enter the identifier of the recommendation interface from which the request originates.

Locale

Enter the locale of the current user. Must comply with IETF’s BCP 47 definition. For example: en-US.

Timezone

Enter the time zone to correctly interpret dates in the query expression and result items. For example: America/New_York. If not specified, the default time zone of the server hosting the index is used.

Index Token

Enter the encoded identifier of the index mirror to forward the request to.

Visitor ID

Enter a GUID representing the current user, who can be authenticated or anonymous. This GUID is normally generated by the usage analytics service and stored in a non-expiring browser cookie.

ML Parameters

Configure the map of options to pass to the Coveo ML models associated with the request’s target query pipeline.

Index Type

Enter the type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Index

Enter the identifier of the index mirror to forward the request to.

Logical Index

Enter the identifier for a logical group of indexes that have been configured to include documents form the same sources.

Maximum Timeout Ms

Enter the maximum number of milliseconds to allow the request to last before timing out.

Analytics

Configure the contextual information about the user performing the request and the request itself. See Analytics Request Parameters.

Limit

Set the maximum number of results Make returns during one scenario execution cycle.

For more information, see the Coveo Perform a Query documentation.

Push

Adds an item to a push source by the source ID or updates an item if it exists.

Connection

Establish a connection to your Coveo account.

Organization ID

Select the ID of the target Coveo Cloud V2 organization associated with the item.

Push Source ID

Select or enter the ID of the target push source. See Creating a Push Source.

Document ID

Enter the ID of the item. Must be the item URI. For example: file://folder/my-file.html

Upload Type

Select how you want to upload the item.

Raw Data: The raw textual item data.

Compressed Binary Data: The encoded item data.

File Container: The file container where the compressed or uncompressed, binary or non-binary item data was previously uploaded.

File Extension

Enter the file extension of the item data you are pushing. Value must include a preceding . character. For example: .html

Note

Specifying a value for this property is typically only useful when using the Compressed Binary Data to push item data.

Parent ID

Enter the URI of the parent item. For example: file://folder/

Permissions

Set the permission parameters for your item.

For more information, see the Coveo Push API documentation.

Removes an item to a push source and optionally its children by the document ID.

Connection

Establish a connection to your Coveo account.

Organization ID

Select the ID of the target Coveo Cloud V2 organization associated with the item.

Push Source ID

Select or enter the ID of the target push source. See Creating a Push Source.

Document ID

Enter the ID of the item. Must be the item URI. For example: file://folder/my-file.html

Delete Children

Select whether to also delete the children of the item.

For more information, see the Coveo Push API documentation.

Other

Performs an arbitrary authorized API Call.

Connection

Establish a connection to your Coveo account.

URL

Enter a path relative to https://{host}.cloud.coveo.com/rest. For example, /search/v2.

Notice

For the list of available endpoints, refer to the Coveo API Documentation.

Method

Select the HTTP method you want to use:

GET to retrieve information for an entry.

POST to create a new entry.

PUT to update/replace an existing entry.

PATCH to make a partial entry update.

DELETE to delete an entry.

Headers

Enter the desired request headers. You don't have to add authorization headers; we already did that for you.

Query String

Enter the request query string.

Body

Enter the body content for your API call.

The following API call returns all the campaigns from your Coveo account:

URL: organizations

Method: GET

coveo_5.png

Matches of the search can be found in the module's Output under Bundle > Body. Our example returned 1 organization:

coveo_6.png