Search Page Configuration Options

The configuration form for all custom search pages will ask for the following:

Label : The name of the search page.  This will show up on the search page tabs if there are more than one search page enabled.

Machine Name : This must be unique across all search pages.

Path: The path to the search page.  All paths begin with 'search'.

The following configuration settings are specific to Vertex AI Search pages.  (admin/config/search/pages/add/vertex_ai_search)

---

Vertex AI Agent Builder Authentication

Service Account Credentials

This is the path to the Service Account credentials file that contains the Service Account key.  The path is relative to the root directory of the site.  This file should be stored in a directory that is inaccessible via the web.

---

Vertex AI Agent Builder Serving Config

The following information is needed to configure a search client and make search requests to the appropriate Vertex AI Search app.

Google Cloud Project ID

The ID of the project that contains the Vertex AI Search App.

Vertex AI Search Location

This is the location where the Vertex AI Search data is available, typically 'global'.

Vertex AI Data Store ID

Within the Google Cloud Project, the data store ids for any Vertex AI Agent data stores can be retrieved from the Data Stores management page (https://console.cloud.google.com/gen-app-builder/data-stores?project=[pr...)

Vertex AI Serving Configuration

For search apps, the default serving config's ID is 'default_search'.

---

Search Autocomplete

Enable Autocomplete

To enable autocomplete functionality on the search form, this must be checked.  No other autocomplete options will appear until this is checked.

Enable Autocomplete on Core Search Block Form

If autocompletion is desired on the core search block form, then check this box.

Autocomplete Trigger Length

This represents the number of characters that must be entered in the search form before autocomplete begins returning suggestions.

Max Suggestions

The maximum number of suggestions that will appear while typing in search terms.

Autocomplete Source

Select the plugin to use for providing autocomplete suggestions.  The Drupal plugin system is used here to provide the ability to create additional autocomplete solutions.  See the Developer Documentation for information on creating a custom autocompletion plugin.

Each autocomplete source may present additional configuration options specific to its plugin.  The Max Suggestions and Trigger Length options apply to all plugins and are enforced via the AutocompleteController class.

Two plugins have been provided by the vertex_ai_search module:

• SimpleAutocomplete: Provides autocomplete suggestions by matching against the titles and/or body of content in the Drupal database. This may not be sufficient for production needs, but offers a good custom autocomplete plugin implementation example.
• VertexAutocomplete: Vertex AI Search provides multiple models for autocompletion.  This plugin provides the ability to switch between the different models.

Vertex AI Search apps using website data stores will use the Vertex AI Search 'search-history' autocomplete model by default.  This is implemented in the VertexAutocomplete plugin.  Autocomplete suggestions will not appear, however, until the search app has received real web traffic for a day or two.  The SimpleAutocomplete option may provide a good short term solution until the 'search-history' model begins returning suggestions.

Refer to the Developer Documentation for information on creating custom Autocomplete functionality using plugin types defined by vertex_ai_search.

---

Search Results Page Display Options

Number of results per page

A pager will be present at the bottom of the SERP.  This specifies the max number of results on each page.

Total Results Limit

Sets a ceiling on the total number of results that can be retrieved for a request.

Pager Type

There are two pager types offered:

• Standard Pager : Displays multiple page links, but is susceptible to empty pages based on the available results count being a rough estimate; it is possible that links to empty results pages will appear in the pager.  If the total available results estimate is greater than the Total Results Limit, then the Total Results Limit is used to determine the number of pages in the pager.
• Vertex Pager : This is a custom pager that determines if the 'next' pager element should be displayed and incrementally shows page links as the 'next' element is clicked.  This mitigates against the rough estimate issue.

Spelling Correction Mode

If set to AUTO or MODE_UNSPECIFIED, then misspelled search terms will automatically be corrected and the search will be performed on the corrected search terms.

If set to SUGGESTION_ONLY, a message will indicate that there is a possible misspelled search term, but the search will still be performed against the misspelled search term.  A convenience link will be provided to redo the search against the correctly spelled term. 

Result Output

By default, the Title and Snippet for each result will be displayed on the SERP.  There is also an option to hide the snippets and only show the titles.

Use SafeSearch

Check this to enable Vertex AI Search SafeSearch capability.

Remove Domain from Result Link URLs

If checked, this will make all search result links relative.  This is convenient for working in development or local environments to ensure one stays in the development or local environment when clicking on search results.

Display Search Form on results page

Searches on a Drupal website can be performed from search blocks as well as from the main search form.  Leave this unchecked if having the main search form on the SERP is not desired.

Check this option to display the search form on the SERP. 

Keywords Input Class

Extra classes to apply to the keyword input element.

Keywords Input Aria Label

Aria label value to apply to the keyword input element.

Submit Input Class

Extra classes to apply to the submit button element.

Submit Input Aria Label

Aria label value to apply to the submit button element.

---

Filters 

The search request can be modified using multiple mechanisms: Configurable JavaScript Plugins, Exclusion List, or Vertex Filter Expressions.

Configurable JavaScript Plugins 

These are plugins that attach custom JavaScript to the search page.  The JavaScript can use configuration captured here to alter search functionality and search requests on the client side.

Check the 'Enable Configurable JavaScript' box then select from a list of available JavaScript Plugins.  The following Plugin is available with the vertex_ai_search module:

• Regex Validator : This plugin examines the keywords entered in the search box.  If any specified regex patterns are matched, then the user can be presented with an Error (prevents submission), Warning, or Info message below the search box.  This Plugin can be used to mitigate against users trying to search on PII.  As an example, to prevent a user from searching on a SSN, the following can be added to the 'Regex Patterns' box to match against SSNs, display an error message to the user, and prevent the search submission.
  

  \d{3}-\d{2}-\d{4}::Please do not search on SSNs.::error

Refer to the Developer Documentation for information on developing custom Configurable JavaScript Plugins.

Exclusion List 

Should there be a need to strip out specific keywords before proceeding with the search request, the exclusion list can be used.  Results will be returned as normal with any words found in the exclusion list stripped out of the request.  The user will not be informed that the words were stripped out.

Check the 'Enable Exclusion List' box then add words or regular expressions to exclude to the 'Exclusion List' box - one per line.

Filter Expressions 

Filter expressions can be used to construct website search filters.  The construction of the filters depends on whether your datastore is using basic or advanced website indexing.  Using expressions, filters can be applied to limit results based on URL and path, document type, language, country, range, licensing and other basic attributes.

To apply a filter expression plugin to all search requests, check the 'Enable Filter Expression' box and select the desired search filter plugin.  

To create filter expressions, the vertex_ai_search module provides a custom plugin type along with a search filter base class (VertexSearchFilterPluginBase) that can be extended.  Note that there are no instances of the custom plugin type provided by the vertex_ai_search module. 

Refer to the Developer Documentation for information on developing custom filter expressions using the Search Filter Plugin provided by vertex_ai_search.

---

Flood Settings

Using Drupal's FloodInterface, basic flood control has been implemented to help stave off an inundation of search requests, possibly caused by a bad actor.

To use flood control, check the 'Enable Flood Control' box.  Three configuration fields will be provided:

• Flood Threshold : This sets the maximum number of requests that are allowed within a defined time window.
• Flood Window : This sets the time window (in seconds), within which requests are metered.
• Flood Message : This sets the message to be displayed to the end user if they have surpassed the flood threshold.

Search functionality will resume after the frequency of search requests subsides and is outside the threshold.

---

Search Results Page Messages

Some custom messages can be created for the SERP.  Tokens integration provides for a handful of vertex_ai_search specific tokens that can be used in the messages.

Results message

When search results are returned for a search query, this message will appear at the top of the search results.

Example message:

Displaying results [vertex_ai_search:vertex_ai_search_result_start] to [vertex_ai_search:vertex_ai_search_result_end] for [vertex_ai_search:vertex_ai_search_keywords].

Results message (singular)

In the case that only a single result is returned for a search query, this message will appear above the singular result.

Example message:

There is only one result for [vertex_ai_search:vertex_ai_search_keywords].  Here it is...

No results message

Should no results be returned for a search query, this message will appear.

Example message:

Your search resulted in no results.  Perhaps modify your search?

No keywords specified message

If a search was performed without any search terms, this message will appear.

Example message:

To perform an actual search, please provide some keyword against which to search.

Keyword Correction Made 

If the Spelling Correction Mode is configured for AUTO correction, this message can be displayed whenever a spelling correction is made by Vertex AI Search.

Special tokens have been provided to help construct messaging to the end user:

• [vertex_ai_search:vertex_ai_search_original_keyword] : This provides the original, incorrectly-spelled keyword.
• [vertex_ai_search:vertex_ai_search_original_Keyword] : This provides the corrected keyword.
• [vertex_ai_search_original_keyword_url] : The URL to enforce a search against the incorrectly-spelled keyword.
• [vertex_ai_search_corrected_keyword_url] : The URL of the search using the corrected keyword.

Example message:

A spelling correction has been applied.

Searching on [vertex_ai_search:vertex_ai_search_corrected_keyword] instead.

Actually search on the misspelled word, <a href="[vertex_ai_search:vertex_ai_search_original_keyword_url]">[vertex_ai_search:vertex_ai_search_original_keyword]</a> instead.

Keyword Correction Suggested 

If the Spelling Correction Mode is configured for SUGGESTION ONLY, this message can be displayed whenever a spelling correction is found by Vertex AI Search.

Searching on [vertex_ai_search:vertex_ai_search_original_keyword] as you wanted.

It seems you may have misspelled some words.  Would you rather search on <a href="[vertex_ai_search:vertex_ai_search_corrected_keyword_url]">[vertex_ai_search:vertex_ai_search_corrected_keyword]</a> instead.

---

Advanced Settings

Transport Options

There are three possible transport options used by the Vertex AI Search Service Clients:

• Google Remote Procedure Call (gRPC):  This is a robust, open-source framework that uses Protocol Buffers and HTTP2 for data transmission.  APIs are faster than when using REST.
• Representational State Transfer (REST): Based on HTTP and manages communications between client and server using HTTP verbs (POST, GET, PUT, and DELETE).
• Auto: If set to 'Auto', gRPC will be used if it is available.  If it is not available, then REST will be used.