Query Manipulation
Information about the different types of query profiles and query manipulation rules that you can use.

Query Manipulation

Query manipulation allows you to modify the queries that your users send to existing text indexes, or modify the results that these queries return.

To use query manipulation, you use the Create Query Profile API to create query profiles, which define what kind of manipulations you want to perform. You can then create rules, which define the manipulations and how to modify the query or results. You use the Add to Text Index API to add these rules to a text index with the query manipulation flavor.

After you create query profiles and rules, you can use a query profile with the Query Text Index API to manipulate queries.

The following sections describe how to create and use Query Profiles and query manipulation rules.

Create Query Profile API

The Create Query Profile API allows you to create a query profile. To create a query profile, you must have a query manipulation flavor text index, which you can create by using the Create Text Index API.

Query profiles allow you to configure how a query is manipulated according to your rules stored in the query manipulation flavor index. You can use a query profile with the Query Text Index API to manipulate queries.

The following query manipulations are supported:

  • Promotions. Promotions allow you to return specific documents to include in the results of your query, or as the results of a separate promotion query. There are different types of promotions to allow you to define promotion documents manually, or to dynamically return promotions according to a query. You can also specify promotion documents that you want to insert at a specified position in the query results. The following query profile parameters affect promotions:

    Parameter Description
    promotions_enabled Set this parameter to true to enable promotions in the query profile.
    promotion_categories A list of promotion categories that you want to allow for the query profile. You can set promotion categories in the rules to allow you to filter your promotions. You can leave this parameter empty if you do not want to apply filters.
    promotions_identified Set this parameter to true to return an additional field in each query result document to indicate whether it is a promoted document. This option can make it easier to check that your promotions work correctly with the original query.
  • Synonyms. Synonyms allow you to modify an original query for a particular term to include other terms that you define, such that all terms marked as synonyms return the same query results. For example if you define cat as a synonym for dog, a query for dog returns the same result as a query for cat. You define synonyms as rules, which are stored in the query manipulation index. The following query profile parameters affect synonyms:

    Parameter Description
    synonyms_enabled Set this parameter to true to enable synonyms in the query profile.
    synonym_categories A list of synonym categories that you want to allow for the query profile. You can set synonym categories in the rules to allow you to filter your synonyms. You can leave this parameter empty if you do not want to apply filters.
  • Blacklists. Blacklists allow you to modify the original query to remove certain terms. For example, if you define dog as a blacklist term, a query for cat dog returns the same results as a query for cat. The following query profile parameters affect blacklists:

    Parameter Description
    blacklists_enabled Set this parameter to true to enable blacklists in the query profile.
    blacklist_categories A list of blacklist categories that you want to allow for the query profile. You can set blacklist categories in the rules to allow you to filter your blacklists. You can leave this parameter empty if you do not want to apply filters.

Update Query Profile API

The Update Query Profile API allows you to update any configured parameters for an existing query profile.

Note: You cannot make partial updates to the query profile. The API resets any parameters that you do not update to their default values.

Retrieve Query Profile API

The Retrieve Query Profile API allows you to retrieve all the information for your configured query profile. It returns a response of the following form:

{
   "query_profile": "myqueryprofile",
   "description": "myqueryprofile description",
   "query_manipulation_index": "myquerymanipulationindex",
   "promotions_enabled":true,
   "promotion_categories": ["pcategory1"],
   "promotions_identified": true,
   "synonyms_enabled": true,
   "synonym_categories": ["scategory1"],
   "blacklists_enabled": true,
   "blacklist_categories": ["bcategory1"]
}

List Query Profiles

To return a list of your existing query profiles, you can use the List Resources API, with the type parameter set to query_profile.

Query Text Index

The Query Text Index API has two parameters related to query manipulation:

Parameter Description
query_profile An existing query profile that you want to use for query manipulation.
promotion Set this parameter to true to return only promotion documents that return from the query manipulation.
  • DYNAMIC_PROMOTION, STATIC_REFERENCE_PROMOTION, and STATIC_CONTENT_PROMOTION rules apply and return results only when you set promotion to true.
  • SYNONYM and BLACKLIST rules apply whether you set promotion to true or false. You can apply these rules to normal queries and promotion queries.
  • CARDINAL_PLACEMENT rules apply only when you set promotion to false.

Find Similar

The Find Similar API has one parameter related to query manipulation:

Parameter Description
query_profile An existing query profile that you want to use for query manipulation.

When you use a query profile with the Find Similar API, the API applies any matching SYNONYM and BLACKLIST rules to the original query text (that is, the best terms from the query document or text). It uses the modified query text to find documents that are similar to the original text.

The API also queries the query manipulation index that the query profile specifies for CARDINAL_PLACEMENT promotion rules that the modified query matches. It processes and returns any cardinal placement documents in the appropriate position in the API results.

Get Parametric Values

The Get Parametric Values API has one parameter related to query manipulation:

Parameter Description
query_profile An existing query profile that you want to use for query manipulation.

When you use a query profile with the Get Parametric Values API, the API applies any SYNONYM and BLACKLIST rules to the original query text. It uses the modified query text to find matching documents, and retrieves the list of values for the parametric fields that you specify in the API.

The API also queries the query manipulation index that the query profile specifies for DYNAMIC_PROMOTION, STATIC_REFERENCE_PROMOTION, and CARDINAL_PLACEMENT promotion rules that the modified query matches. It processes and retrieves any promotion documents for these matching promotions, and checks the promotion documents for the parametric fields that you specify. If the promotion documents contain the specified fields, the API returns the values for these fields from the promotion documents in the Get Parametric Values API response. If you request counts for the parametric values, the API also updates the count information for the field values to include any values that occur in promotions documents.

Query Manipulation Rules

Rules define how to modify the query and results. You add rules as documents in the query manipulation flavor text index that you configure for your query profile, by using the Add to Text Index API. When you send a query using the Query Text Index API with a query profile, the API queries the query manipulation index that the query profile specifies for rules that the query matches, and applies the manipulations.

There are six types of rules that you can define. You set the rule type by defining the ruletype field in the rule document. The following sections describe the format for the rule documents, and provide examples of the rules and their effects.

Note: If you add any rules into the query manipulation index that do not follow the correct rule format, and this rule is activated by a query, the query profile ignores the rule and returns a warning.

Note: The DYNAMIC_PROMOTION, STATIC_REFERENCE_PROMOTION, and CARDINAL_PLACEMENT promotion rules retrieve promotion documents by querying an existing text index (which does not have to be the text index that the user is querying). If an error occurs during the internal processing for these rules, for example while querying a secondary index, the query profile ignores the rule and returns a warning.

DYNAMIC_PROMOTION

Dynamic promotions allow you to return a set of promotion documents, based on a query to existing text indexes, which you define. For example, you might have a regularly changing text index containing promotion items, and the dynamic promotion retrieves the most relevant current promotions for a particular query.

A dynamic promotion rule must have the following document fields:

Field Type Description
ruletype Enum The rule type. For dynamic promotions set this field to DYNAMIC_PROMOTION.
reference String An identifier for the rule.
dynamic_querytext String The query text to use to query the configured text indexes for the dynamic promotion.
dynamic_index Array A list of names of the text indexes to query for the dynamic promotion.

You can optionally include the following document fields:

Field Type Description
content String The content that the original query must match against for the rule to be applied in the query manipulation.
title String A title for the rule.
booleanrestriction String A Boolean or proximity matching expression that the original query must match for the rule to be applied for query manipulation.

When you use a query profile for a query, Haven OnDemand matches the original query text against the content fields in your rules. For matching rules, it then matches the query text against the booleanrestriction field. The rule is applied if the booleanrestriction expression also matches the original query text.
dynamic_results Number The total number of documents to retrieve from configured text indexes for the dynamic promotion.
category Array A list of category names for the dynamic promotion. For the query profile to apply the rule, at least one of these categories must match the promotion_categories parameter in the query profile configuration.

Example dynamic promotion rules:

{
   "document": [
      {
         "reference": "dynamic_promotion_1",
         "ruletype": "DYNAMIC_PROMOTION",
         "content": "cats dogs",
         "title": "dynamic_promotion_1_title",
         "booleanrestriction": "cats AND dogs",
         "dynamic_querytext": "football, animal, hp, desk",
         "dynamic_index": ["wiki_eng", "news_eng"],
         "category": ["cats", "dogs"]
      },
      {
         "reference": "dynamic_promotion_2",
         "ruletype": "DYNAMIC_PROMOTION",
         "content": "computers",
         "title": "dynamic_promotion_2_title",
         "dynamic_querytext": "elephants",
         "dynamic_index": "wiki_eng",
         "dynamic_results": "2",
         "category": ["computers"]
      }
   ]
}

This example has two dynamic promotion rules.

The first rule dynamic_promotion_1 applies for queries where:

  • the original query text contains at least one of the terms cats or dogs (to match the content for the rule).
  • the original query text contains both the terms cats and dogs (to match the booleanrestriction for the rule).
  • the query profile that you specify has a promotion_categories parameter that contains at least one of the cats or dogs categories, or is empty.
  • the query profile that you specify has the promotions_enabled parameter set to true.

When a query activates this rule, it sends an additional query to the wiki_eng and news_eng text indexes (specified by the dynamic_index field), with the query text football, animal, hp, desk (specified by the dynamic_querytext field). The results of this additional query return as promotion results. If the query profile that you specify has the promotion_identified parameter set to true, each result contains an additional promotion field, with the value true to indicate that the document is a promotion.

The second rule dynamic_promotion_2 applies for queries where:

  • the original query text contains the term computers (to match the content for the rule).
  • the query profile that you specify has a promotion_categories parameter that contains the category computers, or is empty.
  • The query profile that you specify has the promotions_enabled parameter set to true.

When a query activates this rule, it sends an additional query to the wiki_eng text index (specified by the dynamic_index field), with the query text elephants (specified by the dynamic_querytext field). It returns the first two results as promotion results (the dynamic_results field for the rule is set to 2).

STATIC_REFERENCE_PROMOTION

Static reference promotions allow you to insert documents into the promotion results, based on references for specific documents in existing text indexes. For example, you might have a set of promotion documents in a text index, where you might update the content of the documents. Static reference promotions allow you to always return the most recent version of a promotion document, without having to update the promotion rules.

A static reference promotion rule must have the following document fields:

Field Type Description
ruletype Enum The rule type. For static reference promotions, set this field to STATIC_REFERENCE_PROMOTION.
reference String An identifier for the rule.
target_reference Array A list of document references that you want to return as promotions. These references must exist in the text indexes that you set for target_index (that is, the Nth target_reference is stored in the Nth target_index). The length of this array must be the same as the length of the target_index array.
target_index Array A list of names of the text indexes that contain the documents with the specified references (the Nth target_reference is stored in the Nth target_index). The length of this array must be the same as the length of the target_reference array.

You can optionally include the following document fields:

Field Type Description
content String The content that the original query must match against for the rule to be applied in the query manipulation.
title String A title for the rule.
booleanrestriction String A Boolean or proximity matching expression that the original query must match for the rule to be applied for query manipulation.

When you use a query profile for a query, Haven OnDemand matches the original query text against the content fields in your rules. For matching rules, it then matches the query text against the booleanrestriction field. The rule is applied if the booleanrestriction expression also matches the original query text.
category Array A list of category names for the static reference promotion. For the query profile to apply the rule, at least one of these categories must match the promotion_categories parameter in the query profile configuration.

Example static reference promotion rules:

{
   "document": [
      {
         "reference": "target_promotion_1",
         "ruletype": "STATIC_REFERENCE_PROMOTION",
         "content": "cats dogs",
         "title": "target_promotion_1_title",
         "booleanrestriction": "cats AND dogs",
         "target_reference": "http://rss.cnn.com/~r/rss/cnn_world/~3/wlxwt_gvoIM/index.html",
         "target_index": "news_eng",
         "category": ["target"]
      },
      {
         "reference": "target_promotion_2",
         "ruletype": "STATIC_REFERENCE_PROMOTION",
         "content": "computers",
         "title": "target_promotion_2_title",
         "target_reference": [
            "http://www.huffingtonpost.com/dr-dave-randle/a-new-model-for-excellenc_b_5327425.html",
            "http://rss.cnn.com/~r/rss/cnn_world/~3/wlxwt_gvoIM/index.html"
         ],
         "target_index": ["wiki_eng", "news_eng"],
         "category": ["target"]
      }
   ]
}

This example has two static reference promotion rules.

The first rule target_promotion_1 applies for queries where:

  • the query text contains at least one of the terms cats or dogs (to match the content for the rule).
  • the query text contains both the terms cats and dogs (to match the booleanrestriction for the rule).
  • the query profile that you specify has a promotion_categories parameter that contains the category target, or is empty.
  • The query profile that you specify has the promotions_enabled parameter set to true.

When a query activates this rule, it retrieves the document with reference http://rss.cnn.com/~r/rss/cnn_world/~3/wlxwt_gvoIM/index.html (specified by the target_reference field) from the news_eng text index (specified by the target_index field). This document returns as a promotion result. If the query profile that you specify has the promotion_identified parameter set to true, each result contains an additional promotion field, with the value true to indicate that the document is a promotion.

The second rule target_promotion_2 applies for queries where:

  • the query text contains the term computers (to match the content for the rule).
  • the query profile that you specify has a promotion_categories parameter that contains the category target, or is empty.
  • the query profile that you specify has the promotions_enabled parameter set to true.

When a query activates this rule, it retrieves the document with reference http://www.huffingtonpost.com/dr-dave-randle/a-new-model-for-excellenc_b_5327425.html (specified by the target_reference field) from the wiki_eng text index (specified by the target_index field). It also retrieves the document with the second configured reference, http://rss.cnn.com/~r/rss/cnn_world/~3/wlxwt_gvoIM/index.html, from the second configured text index, news_eng. These documents return as promotion results.

STATIC_CONTENT_PROMOTION

Static content promotions allow you to provide title, reference, and content fields that you want to use as the promotion result. For example, you might have a particular set of documents that you want to use as promotions, which do not exist in a text index.

A static content promotion rule must have the following document fields:

Field Type Description
ruletype Enum The rule type. For static content promotions set this field to STATIC_CONTENT_PROMOTION.
reference String An identifier for the rule.
static_reference String The document reference to use as the reference field for the promoted document.
static_title String The document title to use as the title field for the promoted document.
static_content String The document content to use as the content field for the promoted document. When a summary is required, this field is also used as the summary field for the promoted document.

You can optionally include the following document fields:

Field Type Description
content String The content that the original query must match against for the rule to be applied in the query manipulation.
title String A title for the rule.
booleanrestriction String A Boolean or proximity matching expression that the original query must match for the rule to be applied for query manipulation.

When you use a query profile for a query, Haven OnDemand matches the original query text against the content fields in your rules. For matching rules, it then matches the query text against the booleanrestriction field. The rule is applied if the booleanrestriction expression also matches the original query text.
category Array A list of category names for the static content promotion. For the query profile to apply the rule, at least one of these categories must match the promotion_categories parameter in the query profile configuration.

Example static content promotion rules:

{
   "document": [
      {
         "reference": "static_promotion_1",
         "ruletype": "STATIC_CONTENT_PROMOTION",
         "content": "cats dogs",
         "title": "static_promotion_1_title",
         "booleanrestriction": "cats AND dogs",
         "static_reference": "static_promotion_1_static_reference",
         "static_title": "static_promotion_1_static_title",
         "static_content": "static_promotion_1_static_content",
         "category": ["cats", "dogs"]
      },
      {
         "reference": "static_promotion_2",
         "ruletype": "STATIC_CONTENT_PROMOTION",
         "content": "cats dogs",
         "title": "static_promotion_2_title",
         "booleanrestriction": "cats OR dogs",
         "static_reference": "static_promotion_2_static_reference",
         "static_title": "static_promotion_2_static_title",
         "static_content": "static_promotion_2_static_content",
         "category": ["cats", "dogs"]
      }
   ]
}

This example has two static content promotion rules.

The first rule static_promotion_1 applies for queries where:

  • the query text contains at least one of the terms cats or dogs (to match the content for the rule).
  • the query text has to contain both the terms cats and dogs (to match the booleanrestriction for the rule).
  • the query profile that you specify has a promotion_categories parameter that contains at least one of cats or dogs categories, or is empty.
  • the query profile that you specify has the promotions_enabled parameter set to true.

When a query activates this rule, it returns a promotion document with the reference field static_promotion_1_static_reference (specified by the static_reference field in the rule), the title field static_promotion_1_static_title (specified by the static_title field in the rule), and the content field static_promotion_1_static_content (specified by the static_content rule field). If the Query Text Index API call has the summary parameter set, the promotion document also has a summary field, with the value static_promotion_1_static_content (specified by the static_content rule field). If the query profile that you specify has the promotion_identified parameter set to true, each result contains an additional promotion field, with the value true to indicate that the document is a promotion.

The second rule static_promotion_2 applies for queries where:

  • the query text contains at least one of the terms cats or dogs (to match the content for the rule).
  • the query text contains at least one of the terms cats or dogs (to match the booleanrestriction for the rule).
  • the query profile that you specify has a promotion_categories parameter that contains at least one of the cats or dogs categories, or is empty.
  • the query profile that you specify has the promotions_enabled set to true.

When a query activates this rule, it returns a promotion document with the reference field static_promotion_2_static_reference (specified by the static_reference field in the rule), the title field static_promotion_2_static_title (specified by the static_title field in the rule), and the content field static_promotion_2_static_content (specified by the static_content rule field). If the Query Text Index API call has the summary parameter set, the promotion document also has a summary field, with the value static_promotion_2_static_content (specified by the static_content rule field).

CARDINAL_PLACEMENT

Cardinal placement promotions allow you to insert documents into query results at specified positions, based on references for specific documents in existing text indexes. For example, for a given query, you might want a particular document to always occur in the top five results of the query.

A cardinal placement promotion rule must have the following document fields:

Field Type Description
ruletype Enum The rule type. For cardinal placement promotions this should be set to CARDINAL_PLACEMENT.
reference String An identifier for the rule.
target_reference Array A list of document references that you want to return as cardinal placement promotions. These references must exist in the text indexes that you set for target_index (the Nth target_reference is stored in the Nth target_index). The length of this array must be the same as the length of target_index and defined_position arrays .
target_index Array A list of text index names to search for documents that matches configured references (the Nth target_reference is stored in the Nth target_index). The length of this array must be the same as the length of the target_reference and defined_position arrays.
defined_position Array A list of integer positions to insert promoted documents into query results, where 1 is the first result in the list. The length of this array must be the same as the length of the target_reference and target_index array (the Nth target_reference is returned at the position defined by the Nth defined_position value).

You can optionally include the following document fields:

Field Type Description
content String The content that the original query must match against for the rule to be applied in the query manipulation.
title String A title for the rule.
booleanrestriction String A Boolean or proximity matching expression that the original query must match for the rule to be applied for query manipulation.

When you use a query profile for a query, Haven OnDemand matches the original query text against the content fields in your rules. For matching rules, it then matches the query text against the booleanrestriction field. The rule is applied if the booleanrestriction expression also matches the original query text.
category Array A list of category names for the cardinal placement promotion. For the query profile to apply the rule, at least one of these categories must match the promotion_categories parameter in the query profile configuration.

Example cardinal placement promotion rules:

{
   "document": [
      {
         "reference": "cardinal_placement_promotion_1",
         "ruletype": "CARDINAL_PLACEMENT",
         "content": "cats dogs",
         "title": "cardinal_placement_promotion_1_title",
         "booleanrestriction": "cats AND dogs",
         "target_reference": "http://rss.cnn.com/~r/rss/cnn_world/~3/wlxwt_gvoIM/index.html",
         "target_index": "news_eng",
         "defined_position": [2],
         "category": ["cardinal"]
      },
      {
         "reference": "cardinal_placement_promotion_2",
         "ruletype": "CARDINAL_PLACEMENT",
         "content": "computers",
         "title": "cardinal_placement_2_title",
         "target_reference": [
            "http://www.huffingtonpost.com/dr-dave-randle/a-new-model-for-excellenc_b_5327425.html",
            "http://rss.cnn.com/~r/rss/cnn_world/~3/wlxwt_gvoIM/index.html"
         ],
         "target_index": ["wiki_eng", "news_eng"],
         "defined_position": [1, 5],
         "category": ["cardinal"]
      }
   ]
}

This example has two cardinal placement promotion rules.

The first rule cardinal_placement_promotion_1 applies for queries where:

  • the query text contains at least one of the terms cats or dogs (to match the content for the rule).
  • the query text contains both the terms cats and dogs (to match the booleanrestriction for the rule).
  • the query profile that you specify has a promotion_categories parameter that contains the category cardinal, or is empty.
  • the query profile that you specify has the promotions_enabled parameter set to true.

When a query activates this rule, it retrieves the document with reference http://rss.cnn.com/~r/rss/cnn_world/~3/wlxwt_gvoIM/index.html (specified by the target_reference field) from the news_eng text index (specified by the target_index field). It places this result second in the query results (specified by the defined_position field). If the query profile that you specify has the promotion_identified parameter set to true, each result contains an additional promotion field, with the value true to indicate that the document is a promotion. In the query results list, normal documents contain the promotion field with the value false, to indicate that it is not a promoted document.

The second rule cardinal_placement_promotion_2 applies for queries where:

  • the query text contains the term computers (to match the content for the rule).
  • the query profile that you specify has a promotion_categories parameter that contains the category cardinal, or is empty.
  • the query profile that you specify has the promotions_enabled parameter set to true.

When a query activates this rule, it retrieves the document with reference http://www.huffingtonpost.com/dr-dave-randle/a-new-model-for-excellenc_b_5327425.html (specified by the target_reference field), from the wiki_eng text index (specified by the target_index field). It also retrieves the document with the second configured reference, http://rss.cnn.com/~r/rss/cnn_world/~3/wlxwt_gvoIM/index.html, from the second configured text index, news_eng. It returns the first document as the first result, and the second document as the fifth result in the query results, as specified by the defined_position field.

SYNONYM

Synonym rules allow you to manipulate the original query text to include additional terms that you define to have the same meaning. For example, you might want to ensure queries for a particular product type also return results for closely related products.

Note: If a blacklist and synonym rule both apply to a query, the blacklist rule takes precedence.

A synonym rule must have the following document fields:

Field Type Description
ruletype Enum The rule type. For synonym rules, set this field to SYNONYM.
reference String An identifier for the rule.
synonym_remove Array A list of terms that you want to remove from the original query. The rule replaces these terms by the list you set in the synonym_add field. If this array is empty, the rule inserts all the synonym_add terms at the end of the query text.
synonym_add Array A list of terms that replaces the removed terms that you set in the synonym_remove field. This array must not be empty.

You can optionally include the following document fields:

Field Type Description
content String The content that the original query must match against for the rule to be applied in the query manipulation.
title String A title for the rule.
booleanrestriction String A Boolean or proximity matching expression that the original query must match for the rule to be applied for query manipulation.

When you use a query profile for a query, Haven OnDemand matches the original query text against the content fields in your rules. For matching rules, it then matches the query text against the booleanrestriction field. The rule is applied if the booleanrestriction expression also matches the original query text.
category Array A list of category names for the synonym rule. For the query profile to apply the rule, at least one of these categories must match the synonym_categories parameter in the query profile configuration.

Example synonym rule:

{
   "document": [
      {
         "reference": "synonym_1",
         "ruletype": "SYNONYM",
         "content": "cats dogs",
         "title": "synonym_1_title",
         "booleanrestriction": "cats AND dogs",
         "synonym_remove": ["dogs"],
         "synonym_add": ["wolves", "foxes"],
         "category": ["synonym"]
      }
   ]
}

This example has one synonym rule synonym_1, which applies for queries where:

  • the query text contains at least one of the terms cats or dogs (to match the content for the rule).
  • the query text contains both the terms cats and dogs (to match the booleanrestriction for the rule).
  • the query profile that you specify has a synonym_categories parameter that contains the category synonym, or is empty.
  • the query profile that you specify has a synonym_enabled parameter set to true.

When a query activates this rule, it modifies the original query text, to remove any instance of the term dogs (specified by the synonym_remove field) and replaces it with the text wolves foxes (specified by the synonym_add field).

For example, if the original query text is cats are like dogs, it modifies the query text to cats are like (wolves foxes). The results for the manipulated query then contain documents about cats, wolves, and foxes.

When the Query Text Index API call has the promotion parameter set to true, Haven OnDemand applies the synonym rule to the query and uses the modified query text to query for promotions.

BLACKLIST

Blacklist rules allow you to manipulate the original query text to remove terms that you define from the query. For example, you might want to remove profanity from user queries.

Note: If a blacklist and synonym rule both apply to a query, the blacklist rule takes precedence.

A blacklist rule must have the following document fields:

Field Type Description
ruletype Enum The rule type. For blacklist rules, set this field to BLACKLIST.
reference String An identifier for the rule.
blacklist Array A list of terms to remove from the original query text.

You can optionally include the following document fields:

Field Type Description
content String The content that the original query must match against for the rule to be applied in the query manipulation.
title String A title for the rule.
booleanrestriction String A Boolean or proximity matching expression that the original query must match for the rule to be applied for query manipulation.

When you use a query profile for a query, Haven OnDemand matches the original query text against the content fields in your rules. For matching rules, it then matches the query text against the booleanrestriction field. The rule is applied if the booleanrestriction expression also matches the original query text.
category Array A list of category names for the blacklist rule. For the query profile to apply the rule, at least one of these categories must match the blacklist_categories parameter in the query profile configuration.

Example blacklist rule:

{
   "document": [
      {
         "reference": "blacklist_1",
         "ruletype": "BLACKLIST",
         "content": "cats dogs",
         "title": "blacklist_1_title",
         "booleanrestriction": ["cats AND dogs"],
         "blacklist": ["dogs", "puppies"],
         "category": ["blacklist"]
      }
   ]
}

This example has one blacklist rule blacklist_1, which applies for queries where:

  • the query text contains at least one of the terms cats or dogs (to match the content for the rule).
  • the query text contains both the terms cats and dogs (to match the booleanrestriction for the rule).
  • the query profile that you specify has a blacklist_categories parameter that contains the category blacklist, or is empty.
  • the query profile that you specify has the blacklists_enabled parameter set to true.

When a query activates this rule, it modifies the original query text, to remove any instances of the terms dogs and puppies.

For example, if the original query text is (cats AND dogs) (kittens OR puppies), it removes dogs from the first part of the expression, and puppies from the second. In the first expression, removing dogs leaves cats AND, which is not valid query syntax (the AND operator requires both sides of the operation), so the rule removes this expression. In the second expression, removing the puppies leaves kittens OR, which is valid (the OR operator requires only at least one side of the operation). Therefore, the resulting modified query text for this query is (kittens). The results for the manipulated query then contain documents about kittens only.

When the Query Text Index API call has the promotion parameter set to true, Haven OnDemand applies the blacklist rule to the query and uses the modified query text to query for promotions.

Query Manipulation Limits

Promotion Type Rules

Rule Limit

For performance reasons, Haven OnDemand applies a maximum of 25 promotion type rules to a query. That is, if a query that you send with a query profile activates more than 25 promotion type rules, it applies only the first 25 rules to the query. This limit applies to DYNAMIC_PROMOTION, STATIC_REFERENCE_PROMOTION, STATIC_CONTENT_PROMOTION and CARDINAL_PLACEMENT rules.

When a query exceeds this rule limit, the response includes a warning.

Document Limit

For performance reasons, Haven OnDemand returns a maximum of 100 results in a promotion query. That is, if a query that you send with a query profile activates several promotion type rules that return a combined total of more than 100 documents, it returns only the first 100 valid promoted documents. This limit applies to DYNAMIC_PROMOTION, STATIC_REFERENCE_PROMOTION, STATIC_CONTENT_PROMOTION and CARDINAL_PLACEMENT rules (and combinations of these types). It does not count invalid documents (for example, if a static reference promotion uses a reference that does not exist in the target index, it does not count towards the total).

When a query exceeds this document limit, the response includes a warning.

Cardinal Placement Rules

Array Limit

For cardinal placement rules, the Target_reference, target_index, and defined_position fields are array type. For performance reasons, these arrays can have a maximum length of 100.

When a rule exceeds this limit, Haven OnDemand considers only the first 100 values, and it returns a warning to indicate that a restriction has been applied to the rule.

Static Reference Promotion Rules

Array Limit

For static reference promotion rules, the Target_reference and target_index fields are array type. For performance reasons, these arrays can have a maximum length of 100.

When a rule exceeds this limit, Haven OnDemand considers only the first 100 values, and it returns a warning to indicate that a restriction has been applied to the rule.

Dynamic Promotion Rules

Array Limit

For dynamic promotion rules, the Dynamic_index field is array type. For performance reasons, this array can have a maximum length of 100.

When a rule exceeds this limit, Haven OnDemand considers only the first 100 values, and it returns a warning to indicate that a restriction has been applied to the rule.

Synonym Rules

Rule Limit

For performance reasons, Haven OnDemand applies a maximum of 1000 synonym rules to a query. If a query that you send with a query profile activates more than 1000 synonym rules, the query returns an error response. This limit applies to SYNONYM rules.

Blacklist Rules

Rule Limit

For performance reasons, Haven OnDemand applies a maximum of 1000 blacklist rules to a query. If a query that you send with a query profile activates more than 1000 blacklist rules, the query returns an error response. This limit applies to BLACKLIST rules.