Preview search results

This page shows how to preview search results using the Google Cloud console and get search results using the API.

Also, instead of using the web app UI, 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.

Preview search results

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.
1. 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.
1. A list of search results appears below the search bar.
2. If no attribute mapping is defined in the Configurations page, each search result appears as a list of raw attribute names and values.
3. 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:

Note: You can search over an app using the engines.servingConfigs.search method and you can search over a data store using the dataStores.servingConfigs.search method. For the following procedure, Google recommends searching using the engines.servingConfigs.search method.

Find your app ID. If you already have your app ID, skip to the next step.
1. In the Google Cloud console, go to the Agentspace page.
  
  Go to Apps
2. On the Apps page, find the name of your app and get the app's ID from the ID column.
Preview search results.

Key Term: In Agentspace Enterprise, the term app can be used interchangeably with the term engine in the context of APIs.
```
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",
"dataStoreSpecs": [{"DATA_STORE_SPEC"}],
}'
```
Replace the following:
- PROJECT_ID: the ID of your project.
- APP_ID: the ID of the 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, Maximum 25
  - Websites with advanced indexing: Default 25, Maximum 50
  - Other: Default 50, Maximum 100
- 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 in the range [-1,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:
  - Use snippets and extractive content
  - Get search summaries
- 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. For more information, see DataStoreSpec.
- 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"
    }
  ]
}
}
```