Retrieve knowledge - Tablestore - Alibaba Cloud Documentation Center

Prerequisites

An AgentStorage instance has been created and is in the normal state, and you have obtained the instance endpoint and instance name.
An API Key has been created.
The knowledge base to be retrieved already exists and contains documents in the completed state.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	Knowledge base name (required)
`subspace`	list<string>	List of subspaces, up to 32. Required when subspace is enabled
`retrievalQuery`	object	Retrieval query (required)
`retrievalQuery.type`	string	Query type (required). Currently only `TEXT` is supported
`retrievalQuery.text`	string	Retrieval text (required). Maximum 128 characters
`retrievalConfiguration`	object	Retrieval configuration. When not specified, the knowledge base-level configuration or system default is used
`retrievalConfiguration.searchType`	list<string>	Retrieval type
`retrievalConfiguration.denseVectorSearchConfiguration.numberOfResults`	int	Number of results returned by vector retrieval, up to 100
`retrievalConfiguration.fullTextSearchConfiguration.numberOfResults`	int	Number of results returned by full-text retrieval, up to 100
`retrievalConfiguration.rerankingConfiguration`	object	Reranking configuration
`retrievalConfiguration.filter`	object	Metadata filter condition

### Retrieval configuration priority

The retrieval configuration (retrievalConfiguration) of the Retrieve API determines the effective parameters by the following priority:

Priority	Source	Description
1 (highest)	Retrieve API parameters	The `retrievalConfiguration` passed in this request, effective only for the current request
2	Knowledge base-level configuration	Set when creating the knowledge base, can be modified at any time via UpdateKnowledgeBase
3 (lowest)	System defaults	Vector + full-text hybrid retrieval, WEIGHT weighted fusion (vector 0.7 : full-text 0.3), returning 20 results

When subspace is not enabled, the minimal retrieval request requires only knowledgeBaseName and retrievalQuery; when subspace is enabled, subspace must also be passed. When no retrieval configuration is explicitly specified, the system uses the knowledge base configuration or defaults.

### Operators supported by filter

#### Comparison operators

Operator	Symbol	Description	Applicable types
`equals`	=	Equal to	All types
`notEquals`	≠	Not equal to	All types
`greaterThan`	>	Greater than	long, double, date
`greaterThanOrEquals`	≥	Greater than or equal to	long, double, date
`lessThan`	<	Less than	long, double, date
`lessThanOrEquals`	≤	Less than or equal to	long, double, date

#### Set and match operators

Operator	Description	Applicable types
`in`	Value is in the given set	All types
`notIn`	Value is not in the given set	All types
`startsWith`	String prefix match	string
`stringContains`	String contains match	string
`listContains`	List field contains the specified element	list type

#### Logical combination operators

Operator	Description
`andAll`	All conditions are met simultaneously
`orAll`	Any condition is met
`notAll`	None of the conditions are met

andAll, orAll, and notAll support nesting, allowing you to build complex combined filter logic.

Request example

When using API Key authentication, pass the instance name and API Key through the x-ots-instancename and x-ots-apikey request headers.

curl -X POST https://<endpoint>/Retrieve \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "knowledgeBaseName": "product_docs_kb",
  "subspace": ["default"],
  "retrievalQuery": {"type": "TEXT", "text": "What are the installation steps for the product"},
  "retrievalConfiguration": {
    "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
    "denseVectorSearchConfiguration": {"numberOfResults": 10},
    "fullTextSearchConfiguration": {"numberOfResults": 10},
    "rerankingConfiguration": {
      "type": "RRF",
      "numberOfResults": 5,
      "rrfConfiguration": {"denseVectorSearchWeight": 0.6, "fullTextSearchWeight": 0.4, "k": 60}
    },
    "filter": {
      "andAll": [
        {"greaterThanOrEquals": {"key": "score", "value": 60}}
      ]
    }
  }
}'

Response

Field	Type	Description
`retrievalResults`	list<object>	List of retrieval results, sorted by relevance score in descending order
`retrievalResults[].docId`	string	Parent document ID
`retrievalResults[].chunkId`	int	Chunk ID
`retrievalResults[].ossKey`	string	Parent document OSS path
`retrievalResults[].score`	float	Relevance score; a higher value indicates higher relevance
`retrievalResults[].content`	string	Original chunk content
`retrievalResults[].subspace`	string	Subspace
`retrievalResults[].metadata`	object	Document metadata

{
    "code": "SUCCESS",
    "data": {
        "retrievalResults": [
            {
                "ossKey": "oss://example-bucket/docs/manual.pdf",
                "docId": "fc6ed97f-28ad-4dc0-9b73-bf4a7d67ab65",
                "chunkId": 0,
                "chunkType": "TEXT",
                "subspace": "default",
                "score": 0.6630394798989444,
                "content": "Product installation steps: 1. Download and extract the installation package. 2. Follow the installation wizard to complete the installation. 3. Start the product and confirm that the installation success page is displayed.", "metadata": {"author": "Zhang San", "date": "2026-01-22 10:00:59", "score": 80}
            }
        ]
    },
    "message": "success"
}