Retrieval and Ranking - Tablestore - Alibaba Cloud Documentation Center

Prerequisites

A knowledge base has been created and documents have been imported, and the document status is Completed (documents in Pending or Indexing status cannot be retrieved).
If the knowledge base has subspaces enabled, you must pass subspace during retrieval, with a maximum of 32 subspaces.
Metadata filter fields must be defined through metadata when creating the knowledge base and cannot be added at runtime.
The retrieval text (retrievalQuery.text) can be up to 128 characters.

Retrieval Configuration Priority

The retrieval configuration (retrievalConfiguration) of the Retrieve interface determines the parameters that take effect based on the following priority:

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

The simplest retrieval request only requires passing knowledgeBaseName and retrievalQuery. The system automatically uses the knowledge base configuration or default values.

Retrieval Types

Type	Description	Applicable scenarios
`DENSE_VECTOR`	Vector retrieval, based on semantic similarity	Describe requirements in natural language where semantic understanding is needed. For example, "how to install" can match "deployment steps"
`FULL_TEXT`	Full-text retrieval, based on keyword matching	Enter exact keywords, proper nouns, or identifiers

Vector retrieval and full-text retrieval have complementary recall capabilities: vector retrieval excels at semantic understanding, while full-text retrieval excels at exact matching. It is recommended to enable both retrieval types simultaneously and fuse the results through Rerank.

Rerank Strategies

Rerank fuses and ranks the results from vector retrieval and full-text retrieval, then returns the final results.

WEIGHT (Weighted Fusion)

Weights the scores of vector and full-text retrieval by proportion. Suitable for scenarios that require fine-grained control over the contribution ratio of the two retrieval paths. Recommended as the default choice.

Parameter	Type	Default value	Description
`denseVectorSearchWeight`	double	0.7	Weight of vector retrieval
`fullTextSearchWeight`	double	0.3	Weight of full-text retrieval

RRF (Reciprocal Rank Fusion)

Fuses multi-path retrieval results by weighting the reciprocal of ranks. No additional model invocation is required, resulting in low latency and stable performance.

Parameter	Type	Default value	Description
`denseVectorSearchWeight`	double	1.0	Weight of vector retrieval
`fullTextSearchWeight`	double	1.0	Weight of full-text retrieval
`k`	int	60	RRF algorithm parameter, must be greater than 0

Configuration example:

{
  "rerankingConfiguration": {
    "type": "RRF",
    "numberOfResults": 5,
    "rrfConfiguration": {
      "denseVectorSearchWeight": 0.6,
      "fullTextSearchWeight": 0.4,
      "k": 20
    }
  }
}

MODEL (Model Rerank)

Invokes a Rerank model (such as gte-rerank-v2) to re-rank candidate results. This delivers the highest ranking quality but introduces additional latency and computational costs.

Parameter	Type	Default value	Description
`provider`	string	`bailian`	Rerank model provider, currently only supports Bailian
`model`	string	`gte-rerank-v2`	Rerank model name

Strategy Selection Recommendations

Scenario	Recommended strategy
General scenarios, sensitive to latency	RRF
Requires fine-grained control over the ratio of vector to full-text retrieval	WEIGHT
Requires the highest ranking quality and can tolerate additional latency	MODEL

Metadata Filtering

During retrieval, use the filter parameter to filter results by metadata conditions and narrow down the candidate range. Filter fields must be defined through metadata when creating the knowledge base. For the complete list of operators, see Retrieve Knowledge API.

Comparison Operators

Operator	Symbol	Description	Applicable types
`equals`	=	Equals	All types
`notEquals`	!=	Not equals	All types
`greaterThan`	>	Greater than	long, double, date
`greaterThanOrEquals`	>=	Greater than or equals	long, double, date
`lessThan`	<	Less than	long, double, date
`lessThanOrEquals`	<=	Less than or equals	long, double, date

Set and Match Operators

Operator	Description	Applicable types
`in`	Value is in the specified set	All types
`notIn`	Value is not in the specified 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 must be met simultaneously
`orAll`	Any condition is met
`notAll`	None of the conditions are met

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

Filter Examples

Query documents where category is "technology" or "science", score >= 60, and title starts with "product":

{
  "filter": {
    "andAll": [
      {"in": {"key": "category", "value": ["technology", "science"]}},
      {"greaterThanOrEquals": {"key": "score", "value": 60}},
      {"startsWith": {"key": "title", "value": "product"}}
    ]
  }
}

Use orAll to implement "or" logic, querying documents where status is "active" or score > 90:

{
  "filter": {
    "orAll": [
      {"equals": {"key": "status", "value": "active"}},
      {"greaterThan": {"key": "score", "value": 90}}
    ]
  }
}

Performing Retrieval

Console

Open the target knowledge base, select Retrieval Test from the left navigation, and follow these steps to verify the retrieval results:

Enter the retrieval text in the Content input box. If the knowledge base has subspaces enabled, also fill in the subspace name.
In Search Type, select Vector Retrieval and/or Full-text Retrieval.
Set Vector TopK, Full-text TopK, and Rerank TopK (you can keep the default values).
Select a Rerank Strategy: Model, Weight, or RRF. When Weight is selected, you can set the vector/full-text retrieval weights.
If the knowledge base has metadata fields defined, you can add metadata filter conditions.
Click Run Retrieval to view the hit chunk content, source, and relevance score in Retrieved Chunks.

For your first test, we recommend using the default parameters. After confirming that the target content can be retrieved, gradually adjust TopK and Rerank strategy.

SDK

Python

Minimal example: no retrieval parameters are passed, using knowledge base-level configuration or system default values:

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

resp = client.retrieve({
    "knowledgeBaseName": "product_docs_kb",
    "retrievalQuery": {"type": "TEXT", "text": "What are the installation steps for the product"}
})

for r in resp["data"]["retrievalResults"]:
    print(f"[{r['score']:.4f}] {r['content'][:80]}...")

Complete example: set retrieval parameters in the request to override knowledge base-level configuration:

resp = client.retrieve({
    "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": [
                {"in": {"key": "category", "value": ["product docs"]}}
            ]
        }
    }
})

for result in resp["data"]["retrievalResults"]:
    print(f"[score={result['score']:.4f}] {result['content'][:100]}...")
    print(f"  source: {result['ossKey']}, chunkId: {result['chunkId']}")

Use Model classes to build the request for better IDE code completion and type checking:

from tablestore_agent_storage import AgentStorageClient
from tablestore_agent_storage.models import (
    RetrieveRequest, RetrievalQuery, RetrievalQueryType
)

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

resp = client.retrieve(RetrieveRequest(
    knowledge_base_name="product_docs_kb",
    retrieval_query=RetrievalQuery(
        text="What are the installation steps for the product",
        type=RetrievalQueryType.TEXT
    )
))

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.retrieve({
  knowledgeBaseName: 'product_docs_kb',
  retrievalQuery: { type: 'TEXT', text: 'What are the installation steps for the product' },
});

for (const r of resp.data.retrievalResults) {
  console.log(`[${r.score.toFixed(4)}] ${r.content.slice(0, 80)}...`);
}

API

Call Retrieve to perform retrieval. For the complete request fields, response fields, and filter operator descriptions, see Retrieve Knowledge API.

The retrieval text text can be up to 128 characters or Chinese characters. If exceeded, an error will be reported. If you have business requirements, please submit a ticket or join the Tablestore technical exchange DingTalk group 36165029092 and contact technical support.
Filter fields must be defined as metadata when creating the knowledge base; otherwise, the filter conditions will not take effect.
The k of RRF must be greater than 0; otherwise, a VALIDATION_ERROR will be reported.
Documents in Pending or Indexing status cannot be retrieved. You must wait until the status becomes Completed.
After a knowledge base has subspaces enabled, you must pass subspace; otherwise, an error will be reported.

Retrieval Tuning

numberOfResults Parameter Relationships

There are three layers of numberOfResults in the retrieval process. Understanding their relationships is the key to tuning:

denseVectorSearchConfiguration.numberOfResults = N1  ← Vector retrieval recall count
fullTextSearchConfiguration.numberOfResults          = N2  ← Full-text retrieval recall count
rerankingConfiguration.numberOfResults               = N3  ← Final return count after Rerank

N1 and N2 determine the size of the candidate pool. A larger value means a higher recall rate but also higher computational cost.
N3 determines the number of final returned results. Typically, N3 < N1 and N3 < N2.
Recommended starting configuration: N1 = N2 = 20, N3 = 5--10. Adjust gradually based on actual results.

Retrieval Type Selection

Scenario	Recommended retrieval type	Description
Ask questions in natural language	`DENSE_VECTOR` + `FULL_TEXT`	Vector captures semantics, full-text ensures keyword hits
Enter exact keywords or identifiers	Prioritize `FULL_TEXT`	Vector retrieval is not sensitive to exact matching
Pure semantic understanding scenarios	Prioritize `DENSE_VECTOR`	For example, "how to install" matches "deployment steps"

Metadata Filter Usage Recommendations

Filter narrows the candidate range before retrieval, improving both retrieval accuracy and performance.
Filter fields must be defined as metadata when creating the knowledge base and cannot be added at runtime.
For date range filtering, use the date type instead of string type to support range comparison operators.