<br />

> [!NOTE]
> **Important:** Gemini Enterprise retrieves search results from the assistant using StreamAssist. We recommend using the StreamAssist instead of the Search and Answer. For more information, see [Get search results using StreamAssist](https://docs.cloud.google.com/gemini/enterprise/docs/get-answers-from-streamassist.md.txt).

<br />

> [!NOTE]
> **Note:** This feature is a Preview offering, subject to the "Pre-GA Offerings Terms" of the [GCP Service Specific Terms](https://cloud.google.com/terms/service-terms). Pre-GA products and features may have limited support, and changes to pre-GA products and features may not be compatible with other pre-GA versions. For more information, see the [launch stage descriptions](https://cloud.google.com/products#product-launch-stages). Further, by using this feature, you agree to the [Generative AI Preview terms and conditions](https://cloud.google.com/trustedtester/aitos) ("Preview Terms"). For this feature, you can process personal data as outlined in the [Cloud Data Processing Addendum](https://cloud.google.com/terms/data-processing-addendum), subject to applicable restrictions and obligations in the Agreement (as defined in the Preview Terms).
>
> <br />
>
When searching in your Gemini Enterprise app, you can apply a
relevance threshold so that only the documents that meet this threshold
are returned as results. This page explains how to specify a
relevance threshold in order to reduce the number of documents returned in
queries.

## About filtering by document-level relevance

Each document returned by a search query is given a relevance level, which
indicates the relevance of the returned document to the query. When you make a
query through an API call, you can set a relevance threshold. Setting a high
relevance threshold can reduce the number of documents returned by a query.

For example, if you find that search is returning too many documents of
insufficient relevance to your users, set the relevance threshold to high to
narrow the results to only those few that are most relevant. If the high setting
is too restrictive, try the medium setting.

> [!NOTE]
> **Note:** This document-level relevance filtering feature is different from and less precise than the [document-relevance score](https://docs.cloud.google.com/gemini/enterprise/docs/preview-search-results.md.txt#relevance-scores) that can be returned for search results.

## Data types and apps supported for document-level relevance filter

The document-level relevance filter can be applied to data stores with following kinds of data:

- Website data with advanced website indexing
- Custom unstructured data
- Custom structured data

The document-level relevance filter doesn't work for data stores with basic website indexing,
media data, or healthcare data.

Furthermore, the document-level relevance filter can't be used with blended search apps. Blended
search apps are apps that are connected to multiple data stores.

## Other kinds of filters

The document-level relevance filter is not the only way you can filter data returned by queries. You
can also use filter expressions to filter results based on metadata (in
unstructured data with metadata data stores) and field values (in structured
data stores).

For information, see [Filter search with metadata](https://docs.cloud.google.com/gemini/enterprise/docs/filter-search-metadata.md.txt).

If you use both a filter expression and the document-level relevance filter, the filter expression
is applied first to the results and then the document-level relevance filter is applied.

## Before you begin

Make sure you have created an app and data store and have ingested data
into your data store. For more information, see [Create a first-party
app](https://docs.cloud.google.com/gemini/enterprise/docs/create-app). See also [Data types and apps supported for
document-level relevance filter](https://docs.cloud.google.com/gemini/enterprise/docs/filter-by-relevance#supported).

## Search and filter results by document-level relevance

To filter by relevance, follow these steps:

> [!NOTE]
> **Note:** You can search over an app using the [`engines.servingConfigs.search`](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1/projects.locations.collections.engines.servingConfigs/search.md.txt) method and you can search over a data store using the [`dataStores.servingConfigs.search`](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1/projects.locations.collections.dataStores.servingConfigs/search.md.txt) method. For the following procedure, Google recommends searching using the `engines.servingConfigs.search` method.

1. 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 **Gemini Enterprise** page.

      [Go to Apps](https://console.cloud.google.com/gemini-enterprise/apps)
   2. On the **Apps** page, find the name of your app and get the app's ID from
      the **ID** column.

2. To filter search by document-level relevance, use the `relevanceThreshold`
   field with the [`engines.servingConfigs.search`](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.collections.engines.servingConfigs/search.md.txt) method.

   > [!IMPORTANT]
   > **Key Term:** In Gemini Enterprise, the term *app* can be used interchangeably with the term *engine* in the context of APIs. A Gemini Enterprise engine is a generic search engine where the `app_type` field is set to `APP_TYPE_INTRANET`.

   ```bash
   curl -X POST -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1alpha/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",
   "relevanceThreshold": "RELEVANCE_THRESHOLD"
   }'
   ```

   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.
   - `RELEVANCE_THRESHOLD`: one of the following: `HIGH`, `MEDIUM`, `LOW`, `LOWEST`.

   #### Example command and result

   ```
   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)"
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-search-app/servingConfigs/default_search:search" \
   -d '{
   "servingConfig": "projects/my-project-123/locations/global/collections/default_collection/engines/my-search-app/servingConfigs/default_search",
   "query": "What is the check grounding API",
   "relevanceThreshold": "HIGH"
   }'

   {
   "results": [
   {
     "id": "a082e70352c073a4443502477255bd2a",
     "document": {
       "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/a082e70352c073a4443502477255bd2a",
       "id": "a082e70352c073a4443502477255bd2a",
       "derivedStructData": {
         "displayLink": "cloud.google.com",
         "link": "https://cloud.google.com/example/docs/check-grounding",
         "htmlTitle": "Check grounding | Example | Google Cloud",
         "title": "Check grounding | Example | Google Cloud"
       }
     }
   }
   ],
   "totalSize": 1,
   "attributionToken": "f_B-CgwIidzwswYQyue15gESJDY2N2M1NmJkLTAwMDAtMjk3Ni1iMGI4LTg4M2QyNGZmNTZhOCIHR0VORVJJQypAjr6dFavEii3b7Ygt3o-aIoCymiLC8J4Vo4CXIra3jC3Usp0V24-aIt7tiC3n7YgtrsSKLeTtiC2DspoixsvzFw",
   "guidedSearchResult": {},
   "summary": {}
   }
   ```

   Here, the relevance threshold is set to high, so only the most
   relevant results are returned. In this example, only one document was determined
   to be highly relevant.
3. Test multiple queries with different thresholds to determine the best
   threshold settings for your data and application.