Query & Query Rules
Query is the most crucial part of the search platform. They are the input provided by the user to match things in a certain indexed document. It is an OpenSearch concept. The queries can be simple text entries or highly filtered ones with multiple parameters such as boosts, burying, facets, and other filters to modify the search accordingly. The parameters of queries can be vendor-specific as well.
Query Rules are used to define the conditions based on which a query matches the available information in the index and thus triggers a specific action in response. They are a pure NoChannel Search concept. Each query rule is specific to the site. There are four different types of query rules.
According to this query rule, you can create filters for a query based on various properties such as brand name, manufacturer name, prices, and other similar fields.
The following code block is an example of how to create a query rule with filters. In it, the value of the filter is applied to the type name of the product. The value is set to "mattress". This means every product that has the term mattress in the type name in it, will be shown in the results.
POST https://api.upstartcommerce.com/v1/search/filter
Important parameters in the code block are:
- condition: This code block defines the condition based on which a query rule is to be applied. In the case of the example above, if the value of the query is "mattress", then the respective filter will become applicable. To understand the functionality of conditions, it is important to know the Query Rules Algebra.
- filters: This code block defines the filter that will be applied. In the example above, if a query corresponds to "mattress" then the filter has to return all the products with the same type name in them.
Using a similar code structure, you can Update, Delete, and perform other CRUD operations accordingly. The only change would be in defining the Type field which will change its value to the operation being performed.
The attach function allows filters to exist independently of a query pipeline. This means that users can attach one filter with multiple query pipelines. The API call to attach the created filter is:
POST https://api.upstartcommerce.com/v1/search/filter/attach/{resourceId}/to/{queryPipelineId}
Notice that the filter's name/id is added before 'to' and after it, the query pipeline name/id is defined.
The detach function allows users to remove a particular filter from the query pipeline. The API call to detach the created filter is:
POST https://api.upstartcommerce.com/v1/search/filter/detach/{resourceId}/to/{queryPipelineId}
Notice that the id of the filter is added before 'from' and after it, the query pipeline name/id is defined.
Following is the representation of the filter query rule in the search code block:
Notice that the term in the query field is "mattress". We created our filter query rule for this term. The total number of results is also specified in the search block.
To understand the functionality of the filter better, consider the following portion of the response. In it, the filter is inactive.
Notice that the total number of returned values without applying the filter returns 86. This means that there are 86 products that have the term mattress in their description, name, brand name, or other similar fields.
Notice that the total number of returned values after applying the filter has changed to 48. This means that there are 48 products that have the term mattress in their typename.
In this type of query rule, specific terms are given a boost. This means that if the specified boosted term is present in the query, then the results with the boosted term will appear on top. Users can apply boosts on multiple terms in the same query. The results will be arranged based on boost priority.
Following is an example of how to create a boost-based query rule. A boost query rule called protector is created and the value of the boost is set to 100. This means that if a user makes a query that contains the word protector in it, all the items with the word "protector" in them will be shown at the top of the search results.
POST https://api.upstartcommerce.com/v1/search/boosts
Other important fields are:
- condition Block: Here you will notice that the value is set to mattress protector.
- boosts Block: In the boosts code block, the list of terms has "protector". A boost of "100.0" is set in the next field. This means that the "protector" term will get a 100 times boost.
The attach function allows boosts to exist independently of a query pipeline. This means that users can attach one boost with multiple query pipelines. The API call to attach the created boost is:
POST https://api.upstartcommerce.com/v1/search/boosts/attach/{resourceId}/to/{queryPipelineId}
Notice that the boost's name/id is added before 'to' and after it the query pipeline name/id is defined.
The detach function allows users to remove a particular boost from the query pipeline. The API call to detach the created boost is:
POST https://api.upstartcommerce.com/v1/search/boosts/detach/{resourceId}/from/{queryPipelineId}
Notice that the id of the boost is added before 'from' and after it the query pipeline name/id is defined.
Following is the representation of the boost query rule in the search code block:
Notice that the term in the query field is "mattress protector". We created our boost query rule for this term. The total number of search results to be displayed is also specified in the search block which is 3.
The following code block represents a snippet of the response generated when a boost is applied.
Notice that the field "name" of the product "Your Choice Mattress Protector" contains the word "mattress protector" (the boosted word). This is why it appears on the top of all the other products.
The following code block represents a snippet of the response generated without any applied boost.
Notice that the field "name" of the product "Your Choice Mattress Protector" no longer appears at the top because the boost is not applied in this case.
According to this query rule, you can redirect users to a product page for a specific query based on various properties such as brand name, manufacturer name, prices, and other similar fields.
For example, if there is a redirect rule in place for the search term "iPhone", and a query with the search term iPhone is made, it will be redirected to the specified iPhone's brand page. Consider the following code block in which a redirect query rule is created. Every time there is a query with the term iPhone in it, the search results will be redirected to the specified path.
POST https://api.upstartcommerce.com/v1/search/redirect
The important field is:
- redirect: The redirect code block defines the URL path that the customer will be redirected to when the above conditions i.e. iPhone are searched in the query. It also defines the type of redirect which is RelativeRedirect in the example above.
The attach function allows redirects to exist independently of a query pipeline. This means that users can attach one redirect with multiple query pipelines. The API call to attach the created redirect is:
POST https://api.upstartcommerce.com/v1/search/redirect/attach/redirect_id/to/querypipeline
Notice that the redirect's name/id is added before 'to' and after it, the query pipeline name/id is defined.
The detach function allows users to remove a particular redirect from the query pipeline. The API call to detach the created redirect is:
POST https://api.upstartcommerce.com/v1/search/redirect/detach/redirect_id/to/querypipeline
Notice that the id of the redirect is added before 'from' and after it the query pipeline name/id is defined.
The following code block represents the search code with the query being iPhone.
Notice that the term in the query field is "iphone". We created our redirect query rule for this term.
The following code block represents a snippet of the response generated if the redirect query rule is created successfully.
In this type of query rule, aggregations are appended if a certain condition is satisfied. This means that if a particular term is searched in the query, a specific aggregation will be appended in the search results.
Following is an example of a code block to create an aggregation appender query rule. In the example below, every time there is a query containing "my mattress" an aggregation will be appended and will create a bucket of the products based on type name.
POST https://api.upstartcommerce.com/v1/search/aggregation-appender
The important fields are:
- condition block: The value is set to "my mattress" which means that the aggregation appender will be triggered if the search query is my mattress.
- aggregations: In the aggregations' block, a bucket of aggregations is defined in the field for typename.
The attach function allows aggregation appenders to exist independently of a query pipeline. This means that users can attach one aggregation appender with multiple query pipelines. The API call to attach the created aggregation appender is:
POST https://api.upstartcommerce.com/v1/search/aggregations-appender/attach/aggregationappender_id/to/querypipeline
Notice that the aggregation appender's name/id is added before 'to' and after it, the query pipeline name/id is defined.
The detach function allows users to remove a particular aggregation appender from the query pipeline. The API call to detach the created aggregation appender is:
POST https://api.upstartcommerce.com/v1/search/aggregations-appenders/detach/aggregationsappenders_id/from/querypipeline
Notice that the name or id of the aggregation appender is added before 'from' and after it, the query pipeline name/id is defined.
The following code block represents the search code with the query being iPhone. The result size is set to 2.
The following code block represents a snippet from the generated response once the aggregation appender is applied.
In the example above, it is obvious that since no aggregation appender was applied, no aggregation in the response is empty.
The following code block represents a snippet from the generated once the aggregation appender is applied.
In the example above, there is an active aggregation appender rule, which is why buckets are created with a "mattress" key. The doc_count shows that the word "mattress" appears 48 times in the field of the type name of the document.