Retrieve and rerank

Retrieval configuration precedence

The retrievalConfiguration parameters take effect in the following priority order:

Priority	Source	Description
1 (Highest)	Retrieve API parameters	The `retrievalConfiguration` applies to the current request only.
2	Knowledge base-level configuration	Set at knowledge base creation. Modifiable via the UpdateKnowledgeBase API.
3 (Lowest)	System defaults	Hybrid search (vector + full-text) with WEIGHT fusion (vector 0.7, full-text 0.3), returning 20 results.

A minimal request needs only knowledgeBaseName and retrievalQuery. The system falls back to knowledge base-level or default configuration.

Search types

Type	Description	Use cases
`DENSE_VECTOR`	Semantic similarity search.	Best for natural-language queries where semantic intent matters. For example, "how to install" matches "deployment steps."
`FULL_TEXT`	Keyword-based search.	Best for exact keywords, proper nouns, or identifiers.

Vector retrieval and full-text search are complementary — vectors excel at semantics, full-text at exact matches. Enable both and use Rerank to fuse results.

Rerank strategies

Rerank fuses and reorders vector and full-text results into the final result set.

WEIGHT (weighted fusion)

Applies weighted scores to vector and full-text results. Ideal for fine-grained control over each method's contribution. Recommended as the default.

Configuration parameters:

Parameter	Type	Default	Description
`denseVectorSearchWeight`	double	0.7	Weighting ratio for vector retrieval.
`fullTextSearchWeight`	double	0.3	Weighting ratio for full-text search.

RRF (Reciprocal Rank Fusion)

Fuses results by weighting the reciprocal of each result's rank. Offers stable performance and low latency without a model call.

Configuration parameters:

Parameter	Type	Default	Description
`denseVectorSearchWeight`	double	1.0	Weight for vector retrieval.
`fullTextSearchWeight`	double	1.0	Weight for full-text search.
`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)

Uses a Rerank model (e.g., gte-rerank-v2) to re-rank candidates. Provides the highest ranking quality but adds latency and cost.

Configuration parameters:

Parameter	Type	Default	Description
`provider`	string	`Bailian`	Rerank model provider. Only Model Studio is supported.
`model`	string	`gte-rerank-v2`	Rerank model name.

Choosing a strategy

Scenario	Recommended strategy
Latency-sensitive general use.	RRF
Fine-grained control over vector/full-text ratio.	WEIGHT
Highest ranking quality; tolerates extra latency.	MODEL

Metadata filter

Use the filter parameter to narrow results by metadata conditions. Filter fields must be defined in metadata at knowledge base creation.

Comparison operators

Operator	Symbol	Description	Applicable types
`equals`	=	Equals	All types
`notEquals`	≠	Does not equal	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 matching 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`	Matches a string prefix.	string
`stringContains`	Matches a substring.	string
`listContains`	Checks if a list field contains the specified element.	list

Logical combination operators

Operator	Description
`andAll`	All conditions must be met.
`orAll`	At least one of the conditions must be met.
`notAll`	Not all of the conditions are met.

Nest andAll, orAll, and notAll to build complex filter logic.

Filter examples

Filter 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 for OR logic: filter documents where status is "active" or score > 90.

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

Retrieve API

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	Knowledge base name. Required.
`subspace`	list<string>	Subspace list (max 32). Required if subspaces are enabled.
`retrievalQuery`	object	Retrieval query object. Required.
`retrievalQuery.type`	string	Query type (Required). Only `TEXT` is supported.
`retrievalQuery.text`	string	Query text. Required. Max 128 characters.
`retrievalConfiguration`	object	Retrieval configuration. Falls back to knowledge base-level or system defaults if omitted.
`retrievalConfiguration.searchType`	list<string>	Search types to enable.
`retrievalConfiguration.denseVectorSearchConfiguration.numberOfResults`	int	Vector retrieval result count. Max: 100.
`retrievalConfiguration.fullTextSearchConfiguration.numberOfResults`	int	Full-text search result count. Max: 100.
`retrievalConfiguration.rerankingConfiguration`	object	Rerank configuration.
`retrievalConfiguration.filter`	object	Metadata filter conditions.

Response

Response fields

Field	Type	Description
`retrievalResults`	list<object>	Retrieval results, sorted by relevance score (descending).
`retrievalResults[].docId`	string	Document ID of the chunk's parent.
`retrievalResults[].chunkId`	int	Chunk ID.
`retrievalResults[].ossKey`	string	OSS path of the source document.
`retrievalResults[].score`	float	Relevance score. Higher means better match.
`retrievalResults[].content`	string	Original chunk content.
`retrievalResults[].subspace`	string	Subspace of the chunk.
`retrievalResults[].metadata`	object	Document metadata.

Code examples

Minimal example

No retrieval parameters set — the system uses knowledge base-level or default configuration:

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

Overrides knowledge base-level configuration with request-level parameters:

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 Documentation"]}}
            ]
        }
    }
})

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

Using model classes

Use model classes for IDE code completion and type checking:

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

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
    )
))

Sample response

{
  "code": "SUCCESS",
  "data": {
    "retrievalResults": [
      {
        "ossKey": "oss://example-bucket/docs/product_manual.pdf",
        "docId": "96fb386e-...",
        "chunkId": 3,
        "subspace": "default",
        "score": 0.85,
        "content": "Step 1: Download the installation package...",
        "metadata": {"author": "John Doe", "category": "Product Documentation"}
      }
    ]
  },
  "message": "succeed"
}

Usage notes

Issue	Description
Query text is too long	`text` accepts up to 128 characters. Longer inputs return an error. Note For specific business needs, submit a support ticket or join the Tablestore technology exchange group (ID: 36165029092).
Filter field is not defined	Filter fields must be defined as metadata at knowledge base creation.
The `k` value for RRF is 0	`k` must be > 0; otherwise a `VALIDATION_ERROR` is returned.
Document indexing is not complete	Documents in `Pending` or `Indexing` status are not retrievable.
`subspace` parameter is missing	Required when subspaces are enabled for the knowledge base.

Performance tuning

numberOfResults parameter relationship

The retrieval pipeline has three numberOfResults layers:

denseVectorSearchConfiguration.numberOfResults = N1  // Number of candidates recalled by vector retrieval
fullTextSearchConfiguration.numberOfResults         = N2  // Number of candidates recalled by full-text search
rerankingConfiguration.numberOfResults           = N3  // Number of final results after Rerank

N1 and N2 set the candidate pool size. Larger values improve recall but increase cost.
N3 sets the final result count. Keep N3 < N1 and N2.
Start with N1=N2=20 and N3 between 5–10. Adjust based on results.

Choosing a search type

Scenario	Recommended search type	Description
Asking questions in natural language	`DENSE_VECTOR` + `FULL_TEXT`	Vectors capture semantic meaning; full-text ensures keyword hits.
Searching with exact keywords or identifiers	Prioritize `FULL_TEXT`	Vectors are less effective for exact matches.
Purely semantic understanding scenarios	Prioritize `DENSE_VECTOR`	E.g., matching "how to install" with "deployment steps."

Using the metadata filter

Filters prune candidates before search, improving accuracy and performance.
Filter fields must be defined as metadata at creation — they cannot be added at runtime.
For date range filtering, use the date type (not string) to enable range operators.