This page shows how to preview search results using the Google Cloud console and get search results using the API.
Also, instead of creating a search widget to add to your web page, you can make API calls and integrate those calls into your server or application. This page includes code samples for how to make search queries using the gRPC client libraries with a service account.
Search summarization differs by model
If you generate search summaries for your queries, you might notice that the summaries differ between the console results and the API results. If you see this, the likely reason is that the console is using a different LLM model from the API. The curl and code examples on this page use the stable LLM model.
To change or view the LLM model used in the Preview page of the UI, go to the Configurations page > UI tab for your app.
For method calls, to use an LLM model other than the stable model, see Specify the summarization model.
Get search results for an app with website data
Console
To use the Google Cloud console to preview search results for an app with website data, follow these steps:
In the Google Cloud console, go to the Agent Builder page.
Click the name of the app that you want to edit.
Click Preview.
Open the Preview page in the console.
Optional: If you connected multiple data stores to your app but want results only from a specific data store, select the data store to get results from.
Type a search query.
- If you enabled autocomplete, you see a list of autocomplete suggestions below the search bar as you type.
Click Enter to submit the query.
- A list of search results appears below the search bar.
- Each result contains a title, a snippet, and a URL.
- Clicking a result opens that URL.
Click the arrow below the results list to load the next page of results.
REST
To use the API to get search results for an app with website data,
use the engines.servingConfigs.search
method:
Find your app ID. If you already have your app ID, skip to the next step.
In the Google Cloud console, go to the Agent Builder page.
On the Apps page, find the name of your app and get the app's ID from the ID column.
Get search results.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \ -d '{ "servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search", "query": "QUERY", "pageSize": "PAGE_SIZE", "offset": "OFFSET", "orderBy": "ORDER_BY", "params": {"user_country_code": "USER_COUNTRY_CODE", "searchType": "SEARCH_TYPE"}, "filter": "FILTER", "boostSpec": "BOOST_SPEC", "contentSearchSpec": { "searchResultMode": "RESULT_MODE" }, "dataStoreSpec": {"DATA_STORE_SPEC"} }'
- PROJECT_ID: the ID of your Google Cloud project.
- APP_ID: the ID of the Vertex AI Search app that you want to query.
- QUERY: the query text to search.
PAGE_SIZE: the number of results returned by the search. The maximum allowed page size depends on the data type. Page sizes above the maximum value are coerced to the maximum value.
- Websites with basic indexing: Default
10
, Maximum25
- Websites with advanced indexing: Default
25
, Maximum50
- Other: Default
50
, Maximum100
- Websites with basic indexing: Default
OFFSET: the starting index of the results. The default value is 0.
For example, if the offset is 2, the page size is 10, and there are 15 results to return, results 2 through 12 are returned on the first page.
ORDER_BY: the order in which the results are arranged. The attribute to sort on must have a numerical interpretation—for example, price or date.
USER_COUNTRY_CODE: the location of the user. This key-value pair is the only supported entry for the
params
map field. The default value is empty. For acceptable values, see Country Codes in the Programmable Search Engine JSON API reference documentation.SEARCH_TYPE: the type of search to be performed. The default value is 0 for document search. The other supported value is 1 for image search.
FILTER: a text field for filtering your search using a filter expression. The default value is an empty string. For more information about using the
filter
field, see Filter website search.BOOST_SPEC: optional. A specification to boost or bury documents. Values:
BOOST
: a floating point number between -1 and 1. When the value is negative, results are demoted (they appear lower down in the results). When the value is positive, results are promoted (they appear higher up in the results).CONDITION
: a text filter expression to select the documents to which boost is applied. The filter must evaluate to a boolean value. To learn about boost for structured search, see Boost search results.
RESULT_MODE: determines whether search results are returned as full documents or in chunks. To get chunks, the data store must have document chunking turned on. Accepted values are
documents
andchunks
. When chunking is turned on for a data store, the default value ischunks
. Otherwise, the default isdocuments
. For information about document chunking, see Parse and chunk documents. This field is in Public preview; to use it, changev1
tov1alpha
in the curl command.DATA_STORE_SPEC: filters for a specific data store to search across. Use
dataStoreSpec
if your search app is connected to multiple data stores but you want results from a specific data store.
C#
For more information, see the Vertex AI Agent Builder C# API reference documentation.
To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
For more information, see the Vertex AI Agent Builder Java API reference documentation.
To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
For more information, see the Vertex AI Agent Builder Node.js API reference documentation.
To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
For more information, see the Vertex AI Agent Builder PHP API reference documentation.
To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
For more information, see the Vertex AI Agent Builder Python API reference documentation.
To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
For more information, see the
Vertex AI Agent Builder Ruby API
reference documentation.
To authenticate to Vertex AI Agent Builder, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
Ruby
Get search results for an app with structured or unstructured data
You can preview search results from the Google Cloud console or get search results using the API.
Console
To use the Google Cloud console to preview search results for an app with structured or unstructured data, follow these steps:
- Open the Preview page in the console.
- Type a search query.
- If you enabled autocomplete in step 1, you'll see a list of autocomplete suggestions below the search bar as you type.
- (Optional) If you connected multiple data stores to your app but want results only from a specific data store, select the data store to get results from.
- Click Enter to submit the query.
- A list of search results appears below the search bar.
- If no attribute mapping is defined in the Configurations page, each search result appears as a list of raw attribute names and values.
- If any attribute mappings were saved in the Configurations page, the search results display the same images that you see in the Configurations page preview.
- If any facets were specified in the Configurations page, they are displayed in the same way.
- Click the arrow below the results list to load the next page of results.
REST
To use the API to get search results for an app with structured or unstructured
data, use the engines.servingConfigs.search
method:
Find your app ID. If you already have your app ID, skip to the next step.
In the Google Cloud console, go to the Agent Builder page.
On the Apps page, find the name of your app and get the app's ID from the ID column.
Get search results.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \ -d '{ "query": "QUERY", "userPseudoId": "USER_PSEUDO_ID", "pageSize": "PAGE_SIZE", "offset": "OFFSET", "orderBy": "ORDER_BY", "filter": "FILTER", "boostSpec": "BOOST_SPEC", "facetSpec": "FACET_SPEC", "queryExpansionSpec": "QUERY_EXPANSION_SPEC", "spellCorrectionSpec": "SPELL_CORRECTION_SPEC", "contentSearchSpec": "CONTENT_SEARCH_SPEC", "dataStoreSpec": {"DATA_STORE_SPEC"}, }'
- PROJECT_ID: the ID of your Google Cloud project.
- APP_ID: the ID of the Vertex AI Search app that you want to query.
- QUERY: the query text to search.
- USER_PSEUDO_ID: optional. This is a pseudonymized identifier for tracking a search visitor. Google strongly recommends using this field, which improves model performance and personalization quality. You can use an HTTP cookie for this field, which uniquely identifies a visitor on a single device. This identifier does not change when the visitor signs in or out of a website. Don't set this field to the same identifier for multiple users—this would combine their event histories and degrade model quality. Don't include personally identifiable information (PII) in this field.
PAGE_SIZE: the number of results returned by the search. The maximum allowed page size depends on the data type. Page sizes above the maximum value are coerced to the maximum value.
- Websites with basic indexing: Default
10
, Maximum25
- Websites with advanced indexing: Default
25
, Maximum50
- Other: Default
50
, Maximum100
- Websites with basic indexing: Default
OFFSET: optional. The starting index of the results. The default value is 0.
For example, if the offset is 2, the page size is 10, and there are 15 results to return, results 2 through 11 are returned on the first page.
ORDER_BY: optional. The order in which the results are arranged.
FILTER: optional. A text field for filtering your search using a filter expression. The default value is an empty string, which means no filter is applied.
Example:
color: ANY("red", "blue") AND score: IN(*, 100.0e)
For more information, see Filter search for structured or unstructured data.
BOOST_SPEC: optional. A specification to boost or bury documents. Values:
BOOST
: a floating point number between -1 and 1. When the value is negative, results are demoted (they appear lower down in the results). When the value is positive, results are promoted (they appear higher up in the results).CONDITION
: a text filter expression to select the documents to which boost is applied. The filter must evaluate to a boolean value.
To learn about boost for structured search, see Boost search results.
FACET_SPEC: optional. A facet specification to perform faceted search.
QUERY_EXPANSION_SPEC: optional. A specification to determine under which conditions query expansion should occur. Default is
DISABLED
.SPELL_CORRECTION_SPEC: optional. A specification to determine under which conditions spell correction should occur. Default is
AUTO
.CONTENT_SEARCH_SPEC: optional. For getting snippets, extractive answers, extractive segments, and search summaries. For unstructured data only. For more information, see:
DATA_STORE_SPEC: filters for a specific data store to search across. This can be used if your search app is connected to multiple data stores.
Viewing guided search results in the search response:
Guided search results are returned with search responses for structured and unstructured search. The guided search result contains a list of extracted attribute key-value pairs based on search result documents. This allows users to refine their search results by using some attribute keys and values as filters.
In this example response, the color green was used to refine search results by issuing a new search request with the filter field specified as
_gs.color: ANY("green")
:{ "guidedSearchResult": { "refinementAttributes": [ { "attributeKey": "_gs.color", "attributeValue" : "green" }, { "attributeKey": "_gs.category", "attributeValue" : "shoe" } ] } }
C#
For more information, see the Vertex AI Agent Builder C# API reference documentation.
To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
For more information, see the Vertex AI Agent Builder Java API reference documentation.
To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
For more information, see the Vertex AI Agent Builder Node.js API reference documentation.
To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
For more information, see the Vertex AI Agent Builder PHP API reference documentation.
To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
For more information, see the Vertex AI Agent Builder Python API reference documentation.
To authenticate to Vertex AI Agent Builder, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
For more information, see the
Vertex AI Agent Builder Ruby API
reference documentation.
To authenticate to Vertex AI Agent Builder, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
Ruby
Get search-as-you-type results for a media app
For media search, Vertex AI Agent Builder offers two kinds of search behavior:
The user types the search query and presses enter. This is the default and is the same behavior as search in the widget and search for non-media (generic) apps. See Get search results for an app with structured or unstructured data.
A new search result is returned after each letter that the user enters. This is called search-as-you-type and is particularly helpful for users who are entering their search queries through more awkward interfaces such as the remote control for a television.
To get search-as-you-type results for a media app:
Console
To use the Google Cloud console to enable search-as-you-type for a widget app:
In the Google Cloud console, go to the Agent Builder page.
Click the name of the media search app that you want to use search-as-you-type for.
Click Configurations.
Click the UI tab.
Click the Enable search-as-you-type toggle.
In the Preview pane, start typing a query.
The search results update after each keystroke.
To keep the search-as-you-type-setting, click Save and publish.
REST
Use the dataStores.servingConfigs.search
method to get
search results for a media app:
Find your app ID. If you already have your app ID, skip to the next step.
In the Google Cloud console, go to the Agent Builder page.
On the Apps page, find the name of your app and get the app's ID from the ID column.
Run the following curl command to get search-as-you-type results.
All the fields except for
contentSearchSpec
can be used in conjunction with thesearchAsYouTypeSpec
field. For clarity, the optional fields have been omitted from the curl command. For the optional fields, see Get search results for an app with structured or unstructured data.curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \ -d '{ "query": "QUERY", "searchAsYouTypeSpec": {"condition": "ENABLED"} }'
- PROJECT_ID: the ID of your Google Cloud project.
- APP_ID: the ID of the Vertex AI Search app that you want to query.
- QUERY: the query text to search.
Click for an example curl command.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" "https://discoveryengine.googleapis.com/v1/projects/12345/locations/global/collections/default_collection/engines/my-app_4321/servingConfigs/default_search:search" -d '{ "query": "midsummer night", "searchAsYouTypeSpec": {"condition": "ENABLED"} }'