Implementing a Search Box

A search interface typically includes a text input from which the end user can enter and submit queries. This article provides guidelines for properly implementing a search box on your own, assuming that you cannot use the Coveo JavaScript Search Framework in your custom search integration with the Coveo Cloud platform.

As a reference, you may want to look at the source code of the Searchbox component to see how it is implemented in the Coveo JavaScript Search Framework.

Standard Search Box Actions

The following table lists some of the most frequent actions you may want to make available in a search box implementation.

Each entry indicates the specific Coveo Usage Analytics (Coveo UA) event type, actionCause, and customData that must be logged (if applicable) when the action is performed, as well as a link to the corresponding implementation guidelines.

Search box action Event category actionCause customData Implementation guidelines
Submitting a query Search searchBoxSubmit   Submitting a Query
Clearing the search box Search searchBoxClear   Submitting a Query
Select a query correction suggestion Search didyoumeanClick   Correct Queries
Trigger an automatically corrected query Search didyoumeanAutomatic   Correct Queries
Rendering Coveo ML suggestions Search     Providing Coveo Machine Learning Query Suggestions
Selecting a Coveo ML suggestion Search omniboxAnalytics partialQueries, partialQuery, suggestionRanking, suggestions Handling Coveo Machine Learning Query Suggestion Selection
Rendering field-based suggestions Search     Providing Field-Based Query Completion Suggestions
Selecting a field-based suggestion Search omniboxField   Handling Field-Based Query Completion Suggestion Selection

Using the proper event type, actionCause, and customData when logging a usage analytics event for a specific type of action in a search interface is important. Otherwise:

Submitting a Query

When the end user submits a query from the search box (e.g., by clicking a Submit button):

  1. Retrieve the current value from the search box input.
  2. Prepare a new query. Ensure that the q search request parameter is set to the value retrieved at Step 1.
  3. Call the Search API to execute the query prepared at Step 2 (see Performing a Query). When the Search API returns:
    1. Call the Usage Analytics Write API to log the corresponding Search event (see Logging Search Events). In the request body:
      • Set the actionCause property to searchBoxSubmit.

        If the end user triggered a query by clearing the search box (e.g., by clicking a Clear button), set the actionCause property to searchBoxClear instead.

      • Set other required/optional properties as appropriate.

    2. Render the query results (see Implementing a Result List - Rendering Query Results).
    3. Render facets, if any (see Implementing Facets - Requesting and Rendering Facets).
  1. Executing the query after the catcher rye expression has been submitted from the search box

    POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1
     
    Accept: application/json
    Content-Type: application/json
    Authorization: Bearer **********-****-****-****-************
    

    Payload (excerpt)

    {
      ...
      "q": "catcher rye",
      "locale": "en-US",
      "searchHub": "BookstoreSearch",
      "tab": "All",
      ...
    }
    

    200 OK response body (excerpt)

    {
      ...
      "duration": 145,
      "searchUid": "9862eba6-b30b-491b-94af-33ca2fd61547",
      "results": [
        ...data to render query results...
      ],
      "groupByResults": [
        ...data to render facets...
      ],
      ...
    }
    
  2. Logging a searchBoxSubmit Search event after the Search API has returned

    POST https://platform.cloud.coveo.com/rest/ua/v15/analytics/search?visitor=28s6g49d-f81s-1435-2r5x153dle72 HTTP/1.1
     
    Accept: application/json
    Content-Type: application/json
    Authorization: Bearer **********-****-****-****-************
    

    Payload (excerpt)

    {
      ...
      "actionCause": "searchBoxSubmit",
      "queryText": "catcher rye",
      "language": "en",
      "originLevel1": "BookstoreSearch",
      "originLevel2": "All",
      "responseTime": 145,
      "searchQueryUid": "9862eba6-b30b-491b-94af-33ca2fd61547",
      ...
    }
    

As shown in this example, whenever logging a Search event:

  • queryText corresponds to q in the query request body.
  • language corresponds to the language part of locale in the query request body.
  • originLevel1 corresponds to searchHub in the query request body.
  • originLevel2 corresponds to tab in the query request body.

Moreover:

  • responseTime corresponds to elapsed time (in milliseconds) between the moment the search interface sent the query to the Search API, and the moment it received the results.
  • searchQueryUid corresponds to searchUid in the query response body.

Correcting Queries

The DidYouMean query feature enables the Search API to check for a possible query correction if a query returns no results. You can configure this feature to either suggest the correction, or automatically trigger a new query with the suggested term. The DidYouMean feature involves the enableDidYouMean (boolean) search request parameter.

When enableDidYouMean is set to true, the Search API returns the queryCorrections object in the query response body if no results are returned (e.g., "totalCount": 0).

To suggest the query correction in the search interface after an end user has entered a query that returned no results:

  1. Retrieve the value of the correctedQuery parameter from within the queryCorrections query response object.
  2. Use the value from Step 1 to output a message suggesting the corrected query. This message should include a link. When the end user clicks that link:
    1. Prepare a new query. Ensure that the q search request parameter is set to the value retrieved at Step 1 (see Submitting a Query).
    2. Call the Search API to execute the query prepared at Step 2 (see Performing a Query). When the Search API returns:
      1. Call the Usage Analytics Write API to log the corresponding Search event (see Logging Search Events). In the request body:
        • Set the actionCause property to didyoumeanClick.
        • Set other required/optional properties as appropriate.

You may want to use the wordCorrections array from the queryCorrections object to output a string indicating what was wrong in the original query.

Alternatively, you can enable your search interface to automatically correct queries and display results without requiring the user to interact more with the search interface. To do so, follow the steps above but make the following changes:

  • Automatically trigger the query from Step 2.a, rather than wait for an end user to select a correction link.
  • Set the actionCause property to didyoumeanAutomatic when logging the corresponding Search event from Step 2.b.i.

You should typically output a string to the user indicating that the query was automatically corrected.

  1. Executing the query after the The Shning expression has been submitted from the search box

     POST https://platform.cloud.coveo.com/rest/search/v2?organizationId=myorganizationid HTTP/1.1
      
     Accept: application/json
     Content-Type: application/json
     Authorization: Bearer **********-****-****-****-************
    

    Payload (excerpt)

     {
       "aq": "@source==\"MovieSource\"",
       "q": "Shning",
       "enableDidYouMean": true
       // additional parameters...
     }
    

    200 OK response body (excerpt)

     {
       "totalCount": 0,
       ...
       "queryCorrections": [
         {
           "correctedQuery": "shining",
           "wordCorrections": [
             {
               "offset": 0,
               "length": 7,
               "originalWord": "shning",
               "correctedWord": "shining"
             }
           ]
         }
       ],
       ...
     }
    
  2. Using the correctedWord value as the q parameter for the new query

     POST https://platform.cloud.coveo.com/rest/search/v2?organizationId=myorganizationid HTTP/1.1
      
     Accept: application/json
     Content-Type: application/json
     Authorization: Bearer **********-****-****-****-************
    

    Payload (excerpt)

     {
       "aq": "@source==\"MovieSource\"",
       "q": "shining",
       "enableDidYouMean": true
       // additional parameters...
     }
    

    200 OK response body (excerpt)

       {
       "totalCount": 1,
       ...
       "results": [
         {
           "title": "The Shining",
           ...
         }
       ],
       ...
       }
    
  3. Logging a didyoumeanAutomatic Custom event after the Search API has returned

     POST https://platform.cloud.coveo.com/rest/ua/v15/analytics/search?visitor=28s6g49d-f81s-1435-2r5x153dle72 HTTP/1.1
      
     Accept: application/json
     Content-Type: application/json
     Authorization: Bearer **********-****-****-****-************
    

    Payload (excerpt)

     {
       ...
       "actionCause": "didyoumeanAutomatic",
       "queryText": "The Shining",
       "language": "en",
       "originLevel1": "MoviestoreSearch",
       "originLevel2": "Classics",
       "responseTime": 118,
       "searchQueryUid": "8c2f6897-203d-4d5c-db56-5b3e39831345",
       ...
     }
    

Providing Coveo Machine Learning Query Suggestions

Once you have logged sufficient usage analytics data in your Coveo Cloud organization, and created a Coveo ML Query Suggestions (QS) model, you can assist end users by providing them with highly relevant, machine learning-powered query suggestions as they are typing in the search box (see Coveo Machine Learning).

To do so, on each valid keystroke in the search box:

  1. Retrieve the current value from the search box input.
  2. Resolve the current searchHub, tab, and locale (and optionally, referrer, and context) search request parameters.
  3. Call the Search API to get query suggestions (see Getting Query Suggestions). In the request body:
    • Set the q property to the value retrieved at Step 1.
    • Set the searchHub, tab, and locale (and optionally, referrer, and context for finer granularity) parameters to the values resolved at Step 2 in order to get contextually relevant Coveo ML Query Suggestions.
    • Set the enableWordCompletion property to true if you want the top query suggestion in the request response to be the one that best completes the last word being typed by the end user in the search box. If you set this property to false, the top query completion suggestion will instead be the one deemed most relevant by the Query Suggestions (QS) model (even if this query suggestion does not actually complete the query).

    When calling the Search API to get query suggestions, the request must be routed to a query pipeline in which a Coveo ML Query Suggestions (QS) model is configured and ready. Otherwise, the request will return an empty completions array.

  4. When the Search API returns, use the expression and/or highlighted properties of each element in the ordered completions array of the response body to properly render query suggestions in a dedicated list.

No usage analytics event needs to be logged when requesting Coveo ML Query Suggestions.

Requesting Coveo ML-based query suggestions

POST https://platform.cloud.coveo.com/rest/search/v2/querySuggest HTTP/1.1
 
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "q": "cat",
  "locale": "en-US",
  "searchHub": "BookstoreSearch",
  "tab": "All",
  "referrer": "https://example.com/books/classics/authors/Salinger_J_D/",
  "context": {
    "userType": "Premium"
  },
  "enableWordCompletion": false
}

Successful response - 200 OK

{
  "completions": [
    {
      "expression": "catcher in the rye",
      "score": 14.811407079917723,
      "highlighted": "{cat}[cher] [in] [the] [rye]",
      "executableConfidence": 1
    },
    {
      "expression": "dream catcher",
      "score": 14.135665512605295,
      "highlighted": "[dream] {cat}[cher]",
      "executableConfidence": 1.0
    },
    {
      "expression": "catch-22",
      "score": 13.576942132468472,
      "highlighted": "{cat}[ch-22]",
      "executableConfidence": 1
    },
    {
      "expression": "cat in the hat",
      "score": 12.879732037029243,
      "highlighted": "{cat} [in] [the] [hat]",
      "executableConfidence": 1.0
    },
    {
      "expression": "the children act",
      "score": 12.325728875625282,
      "highlighted": "[the] [children] (act)",
      "executableConfidence": 0.6666666666666666
    },
  ]
}

In a completions array item:

  • The score property value only has relative significance within the same completions array.

    For instance, a suggestion with a score of 14.811407079917723 in the completions array of response A is not necessarily less relevant than a suggestion with a score of 24.325728875625282 in the completions array of response B.

  • The highlighted property uses the following logic:

    • Characters between curly braces (e.g., {cat}) indicate an exact match with q.
    • Characters between square braces (e.g., [cher]) indicate completions.
    • Characters between parentheses (e.g., (act)) indicate corrections to q.
  • The executableConfidence property contains a floating-point value between 0 and 1 indicating how “convinced” Coveo ML is that performing a query with this suggestion as a basic query expression will return relevant results. The threshold from which Coveo ML considers a query suggestion executable is 0.8.

    You could use this property to include a reliable search-as-you-type feature in your search box implementation.

Handling Coveo Machine Learning Query Suggestion Selection

When the end user selects a query suggestion (e.g., by clicking one of the rendered suggestions):

  1. Set the search box input value to the query suggestion the end user has selected.
  2. Prepare a new query. Ensure that the q search request parameter to the expression generated at Step 1.
  3. Call the Search API to execute the query prepared at Step 2 (see Performing a Query). When the Search API returns:
    1. Call the Usage Analytics Write API to log the corresponding Search event (see Logging Search Events).

      In the request body:

      • Set the actionCause property to omniboxAnalytics.
      • Include the following key-value pairs in the customData property:
        • "partialQueries": <partialQueries>
        • "partialQuery": <partialQuery>
        • "suggestionRanking": <suggestionRanking>
        • "suggestions": <suggestions>

        where:

        • <partialQueries> (semicolon-separated ordered list of strings) contains the q value of each Search API query suggestion request that returned at least one suggestion, before a suggestion was selected.
        • <partialQuery> (string) is the q value of the last Search API query suggestion request made before a suggestion was selected.
        • <suggestionRanking> (unsigned integer) is the 0-based index position of the suggestion that was selected in the completions array.
        • <suggestions> (semicolon-separated ordered list of strings) contains the expression value of each item in the response of the last Search API query suggestion request.

        The end user types c, i, [backspace], o, and v in the search box. At this point, the following ordered list of query suggestions is displayed:

        • coveo for salesforce
        • coveo for sitecore
        • coveo cloud
        • coveo on elasticsearch
        • coveo for dynamics

        The end user selects the third item in the list (coveo cloud).

        In the customData property of the Search event that gets logged when the triggered query returns:

        • <partialQueries> would have to be set to c;ci;c;co;cov
        • <partialQuery> would have to be set to cov
        • <suggestionRanking> would have to be set to 2
        • <suggestions> would have to be set to coveo for salesforce;coveo for sitecore;coveo cloud;coveo on elasticsearch;coveo for dynamics
        • Set other required/optional properties as appropriate.
    2. Render the query results (see Implementing a Result List - Rendering Query Results).
    3. Render facets, if any (see Implementing Facets - Requesting and Rendering Facets).
    1. Executing a query after the dream catcher query completion suggestion has been selected

      POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1
       
      Accept: application/json
      Content-Type: application/json
      Authorization: Bearer **********-****-****-****-************
      

      Payload (excerpt)

      {
        ...
        "q": "dream catcher",
        "firstResult": 0,
        "locale": "en-US",
        "searchHub": "BookstoreSearch",
        "tab": "All",
        "referrer": "https://example.com/books/classics/authors/Salinger_J_D/",
        "context": {
          "userType": "Premium"
        },
        ...
      }
      
    2. Logging an omniboxField Search event after the Search API has returned

      POST https://platform.cloud.coveo.com/rest/ua/v15/analytics/search?visitor=28s6g49d-f81s-1435-2r5x153dle72 HTTP/1.1
       
      Accept: application/json
      Content-Type: application/json
      Authorization: Bearer **********-****-****-****-************
      

      Payload (excerpt)

      {
        ...
        "actionCause": "omniboxAnalytics",
        "customData": {
          ...
          "partialQueries": "c;ca;car;ca;cat",
          "partialQuery": "cat",
          "suggestionRanking": 1,
          "suggestions": "catcher in the rye;dream catcher;catch-22;cat in the hat;the children act",
          "context_userType": "Premium",
          ...
        },
        "queryText": "dream catcher",
        "language": "en",
        "originLevel1": "BookstoreSearch",
        "originLevel2": "All",
        "responseTime": 97,
        "searchQueryUid": "153fdc38-8eb9-428a-942d-19a6ddb59fe9",
        ...
      }
      

      As shown in this example, when logging a Search event, customData must contain a corresponding context_-prefixed key along with its value for each key-value pair in the context object of the query request body.

Providing Field-Based Query Completion Suggestions

Typically, you should only use Coveo ML Query Suggestions in your search box implementation, as they are both powerful and relatively easy to implement (see Providing Coveo Machine Learning Query Suggestions). However, it is also possible (although not necessarily recommended) to assist end users by providing them with field-based query completion suggestions as they are typing in the search box.

In a bookstore search interface, you may want to suggest @author field values that match what the end user is typing.

To render field-based query completion suggestions, on each valid keystroke in the search box:

  1. Retrieve the current value from the search box input.
  2. Modify the retrieved value to a wildcards expression (e.g., if the value retrieved at Step 1 was a, set it to *a*).

    These guidelines assume that you are using the wildcards patternType when requesting field values from the Search API, because this is how field suggestions are implemented in the Coveo JavaScript Search Framework (see the FieldsSuggestion component). You can use any other valid patternType value (regularExpression, editDistance, or phonetic) in your own implementation if you so desire.

  3. If your search interface includes tabs, retrieve the filter expression enforced by the currently selected tab (see Implementing Tabs).
  4. Call the Search API to get matching field values (see Get field list values method). In the request body:

    • Set the patternType property to wildcards.
    • Set the pattern property to the value modified at Step 2 (e.g., *a*).
    • Set the field property to the @-prefixed name of the field from which to retrieve query completion suggestions (e.g., @author).

      Field-based query completion suggestions can only be retrieved from fields whose facet option is set to true (see Available Boolean Field Options)

    • Set the sortCriteria property to occurrences to ensure that field suggestions are returned in a logical order.
    • Set the maximumNumberOfValues property to a relatively low value (e.g., 5) to ensure only a useful number of field suggestions are requested.
    • When end users may use accented characters, set the ignoreAccents property to true to ensure that accented characters are treated as non-accented characters when retrieving field values (e.g., when ignoreAccents is set to true, using *élo* or *elo* as a pattern value is equivalent; both may return fields values such as Hello or Éloïse).
    • If your search interface includes tabs, set the queryOverride property to the value retrieved at Step 3 to ensure that only field suggestions matching the expression enforced by the currently selected tab are returned (see Implementing Tabs).
  5. When the Search API returns, use the value property of each element in the ordered values array of the response body to properly render field suggestions in a dedicated list.

No usage analytics event needs to be logged when requesting field values.

Requesting query completion suggestions based on the @author field

POST https://platform.cloud.coveo.com/rest/search/v2/values HTTP/1.1
 
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "patternType": "wildcards",
  "pattern": "*a*",
  "field": "@author",
  "sortCriteria": "occurrences",
  "maximumNumberOfValues": 5,
  "ignoreAccents": true,
  "queryOverride": "@source==\"Classics\""
}

Successful response - 200 OK

{
  "values": [
    {
      "value": "Mark Twain",
      "lookupValue": "Mark Twain",
      "numberOfResults": 25
    },
    {
      "value": "Charles Dickens",
      "lookupValue": "Charles Dickens",
      "numberOfResults": 21
    },
    {
      "value": "Jane Austen",
      "lookupValue": "Jane Austen",
      "numberOfResults": 12
    },
    {
      "value": "Charlotte Brontë",
      "lookupValue": "Charlotte Brontë",
      "numberOfResults": 8
    },
    {
      "value": "Mary Shelley",
      "lookupValue": "Mary Shelly",
      "numberOfResults": 5
    }
  ]
}

Handling Field-Based Query Completion Suggestion Selection

When the end user selects a specific field-based query completion suggestion (e.g., by clicking one of the rendered values):

  1. Generate an expression from the field value the end user has selected (e.g., Alice Smith).
  2. Set the search box input value to the query expression generated at Step 1.
  3. Prepare a new query. Ensure that the q search request parameter is set to the expression generated at Step 1.

    If the expression generated at Step 1 uses advanced query syntax (e.g., @author=="Alice Smith"), also ensure that the enableQuerySyntax search request parameter is set to true before the query is executed.

  4. Call the Search API to execute the query prepared at Step 3 (see Performing a Query). When the Search API returns:
    1. Call the Usage Analytics Write API to log the corresponding Search event (see Logging Search Events). In the request body:
      • Set the actionCause property to omniboxField.
      • Set other required/optional properties as appropriate.
    2. Render the query results (see Implementing a Result List - Rendering Query Results).
    3. Render facets, if any (see Implementing Facets - Requesting and Rendering Facets).
  1. Executing a query after the Charles Dickens query completion suggestion has been selected

    POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1
     
    Accept: application/json
    Content-Type: application/json
    Authorization: Bearer **********-****-****-****-************
    

    Payload (excerpt)

    {
      ...
      "q": "@author==\"Charles Dickens\"",
      "enableQuerySyntax": true,
      "firstResult": 0,
      "locale": "en-US",
      "searchHub": "BookstoreSearch",
      "tab": "Classics",
      ...
    }
    

    In this example, the basic query expression generated from the selected field value uses advanced query syntax (@author=="Charles Dickens"). Thus, the enableQuerySyntax search request parameter is set to true to ensure that the Search API parses this expression correctly.

  2. Logging an omniboxField Search event after the Search API has returned

    POST https://platform.cloud.coveo.com/rest/ua/v15/analytics/search?visitor=28s6g49d-f81s-1435-2r5x153dle72 HTTP/1.1
     
    Accept: application/json
    Content-Type: application/json
    Authorization: Bearer **********-****-****-****-************
    

    Payload (excerpt)

    {
      ...
      "actionCause": "omniboxField",
      "queryText": "@author==\"Charles Dickens\"",
      "language": "en",
      "originLevel1": "BookstoreSearch",
      "originLevel2": "Classics",
      "responseTime": 118,
      "searchQueryUid": "8c8f5897-233d-4b4c-bd56-5b3e39885345",
      ...
    }
    

Enabling Advanced Search Box Features

Several search request parameters can have a direct and significant impact on the way the Search API and the index interpret the basic part of the query expression (q). In a typical search interface, those search request parameters should thus logically be configurable through the search box.

You may want to ensure that your search box implementation includes options to enable and take advantage of the following features.

Partial Match

The partial match feature can help the index find items that match the basic part of the query expression (q) even when the expression is fairly wordy. The partial match feature involves the following search request parameters:

  • partialMatch (boolean)
  • partialMatchKeywords (unsigned integer)
  • partialMatchThreshold (unsigned integer or string [percentage])

When partialMatch is set to true and the q value contains at least partialMatchKeywords (e.g., 5), items only need to match partialMatchThreshold (e.g., 50%, rounded up) of those keywords to match the basic query expression.

The partial match feature:

  • Applies after the query has been fully processed by the query pipeline.
  • Has no effect when enableQuerySyntax is set to true and q contains advanced query syntax.

Enabling the partial match feature

Query payload

{
  "q": "the life and strange surprising adventures of robinson crusoe of york mariner",
  "partialMatch": true,
  "partialMatchKeywords": "3",
  "partialMatchThreshold": "35%"
}

In this example, since partialMatch is set to true and q contains 12 keywords:

  • The basic query expression is converted to a partial match expression (12 is greater than the partialMatchKeywords value of 3).
  • Any item matching a minimum of 5 keywords in the partial match expression (i.e., the partialMatchThreshold value of 35% multiplied by 12, and then rounded up) will match the expression.

This means that, for instance, an item which merely contains the the adventures of robinson crusoe keywords will match the expression.

Wildcards

The wildcards feature allows the index to recognize wildcards characters in the basic part of the query expression (q) and expand the expression accordingly. The wildcards feature involves the following search request parameters:

  • wildcards (boolean)
  • questionMark (boolean)

When wildcards is set to true, * characters in q are interpreted as wildcards. When questionMark is also set to true, ? characters in q are also treated as wildcards (see Using Wildcards in Queries).

Setting questionMark to true has no effect unless wildcards is also set to true.

Enabling and using the * and ? wildcards

Query payload

{
  "q": "?obi*",
  "wildcards": true,
  "questionMark": true,
}

In this example, since wildcards and questionMark are both set to true, q is expanded so that items containing keywords such as robin, robinson, jobim, or mobile, will match the expression.

Advanced Query Syntax

The advanced query syntax feature allows the index to recognize Coveo Cloud query syntax in the basic part of the query expression (q) and interpret the expression accordingly. The advanced query syntax feature involves the following search request parameters:

  • enableQuerySyntax (boolean)
  • lowercaseOperators (boolean)

When enableQuerySyntax is set to true, advanced query syntax in q is interpreted as such. When lowercaseOperators is also set to true, boolean operators (i.e., NEAR, NOT, AND, OR) in q are always interpreted as such, even if they appear in lowercase (see Coveo Cloud Query Syntax Reference).

  • In most public deployments, enableQuerySyntax should be set to false by default.

    Typically, end users are not going to be aware of advanced Coveo Cloud query syntax and will either not use at all, or use it inappropriately. Exact phrase match requests (i.e., keywords between double quotes) are still going to work even if enableQuerySyntax is set to true, and wildcards (i.e., * and ?) can also be enabled independently (see Wildcards).

  • Setting lowercaseOperators to true has no effect unless enableQuerySyntax is also set to true.

  1. Enabling and using advanced query syntax

    Query payload

    {
      "q": "@title=prometheus NOT (@author=Shelley)",
      "enableQuerySyntax": true
    }
    

    In this example, since enableQuerySyntax is set to true, q is parsed so that items whose title contains the keyword prometheus and whose author name does not contain the keyword Shelley will match the expression.

    This means that, for instance, book items corresponding to Frankenstein or the Modern Prometheus (by Mary Shelley) and Prometheus Unbound (by Percy Bysshe Shelley) will not match the expression, whereas a book item such as The Prometheus Effect (by David Fleming) will match the expression.

  2. Enabling and using lowercase operators

    Query payload

    {
      "q": "doctor strangelove or how i learned to stop worrying and love the bomb",
      "enableQuerySyntax": true,
      "lowercaseOperators": true
    }
    

    In this example, since enableQuerySyntax and lowercaseOperators are both set to true, the Search API parses the basic query expression as follows: (doctor strangelove) OR (how i learned to stop worrying) AND (love the bomb), which is very likely not what the end user wants. Setting lowercaseOperators to true should thus only be done under very specific circumstances and is typically not recommended.