Method: corpora.documents.query

Performs semantic search over a Document.

HTTP request

POST https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*}:query

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The name of the Document to query. Example: corpora/my-corpus-123/documents/the-doc-abc

Request body

The request body contains data with the following structure:

JSON representation 
{
  "query": string,
  "resultsCount": integer,
  "metadataFilters": [
    {
      object (MetadataFilter)
    }
  ]
}
Fields
query

string

Required. Query string to perform semantic search.
resultsCount

integer

Optional. The maximum number of Chunks to return. The service may return fewer Chunks.

If unspecified, at most 10 Chunks will be returned. The maximum specified result count is 100.
metadataFilters[]

object (MetadataFilter)

Optional. Filter for Chunk metadata. Each MetadataFilter object should correspond to a unique key. Multiple MetadataFilter objects are joined by logical "AND"s.

Note: Document-level filtering is not supported for this request because a Document name is already specified.

Example query: (year >= 2020 OR year < 2010) AND (genre = drama OR genre = action)

MetadataFilter object list: metadataFilters = [ {key = "chunk.custom_metadata.year" conditions = [{int_value = 2020, operation = GREATER_EQUAL}, {int_value = 2010, operation = LESS}}, {key = "chunk.custom_metadata.genre" conditions = [{stringValue = "drama", operation = EQUAL}, {stringValue = "action", operation = EQUAL}}]

Example query for a numeric range of values: (year > 2015 AND year <= 2020)

MetadataFilter object list: metadataFilters = [ {key = "chunk.custom_metadata.year" conditions = [{int_value = 2015, operation = GREATER}]}, {key = "chunk.custom_metadata.year" conditions = [{int_value = 2020, operation = LESS_EQUAL}]}]

Note: "AND"s for the same key are only supported for numeric values. String values only support "OR"s for the same key.

Response body

Response from documents.query containing a list of relevant chunks.

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

JSON representation 
{
  "relevantChunks": [
    {
      object (RelevantChunk)
    }
  ]
}
Fields
relevantChunks[]

object (RelevantChunk)

The returned relevant chunks.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/generative-language.retriever
  • https://www.googleapis.com/auth/generative-language.retriever.readonly

For more information, see the Authentication Overview.