Required. The resource name of the Location from which to retrieve RagContexts. The users must have permission to make a call in the project. Format:projects/{project}/locations/{location}.
Request body
The request body contains data with the following structure:
Optional. The representation of the rag source. It can be used to specify corpus only or ragfiles. Currently only support one corpus or multiple files from one corpus. In the future we may open up multiple corpora support.
vectorDistanceThreshold (deprecated)number
Optional. Only return contexts with vector distance smaller than the threshold.
The query to retrieve contexts. Currently only text query is supported.querycan be only one of the following:
textstring
Optional. The query in text format to get relevant contexts.
JSON representation
{"similarityTopK":integer,"ranking":{object (Ranking)},"ragRetrievalConfig":{object (RagRetrievalConfig)},// query"text":string// Union type}
Ranking
Configurations for hybrid search results ranking.
Fields
alphanumber
Optional. Alpha value controls the weight between dense and sparse vector search results. The range is [0, 1], while 0 means sparse vector search only and 1 means dense vector search only. The default value is 0.5 which balances sparse and dense vector search equally.
If the file is imported from Cloud Storage or Google Drive, sourceUri will be original file URI in Cloud Storage or Google Drive; if file is uploaded, sourceUri will be file display name.
sourceDisplayNamestring
The file display name.
textstring
The text chunk.
distance (deprecated)number
The distance between the query dense embedding vector and the context text vector.
sparseDistance (deprecated)number
The distance between the query sparse embedding vector and the context text vector.
According to the underlying Vector DB and the selected metric type, the score can be either the distance or the similarity between the query and the context and its range depends on the metric type.
For example, if the metric type is COSINE_DISTANCE, it represents the distance between the query and the context. The larger the distance, the less relevant the context is to the query. The range is [0, 2], while 0 means the most relevant and 2 means the least relevant.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-06-27 UTC."],[],[],null,["# Method: locations.retrieveContexts\n\n**Full name**: projects.locations.retrieveContexts\n\nRetrieves relevant contexts for a query. \n\n### Endpoint\n\npost `https:``/``/{service-endpoint}``/v1beta1``/{parent}:retrieveContexts` \nWhere `{service-endpoint}` is one of the [supported service endpoints](/vertex-ai/docs/reference/rest#rest_endpoints).\n\n### Path parameters\n\n`parent` `string` \nRequired. The resource name of the Location from which to retrieve RagContexts. The users must have permission to make a call in the project. Format: `projects/{project}/locations/{location}`.\n\n### Request body\n\nThe request body contains data with the following structure:\nFields `query` `object (`[RagQuery](/vertex-ai/docs/reference/rest/v1beta1/projects.locations/retrieveContexts#RagQuery)`)` \nRequired. Single RAG retrieve query. \n`data_source` `Union type` \nData Source to retrieve contexts. `data_source` can be only one of the following:\n`vertexRagStore` `object (`[VertexRagStore](/vertex-ai/docs/reference/rest/v1beta1/projects.locations/retrieveContexts#VertexRagStore)`)` \nThe data source for Vertex RagStore. \n\n### Response body\n\nResponse message for [VertexRagService.RetrieveContexts](/vertex-ai/docs/reference/rest/v1beta1/projects.locations/retrieveContexts#google.cloud.aiplatform.v1beta1.VertexRagService.RetrieveContexts).\n\nIf successful, the response body contains data with the following structure:\nFields `contexts` `object (`[RagContexts](/vertex-ai/docs/reference/rest/v1beta1/projects.locations/retrieveContexts#RagContexts)`)` \nThe contexts of the query. \n\nVertexRagStore\n--------------\n\nThe data source for Vertex RagStore.\nFields `ragCorpora[]` \n**(deprecated)** `string` \n| This item is deprecated!\n\nOptional. Deprecated. Please use ragResources to specify the data source.\n`ragResources[]` `object (`[RagResource](/vertex-ai/docs/reference/rest/v1beta1/projects.locations/retrieveContexts#RagResource)`)` \nOptional. The representation of the rag source. It can be used to specify corpus only or ragfiles. Currently only support one corpus or multiple files from one corpus. In the future we may open up multiple corpora support.\n`vectorDistanceThreshold` \n**(deprecated)** `number` \n| This item is deprecated!\n\nOptional. Only return contexts with vector distance smaller than the threshold. \n\nRagResource\n-----------\n\nThe definition of the Rag resource.\nFields `ragCorpus` `string` \nOptional. RagCorpora resource name. Format: `projects/{project}/locations/{location}/ragCorpora/{ragCorpus}`\n`ragFileIds[]` `string` \nOptional. ragFileId. The files should be in the same ragCorpus set in ragCorpus field. \n\nRagQuery\n--------\n\nA query to retrieve relevant contexts.\nFields `similarityTopK` \n**(deprecated)** `integer` \n| This item is deprecated!\n\nOptional. The number of contexts to retrieve.\n`ranking` \n**(deprecated)** `object (`[Ranking](/vertex-ai/docs/reference/rest/v1beta1/projects.locations/retrieveContexts#Ranking)`)` \n| This item is deprecated!\n\nOptional. Configurations for hybrid search results ranking.\n`ragRetrievalConfig` `object (`[RagRetrievalConfig](/vertex-ai/docs/reference/rest/v1beta1/projects.locations.cachedContents#RagRetrievalConfig)`)` \nOptional. The retrieval config for the query. \n`query` `Union type` \nThe query to retrieve contexts. Currently only text query is supported. `query` can be only one of the following:\n`text` `string` \nOptional. The query in text format to get relevant contexts. \n\nRanking\n-------\n\nConfigurations for hybrid search results ranking.\nFields `alpha` `number` \nOptional. Alpha value controls the weight between dense and sparse vector search results. The range is \\[0, 1\\], while 0 means sparse vector search only and 1 means dense vector search only. The default value is 0.5 which balances sparse and dense vector search equally. \n\nRagContexts\n-----------\n\nRelevant contexts for one query.\nFields `contexts[]` `object (`[Context](/vertex-ai/docs/reference/rest/v1beta1/projects.locations/retrieveContexts#Context)`)` \nAll its contexts. \n\nContext\n-------\n\nA context of the query.\nFields `sourceUri` `string` \nIf the file is imported from Cloud Storage or Google Drive, sourceUri will be original file URI in Cloud Storage or Google Drive; if file is uploaded, sourceUri will be file display name.\n`sourceDisplayName` `string` \nThe file display name.\n`text` `string` \nThe text chunk.\n`distance` \n**(deprecated)** `number` \n| This item is deprecated!\n\nThe distance between the query dense embedding vector and the context text vector.\n`sparseDistance` \n**(deprecated)** `number` \n| This item is deprecated!\n\nThe distance between the query sparse embedding vector and the context text vector.\n`chunk` `object (`[RagChunk](/vertex-ai/docs/reference/rest/v1beta1/RagChunk)`)` \nContext of the retrieved chunk.\n`score` `number` \nAccording to the underlying Vector DB and the selected metric type, the score can be either the distance or the similarity between the query and the context and its range depends on the metric type.\n\nFor example, if the metric type is COSINE_DISTANCE, it represents the distance between the query and the context. The larger the distance, the less relevant the context is to the query. The range is \\[0, 2\\], while 0 means the most relevant and 2 means the least relevant."]]
