Use the Query Configurations API
Use the Query Configurations API
A query configuration is a JSON object that lets you set certain parameters for queries sent from search interfaces and product listing pages (PLPs). Although products can be retrieved from the index without a query configuration, you’ll need to create one to configure the following:
-
Sort criteria
-
Additional fields
-
Number of results per page
-
Number of children per result
-
Product grouping
|
Note
If the Facet manager isn’t enabled for your Coveo organization, you’ll also use query configurations to set up facets for your search interface or product listing pages (PLPs). The Facet manager in the CMH is currently in open beta. If you gained access to the CMH before the Facet manager was available and would like to adopt it, contact your Coveo representative. |
Query configurations can be scoped as global or specific. Both let you set the same parameters, but specific query configurations can’t be used with all product discovery solutions:
The parameters in a global query configuration are the default that applies to all queries, while those in a specific query configuration only apply to a single PLP.
If there’s a conflict between a global and specific configuration, then the parameters in the specific configuration take precedence.
Create a query configuration
To create a query configuration, make the following request to the Query Configurations API:
POST https://platform.cloud.coveo.com/rest/organizations/<ORGANIZATION_ID>/commerce/v2/configurations/query HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************where <ORGANIZATION_ID> is the unique identifier of your Coveo organization.
To learn how to find your organization ID, see Find your organization ID.
The following is the basic payload to create a query configuration. More complete examples are included in the other sections of this article.
{
"trackingId": "<TRACKING_ID>", 
"solutionType": "<SOLUTION_TYPE>", 
"targets": [], 
"isGlobal": <SCOPE>, 
"configurationModel": {
"additionalFields": [],
"facets": { 
"facets": []
},
"perPage": <NUMBER_OF_RESULTS>,
"sorts": [],
"numberOfChildren": <NUMBER_OF_CHILDREN>, 
"grouping": {
"type": "<GROUPING>" 
}
}
} |
trackingId lets you segregate your query configurations.
When you make a request via the Commerce API to retrieve this configuration, you’ll need to specify the tracking ID to retrieve the configuration. |
|
solutionType is the product discovery solution to which this query configuration applies.
This can be either search or listing. |
|
targets lets you specify the name of a single product listing page (PLP) to which this query configuration applies.
This parameter is only used in specific query configurations for PLPs.
In a global query configuration, omit this parameter. |
|
isGlobal defines the scope of the query configuration.
This is true for a global configuration and false for a specific one. |
|
Only use the facets parameter if you’re managing facets directly via the Commerce API.
If you’re using the Coveo Merchandising Hub (CMH), use the Facet manager instead. |
|
numberOfChildren sets the maximum number of child items to include in a folded query result. |
|
If the query pipeline that routes queries for this tracking ID and solution is configured for product grouping, set the grouping type to query_pipeline.
Otherwise, set it to none.
Pin rules will respect this setting. |
The resulting query configuration will apply to queries that meet all of the following criteria:
-
They include the defined tracking ID.
-
They originate from an interface of the defined solution type.
-
If the query configuration isn’t global, they originate specifically from the product listing page (PLP) defined in
targets.
Global query configurations
Global query configurations define certain common elements that you want returned with each query.
You don’t have to create a global query configuration before you can query products from a search interface or product listing page (PLP). However, you’ll need one to specify the sort criteria, additional fields, and a few other parameters that apply when your front end queries the Commerce API.
Sample global configuration for search
The following global query configuration for the Search solution retrieves the collection and color fields, returns 10 results per page, and sorts by relevance:
{
"trackingId": "barca_sports_ca",
"solutionType": "search",
"isGlobal": true,
"configurationModel": {
"additionalFields": [
"collection",
"color"
],
"perPage": 10,
"sorts": [
{
"sortCriteria": "relevance"
}
],
"numberOfChildren": 0,
"grouping": {
"type": "none"
}
}
} |
For the Search product discovery solution, set solutionType to search. |
||
|
In a global query configuration, set isGlobal to true. |
||
|
configurationModel lets you specify the following parameters: additionalFields, perPage, sorts, numberOfChildren, and grouping.
You can also configure
|
Sample global configuration for listings
The following global query configuration for the Product listings solution retrieves the collection and color fields, returns 20 results per page, and sorts by relevance:
{
"trackingId": "barca_sports_ca",
"solutionType": "listing",
"isGlobal": true,
"configurationModel": {
"additionalFields": [
"collection",
"color"
],
"perPage": 20,
"sorts": [
{
"sortCriteria": "relevance"
}
],
"numberOfChildren": 0,
"grouping": {
"type": "none"
}
}
} |
For the Product listings product discovery solution, set solutionType to listing. |
||
|
In a global query configuration, set isGlobal to true. |
||
|
configurationModel lets you specify the following parameters: additionalFields, perPage, sorts, numberOfChildren, and grouping.
You can also configure
|
Specific query configurations
Specific query configurations define certain common elements that you want returned with each query on a particular product listing page (PLP). They let you customize these elements if you want certain PLPs to behave differently from the default parameters defined in the global query configuration.
For example, the default behaviour for your PLPs might be to sort by relevance, but you want to sort by price on the "Promotions" PLP.
The following specific query configuration targets the Accessories|Bags product listing page (PLP).
It retrieves the color and size fields, returns 20 results per page, and sorts by price (based on the ec_price field) in ascending order:
{
"trackingId": "barca_sports_ca",
"solutionType": "listing",
"targets": [
"Accessories|Bags"
],
"isGlobal": false,
"configurationModel": {
"additionalFields": [
"color",
"size"
],
"perPage": 20,
"sorts": [
{
"sortCriteria": "fields",
"fields": [
{
"field": "ec_price",
"direction": "asc",
"displayNames": [
{
"value": "Price",
"language": "en"
},
{
"value": "Prix",
"language": "fr"
}
]
}
]
}
],
"numberOfChildren": 0,
"grouping": {
"type": "none"
}
}
} |
For the Product listings product discovery solution, set solutionType to listing. |
||
|
The name of the specific product listing page (PLP) to which this query configuration applies.
Each specific configuration can only apply to one PLP, so the targets array can only hold a single value. |
||
|
In a specific query configuration, set isGlobal to false. |
||
|
configurationModel lets you specify the following parameters: additionalFields, perPage, sorts, numberOfChildren, and grouping.
You can also configure
|
Use a query configuration to manage facets
You should use the Facet manager in the Coveo Merchandising Hub (CMH) to configure facets for your search interface or product listing page (PLP).
|
The Facet manager in the CMH is currently in open beta. If you gained access to the CMH before the Facet manager was available and would like to adopt it, contact your Coveo representative. |
However, you can use a query configuration to set up your facets if the Facet manager isn’t enabled for your Coveo organization.
The following specific query configuration targets the Canoes & Kayaks product listing page (PLP).
It retrieves the color and storage fields, configures several facets, returns 20 results per page, and sorts by price (based on the ec_price field) in ascending order:
{
"trackingId": "barca_sports_ca",
"solutionType": "listing",
"targets": [
"Canoes & Kayaks"
],
"isGlobal": false,
"configurationModel": {
"additionalFields": [
"color",
"storage"
],
"facets": {
"enableIndexFacetOrdering": true,
"freezeFacetOrder": true,
"facets": [
{
"facetId": "year",
"field": "year",
"displayNames": [
{
"value": "Year",
"language": "en"
},
{
"value": "Année",
"language": "fr"
}
],
"values": [
{
"state": "idle",
"preventAutoSelect": false,
"start": "2023/10/01@00:00:00",
"end": "2023/10/31@23:59:59",
"endInclusive": true
},
{
"state": "idle",
"preventAutoSelect": true,
"start": "2023/11/01@00:00:00",
"end": "2023/11/30@23:59:59",
"endInclusive": false
},
{
"state": "selected",
"preventAutoSelect": true,
"start": "2023/12/01@00:00:00",
"end": "2023/12/31@23:59:59",
"endInclusive": true
}
],
"numberOfValues": 3,
"preventAutoSelect": false,
"sortCriteria": "score",
"isFieldExpanded": true,
"type": "dateRange",
"generateAutomaticRanges": true
},
{
"facetId": "ec_category",
"field": "ec_category",
"displayNames": [
{
"value": "Category",
"language": "en"
},
{
"value": "Catégorie",
"language": "fr"
}
],
"values": [
{
"state": "selected",
"preventAutoSelect": true,
"value": "Canoes & Kayaks",
"children": [
{
"state": "selected",
"preventAutoSelect": true,
"value": "Kayaks",
"children": [
{
"state": "selected",
"preventAutoSelect": true,
"value": "Folding Kayaks"
}
]
},
{
"state": "idle",
"preventAutoSelect": true,
"value": "Sea Kayaks"
}
]
},
{
"state": "selected",
"preventAutoSelect": false,
"value": "Canoes"
}
],
"numberOfValues": 5,
"preventAutoSelect": true,
"sortCriteria": "score",
"isFieldExpanded": true,
"type": "hierarchical",
"delimitingCharacter": "|",
"basePaths": {
"value": [
"Boats"
],
"language": "en"
},
"filterByBasePath": true
},
{
"facetId": "ec_brand",
"field": "ec_brand",
"displayNames": [
{
"value": "string",
"language": "en"
}
],
"values": [
{
"state": "idle",
"value": "string"
}
],
"numberOfValues": 0,
"type": "regular",
"latitude": "@latitude",
"longitude": "@longitude"
},
{
"facetId": "ec_price",
"field": "ec_price",
"displayNames": [
{
"value": "Price",
"language": "en"
},
{
"value": "Prix",
"language": "fr"
}
],
"values": [
{
"state": "idle",
"preventAutoSelect": true,
"start": "0",
"end": "999",
"endInclusive": "true"
},
{
"state": "selected",
"preventAutoSelect": true,
"start": "1000",
"end": "2000",
"endInclusive": "false"
},
{
"state": "selected",
"preventAutoSelect": true,
"start": "2001",
"end": "3000",
"endInclusive": "false"
}
],
"numberOfValues": 3,
"preventAutoSelect": true,
"sortCriteria": "score",
"isFieldExpanded": true,
"type": "numericalRange",
"generateAutomaticRanges": true,
"rangeAlgorithm": "equiprobable"
},
{
"facetId": "ec_brand",
"field": "ec_brand",
"displayNames": [
{
"value": "Brand",
"language": "en"
},
{
"value": "Marque",
"language": "fr"
}
],
"values": [
{
"state": "selected",
"preventAutoSelect": false,
"value": "Aqua Sports"
},
{
"state": "idle",
"preventAutoSelect": false,
"value": "Aqua Marina"
},
{
"state": "idle",
"preventAutoSelect": false,
"value": "HO Sports"
}
],
"numberOfValues": 3,
"preventAutoSelect": false,
"sortCriteria": "score",
"isFieldExpanded": true,
"type": "regular",
"customOrder": [
"string"
]
}
]
},
"perPage": 20,
"sorts": [
{
"sortCriteria": "fields",
"fields": [
{
"field": "ec_price",
"direction": "asc",
"displayNames": [
{
"value": "Price",
"language": "en"
},
{
"value": "Prix",
"language": "fr"
}
]
}
]
}
],
"numberOfChildren": 0,
"grouping": {
"type": "none"
}
}
} |
For the Product listings product discovery solution, set solutionType to listing. |
|
The name of the specific product listing page (PLP) to which this query configuration applies.
Each specific configuration can only apply to one PLP, so the targets array can only hold a single value. |
|
In a specific query configuration, set isGlobal to false. |
|
configurationModel lets you specify the following parameters: additionalFields, facets, perPage, sorts, numberOfChildren, and grouping. |
Very useful
Not really
Very useful
Not really