Method: projects.locations.dataStores.documents.search

Searches the Documents of a single DataStore.

Returns ranked sub-document segments, each referring back to the Document it came from and carrying the provenance needed to cite it.

HTTP request

POST https://vectorsearch.googleapis.com/v1beta/{parent}/documents:search

Path parameters

Parameters
parent

string

Required. The DataStore to search. Format: projects/{project}/locations/{location}/dataStores/{dataStore}

Request body

The request body contains data with the following structure:

JSON representation 
{
  "topK": integer,
  "documentIds": [
    string
  ],
  "rankingSpec": {
    object (RankingSpec)
  },
  "filter": {
    object
  },
  "outputFields": {
    object (OutputFields)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "textQuery": {
    object (TextQuery)
  }
  // End of mutually exclusive fields.
}
Fields
topK

integer

Optional. Number of results to return. Defaults to 10. Values above 100 are coerced to 100.
documentIds[]

string

Optional. Restrict the search to these Document IDs. Max 100. If empty, the whole DataStore is searched.
rankingSpec

object (RankingSpec)

Optional. Controls how results are ranked.
filter

object (Struct format)

Optional. Restricts the search to segments that match this filter, a JSON object over the field paths of a DocumentSearchResult:

  • metadata.<property>: a property declared in the DataStore's documentMetadataSchema, e.g. metadata.category.
  • unstructured_details.page_range.start_page and .end_page: for an UNSTRUCTURED DataStore. Not every segment has a page range; see UnstructuredSegmentDetails.page_range.
  • video_details.start_offset and .end_offset: in seconds, for a VIDEO DataStore.

Comparisons: $eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $all, and $exists. Combine them with $and, $or, and $not, nested at most two levels deep. For example:

{"$and": [{"metadata.year": {"$gte": 2025}}, {"unstructured_details.page_range.start_page": {"$lte": 20}}]}
outputFields

object (OutputFields)

Optional. Fields to return on each result.
Required. The query to search for. Exactly one query type must be set. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
textQuery

object (TextQuery)

A text query.
End of mutually exclusive fields.

Response body

Response message for DocumentSearchService.SearchDocuments.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "results": [
    {
      object (DocumentSearchResult)
    }
  ],
  "warnings": [
    {
      object (Status)
    }
  ]
}
Fields
results[]

object (DocumentSearchResult)

Output only. The matching document segments that match the search criteria, ordered by relevance.
warnings[]

object (Status)

Output only. Warnings or non-fatal errors that occurred during execution.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/vectorsearch
  • https://www.googleapis.com/auth/vectorsearch.readonly

For more information, see the Authentication Overview.

TextQuery

A text query.

JSON representation 
{
  "text": string
}
Fields
text

string

Required. The text to search for.

RankingSpec

Controls how results are ranked.

JSON representation 
{
  "rerankingSpec": {
    object (RerankingSpec)
  }
}
Fields
rerankingSpec

object (RerankingSpec)

Optional. Controls the re-ranking stage.

RerankingSpec

Configuration for semantic re-ranking applied to candidate results after hybrid retrieval and Reciprocal Rank Fusion (RRF).

JSON representation 
{
  "enabled": boolean,
  "rankOversamplingFactor": integer
}
Fields
enabled

boolean

Optional. Whether to re-rank the fused results. Defaults to false: results are returned in RRF-fused order unless the caller opts in.

When enabled, re-ranking uses semantic-ranker-fast@latest on the Vertex Ranking Service, and requires the Discovery Engine API to be enabled on the caller's project.

Not supported for a VIDEO DataStore: a request that enables it fails with INVALID_ARGUMENT.
rankOversamplingFactor

integer

Optional. The factor by which to oversample candidates before re-ranking. The total number of candidates retrieved for re-ranking is min(rankOversamplingFactor * topK, 200). After re-ranking, results are trimmed to SearchDocumentsRequest.top_k.

Ignored unless enabled is true. When enabled, defaults to 5 (retrieving min(5 * topK, 200) candidates, with a maximum of 200).

To re-rank without oversampling, set this field to 1.

OutputFields

Fields to return on each DocumentSearchResult, beyond those every result carries.

JSON representation 
{
  "metadata": [
    string
  ]
}
Fields
metadata[]

string

Optional. Metadata properties to return in DocumentSearchResult.document.metadata, named as declared in the DataStore's documentMetadataSchema. A nested property is named by its dotted path, e.g. address.city, without the metadata. prefix filter uses. "*" returns every declared property. Unset returns none. A property the Document has no value for is omitted.

DocumentSearchResult

A single matching segment of a Document.

JSON representation 
{
  "document": {
    object (Document)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "videoDetails": {
    object (VideoSegmentDetails)
  },
  "unstructuredDetails": {
    object (UnstructuredSegmentDetails)
  }
  // End of mutually exclusive fields.
}
Fields
document

object (Document)

Output only. The Document this segment came from, including its resource name and the Cloud Storage location it was ingested from.

Note that not all Document fields are populated. For the full Document, call documents.get on the returned document name.
Details of where the segment sits within its Document. Which field is set follows the parent DataStore's document_type. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
videoDetails

object (VideoSegmentDetails)

Set when the parent DataStore's documentType is VIDEO.
unstructuredDetails

object (UnstructuredSegmentDetails)

Set when the parent DataStore's documentType is UNSTRUCTURED.
End of mutually exclusive fields.

VideoSegmentDetails

Locates a segment within a video Document.

JSON representation 
{
  "startOffset": string,
  "endOffset": string
}
Fields
startOffset

string (Duration format)

Output only. Where this segment begins, relative to the start of the source video.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
endOffset

string (Duration format)

Output only. Where this segment ends, relative to the start of the source video.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

UnstructuredSegmentDetails

Locates a segment within an unstructured Document, and carries its text.

JSON representation 
{
  "contentSnippet": string,
  "pageRange": {
    object (PageRange)
  }
}
Fields
contentSnippet

string

Output only. Text content of the segment.
pageRange

object (PageRange)

Output only. Where the segment sits in the source document. Set for PDF, PowerPoint and Excel files, where a page is a PDF page, a slide or a sheet. For plain-text and Word files, set only when the file is split into pages (pageSegmentationConfig with digital parsing); the pages are then consecutive sections of the text, numbered in order.

PageRange

A page range within the source document. Pages are 1-based and the range is inclusive; a single page is represented as startPage == endPage.

JSON representation 
{
  "startPage": string,
  "endPage": string
}
Fields
startPage

string (int64 format)

Output only. First page of the range.
endPage

string (int64 format)

Output only. Last page of the range.