Get search summaries

This page shows how to use the API to get search summaries with your search results. It also explains the options that are available with search summaries. For unstructured and website data only. For more information about getting search results, Get search results.

Before you begin

Depending on the type of app you have, complete the following requirements:

Get a search summary

A search summary is a short summarization of the top one or more search results returned in a search response. The summary itself is taken from the extractive answers returned in the response. Therefore, to get a summary, you must also get extractive answers with your search results. For more information, see Get extractive answers (Preview).

The following image shows the summary when PDFs in a data store are queried with the summaryResultCount set to 5. The summary content can vary depending on the app configurations.

Query is quote Define operating
expenses endquote. The search summary section shows a summary extracted from the
top results.
Figure 1. Sample widget with a search summary.

Search summaries can include Markdown-formatted text. For this reason, consider using a Markdown parser in your application to render Markdown text.

To get a search summary, follow these steps:

  1. Submit a search request that includes contentSearchSpec.summarySpec and specifies values for summaryResultCount and maxExtractiveAnswerCount. For more information about submitting a search request, see Get search results.

    In the following example, summarySpec indicates that you want a search summary and that the summary should be generated from the top three search results.

    "contentSearchSpec":
     {
       "summarySpec":
       {
         "summaryResultCount": 3
       },
       "extractiveContentSpec": { "maxExtractiveAnswerCount" : 1}
     }
    
    • summaryResultCount: The number of top results to generate the search summary from. If the number of results returned is less than summaryResultCount, the summary is generated from all of the results. The maximum value is 5.
    • maxExtractiveAnswerCount: The number of extractive answers to return for each search result. The default value is 0 and the maximum is 1.
  2. Get the summary from the search response. One summary property is returned in each response.

    Here is an example of a summary returned at the end of a search response:

    "summary":
    {
      "summaryText": "BigQuery is Google Cloud's fully managed and completely
      serverless enterprise data warehouse. BigQuery supports all data types,
      works across clouds, and has built-in machine learning and business
      intelligence, all within a unified platform."
    }
    

Get citations

Citations, when specified, are numbers that are placed inline in a search summary. These numbers indicate from which search results specific sentences in the summary are taken.

To get citations, follow these steps:

  1. Submit a search request that includes contentSearchSpec.summarySpec and specifies "includeCitations": true. For more information about submitting a search request, see Get search results.

    In the following example, summarySpec indicates that you want a search summary, that the summary should be generated from the top three search results, and that citations should be included in the summary.

    "contentSearchSpec":
     {
       "summarySpec":
       {
         "summaryResultCount": 3,
         "includeCitations": true
       },
       "extractiveContentSpec": { "maxExtractiveAnswerCount" : 1}
     }
    
    • summaryResultCount: The number of top results to generate the search summary from. If the number of results returned is less than summaryResultCount, the summary is generated from all of the results. The maximum value is 5.
    • includeCitations: A boolean that specifies whether citations are returned.
    • maxExtractiveAnswerCount: The number of extractive answers to return for each search result. The default value is 0 and the maximum is 1.
  2. Get the summary, with citations, from the search response. One summary property is returned in each response.

    Here is an example of a summary, with citations and citation metadata, returned at the end of a search response:

    "summary": {
     "summaryText": "BigQuery is Google Cloud's fully managed and completely
      serverless enterprise data warehouse [1]. BigQuery supports all data types,
      works across clouds, and has built-in machine learning and business
      intelligence, all within a unified platform [2, 3].",
     "summaryWithMetadata": {
       "summary": "BigQuery is Google Cloud's fully managed and completely
       serverless enterprise data warehouse. BigQuery supports all data types,
       works across clouds, and has built-in machine learning and business
       intelligence, all within a unified platform.",
       "citationMetadata": {
         "citations": [
           {
             "startIndex": "0",
             "endIndex": "101",
             "sources": [
               {
                 "uri": "gs://example-dataset/html/6344007140738632642.html",
                 "title": "About BigQuery",
                 "id": "b6344007140738632642",
                 "referenceIndex": "0"
               },
               {
                 "uri": "gs://example-dataset/html/1365490014946172719.html",
                 "title": "Google Cloud article",
                 "id": "b1365490014946172719",
                 "referenceIndex": "1"
               },
               {
                 "uri": "gs://example-dataset/html/2687910668117268120.html",
                 "title": "BigQuery document",
                 "id": "a2687910668117268120",
                 "referenceIndex": "2"
               }
             ]
           },
           {
             "startIndex": "103",
             "endIndex": "230",
             "sources": [
               {
                 "referenceIndex": "0"
                },
               {
                 "referenceIndex": "1"
               },
               {
                 "referenceIndex": "2",
               }
             ]
           }
         ]
       },
       "references": [
       {
         "title": "Sports in the United States",
         "docName": "projects/123/locations/global/collections/default_collection/dataStores/ds-123/branches/0/documents/b6344007140738632642",
         "uri": "https://example.com/bigqueryA"
       },
       {
         "title": "Sports in the United States",
         "docName": "projects/123/locations/global/collections/default_collection/dataStores/ds-123/branches/0/documents/b1365490014946172719",
         "uri": "https://example.com/bigqueryB"
       },
       {
         "title": "Sports in the United States",
         "docName": "projects/123/locations/global/collections/default_collection/dataStores/ds-123/branches/0/documents/a268791066811726812",
         "uri": "https://example.com/bigqueryC"
       }
     ]
    }
    }
    
    • summaryText: The search summary, with citation numbers. The citation numbers refer to the returned search results and are 1-indexed. For example, [1] means that the sentence is attributed to the first search result. [2, 3] means that the sentence is attributed to both the second and third search results.
    • citations: For each sentence in the summary that has a citation, lists the metadata for that citation.
    • startIndex: Indicates the start of the sentence, measured in unicode bytes.
    • endIndex: Indicates the end of the sentence, measured in unicode bytes.
    • sources: Lists the referenceIndex for each source that was included in the sentence's citation. referenceIndex is the index number assigned to a source. The first source's referenceIndex isn't always explicitly returned in the response. Because referenceIndex is 0-indexed, the first source always has a referenceIndex of 0.
    • references: Lists metadata for each reference that was cited in the summary. Metadata includes title, docName, and uri.

Ignore adversarial queries

Adversarial queries include negative comments or are designed to generate unsafe, policy-violating output. You can specify that no search summaries should be returned for adversarial queries. When an adversarial query is ignored, the summaryText property contains boilerplate text indicating that no search summary is returned. Search documents are returned for adversarial queries even though search summaries are not.

To specify that no search summaries should be returned for adversarial queries, follow these steps:

  1. Submit a search request that includes contentSearchSpec.summarySpec and specifies "ignoreAdversarialQuery": true. For more information about submitting a search request, see Get search results.

    In the following example, summarySpec indicates that you want a search summary, that the summary should be generated from the top three search results, but that no summary should be returned for adversarial queries.

    "contentSearchSpec":
     {
       "summarySpec":
       {
         "summaryResultCount": 3,
         "ignoreAdversarialQuery": true
       },
       "extractiveContentSpec": { "maxExtractiveAnswerCount" : 1}
     }
    
    • summaryResultCount: The number of top results to generate the search summary from. If the number of results returned is less than summaryResultCount, the summary is generated from all of the results. The maximum value is 5.
    • ignoreAdversarialQuery: A boolean that specifies that no search summaries should be returned for adversarial queries.
    • maxExtractiveAnswerCount: The number of extractive answers to return for each search result. The default value is 0 and the maximum is 1.
  2. See the summary property that is returned for an adversarial search request.

    Here is an example:

    "summary":
    {
      "summaryText": "We do not have a summary for your query. Here are some
      search results.",
      "summarySkippedReasons": [
       "ADVERSARIAL_QUERY_IGNORED"
     ]
    }
    
    • summaryText: Boilerplate text indicating that no search summary is returned.
    • summarySkippedReasons: An enumeration with values for summary-skipped reasons.

Ignore non-summary seeking queries

Non-summary seeking queries return results that are not suitable for summarization. For example, "why is the sky blue" and "Who is the best soccer player in the world?" are summary-seeking queries, but "SFO airport" and "world cup 2026" are not. They are most likely navigational queries. You can specify that no search summaries should be returned for non-summary seeking queries. Search documents are returned for non-summary seeking queries even though search summaries are not.

To specify that no search summaries should be returned for non-summary seeking queries, follow these steps:

  1. Submit a search request that includes contentSearchSpec.summarySpec and specifies "ignoreNonSummarySeekingQuery": true. For more information about submitting a search request, see Get search results.

    In the following example, summarySpec indicates that you want a search summary, the summary should be generated from the top three search results, but that no summary should be returned for non-summary seeking queries.

    "contentSearchSpec":
     {
       "summarySpec":
       {
         "summaryResultCount": 3,
         "ignoreNonSummarySeekingQuery": true
       },
       "extractiveContentSpec": { "maxExtractiveAnswerCount" : 1}
     }
    
    • summaryResultCount: The number of top results to generate the search summary from. If the number of results returned is less than summaryResultCount, the summary is generated from all of the results. The maximum value is 5.
    • ignoreNonSummarySeekingQuery: A boolean that specifies that no search summaries should be returned for non-summary seeking queries.
    • maxExtractiveAnswerCount: The number of extractive answers to return for each search result. The default value is 0 and the maximum is 1.
  2. See the summary property that is returned for a non-summary seeking search request.

    Here is an example:

    "summary":
    {
      "summaryText": "We do not have a summary for your query. Here are some
      search results.",
      "summarySkippedReasons": [
        "NON_SUMMARY_SEEKING_QUERY_IGNORED"
     ]
    }
    
    • summaryText: Boilerplate text indicating that no search summary is returned.
    • summarySkippedReasons: An enumeration with values for summary-skipped reasons.

Get customized summaries

You can get customized summaries by providing natural-language instructions. This feature is available for the search widget by using the console, and for the API by entering instructions in the modelPromptSpec.preamble field.

You can request customizations such as length, level of detail, style of output (such as "simple"), language of output, focus of answer, and format (such as tables, bullets, and XML).

For example, for the query "What are the benefits of bigquery?" you could enter customization instructions like in the following examples:

  • Example instruction: "please show the answer format in an ordered list"

    Example answer:

    The benefits of BigQuery are:
    
    1. Increased business productivity
    2. IT staff productivity
    3. Reduced infrastructure costs
    4. Loading and exporting data are free
    
  • Example instruction: give a very detailed answer

    Example answer:

    BigQuery is a serverless, highly scalable, and cost-effective cloud data warehouse that enables businesses to analyze all their data very quickly. It is a fully managed service that takes care of provisioning, scaling, and managing the underlying infrastructure, so you can focus on analyzing your data. BigQuery is also integrated with other Google Cloud services, such as Google Kubernetes Engine, Cloud Data Fusion, and Cloud Dataproc, making it easy to build and deploy data pipelines.
    
    Here are some of the benefits of using BigQuery:
    
    * **Fast and scalable:** BigQuery can process petabytes of data very quickly, and it can scale to handle even the most demanding workloads. * **Cost-effective:** BigQuery is a very cost-effective way to store and analyze data. You only pay for the data that you use, and there are no upfront costs or commitments. * **Secure:** BigQuery is a secure platform that meets the needs of even the most security-conscious organizations. * **Easy to use:** BigQuery is easy to use, even for non-technical users. It has a simple and intuitive user interface, and it supports a variety of data sources. * **Integrated with other Google Cloud services:** BigQuery is integrated with other Google Cloud services, making it easy to build and deploy data pipelines.
    
    If you are looking for a fast, scalable, and cost-effective way to analyze your data, then BigQuery is a great option.
    

Best practices for customized summaries

If you plan to use this feature, do the following:

  • Request only one customization at a time. Don't combine customizations—for example, requesting an HTML table in French.
  • Google recommends that you impose limits on what customizations your end users can request—for example, by offering a selector with a set of predefined customizations.

Customize summaries

You can get customized summaries for only the search widget by using the console or, for any search request, by using the API.

To get a customized summary, follow these steps:

Console

  1. In the Google Cloud console, go to the Search and Conversation page.

    Search and Conversation

  2. Click the name of the app that you want to edit.

  3. Go to Configurations > Widget.

  4. Make sure your search widget's Search type is set to Search with an answer or Search with follow-ups. This feature isn't available if Search is selected.

  5. Turn on Enable summary customization.

  6. To enter summary instructions, do one of the following:

    • Enter free-form instructions: Enter your own natural language instructions in the Preamble field.
    • Use template instructions: Click Replace with a template and select one of the predefined template instructions. The predefined template appears in the Preamble field after you select it.
  7. Test the customized summary generation for your app by searching in the Preview pane.

  8. To reset to the last saved set of instructions, click Reset preamble.

  9. To save your settings to the widget, click Save and publish.

REST

  1. Submit a search request that includes contentSearchSpec.summarySpec and specifies the customization instruction in modelPromptSpec.preamble. For more information about submitting a search request, see Get search results.

    In the following example, summarySpec indicates that you want a search summary, the summary should be generated from the top three search results, and the summary should be customized as though it is being explained to a 10-year-old.

    "contentSearchSpec":
      {
        "summarySpec":
        {
          "summaryResultCount": 3,
          "modelPromptSpec":
          {
            "preamble": "explain like you would to a ten year old"
          }
        }
      }
    
    • summaryResultCount: The number of top results to generate the search summary from. If the number of results returned is less than summaryResultCount, the summary is generated from all of the results. The maximum value is 5.
    • preamble: The instruction for customization.
  2. Get the customized summary from the search response.

    Here is an example of a customized summary that is returned:

    "summary":
    {
      "summaryText": "BigQuery is a serverless data warehouse that helps you
      analyze all your data very quickly. It's very easy to use and you don't
      need to worry about managing servers or infrastructure. BigQuery is also
      very scalable, so you can analyze large datasets without any problems."
    }
    
    • summaryText: The customized search summary.

Specify the summarization model

You can specify the model that you want to use to generating summaries. You can choose a fine-tuned version of the text-bison@002 model, or you can choose Gemini Pro, which is in Public preview. The default is the text-bison@002 model.

To change the model version:

  1. Submit a search request that includes ContentSearchSpec and specifies the model version in SummarySpec.ModelSpec.

    "contentSearchSpec": {
      "summarySpec": {
        "modelSpec": {
          "version": MODEL_VERSION
         }
       }
     }
    
    • MODEL_VERSION: Specifies which model to use to generate summaries. Supported values are:

      • stable: string. Default value when no value is specified. Uses a generally available, fine-tuned version of the text-bison@001 model.
      • preview: string. (Public preview) Uses the Gemini Pro model. For more information about Gemini Pro, see Vertex AI Gemini API.

Limitations of search summaries

You might encounter the following limitations when using search summaries:

  • Because LLMs are used to generate search summaries and citations, the limitations of LLMs also apply to Vertex AI Search summaries.

    For general information about these LLM limitations, see PaLM API limitations in the Vertex AI documentation.

  • Search queries that require complex logical or analytical reasoning or understanding of the world can lead to search summaries that contain incorrect information (hallucinations) or information that is not present in the unstructured or website data.

  • Some statements in the search summary might not contain a citation and, in rare cases, citations might be incorrectly attributed to a statement.

  • Complex documents might be incorrectly parsed by the LLM. In this case, the summary might be incomplete or incorrect.

  • Because customization instructions are in natural language, adherence to instructions can't be guaranteed for all requests.