Knowledge base management (create, update, query, delete) - Tablestore

Create a knowledge base

Call create_knowledge_base to create a knowledge base. The system automatically creates the corresponding Document table and Chunk table in Tablestore.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	(Required) The unique name of the knowledge base. Must be 1 to 64 characters long, start with a letter, and contain only letters, numbers, and underscores.
`description`	string	The description of the knowledge base. The maximum size is 4 KB.
`subspace`	boolean	Specifies whether to enable subspace multi-tenancy. For more information, see Subspace multi-tenancy. Default value: `false`. If enabled, you must specify the `subspace` field for all document operations and retrieval requests. This parameter cannot be modified after creation.
`tags`	list<string>	A list of tags. The total size cannot exceed 4 KB.
`metadata`	list<object>	Metadata field definitions. See the following section for details.
`embeddingConfiguration`	object	Embedding configuration. If not specified, the system defaults to the Model Studio `text-embedding-v4` model with 1024 dimensions. This parameter cannot be changed after creation.
`retrievalConfiguration`	object	Default retrieval configuration. `Retrieve` API calls use these settings unless overridden per request. You can update this configuration later by calling `update_knowledge_base`.

Metadata field definitions

Each element contains a name (field name) and type (field type).

Item	Description
Supported types	`string`, `long`, `double`, `boolean`, `date`, `string_list`, `long_list`, `double_list`, `boolean_list`, and `date_list` Note The `date` type supports the following formats: `yyyy-MM-dd`, `yyyy-MM-dd HH:mm:ss`, `yyyy-MM-dd HH:mm:ss.SSS`, `yyyyMMdd HHmmss`, and `yyyy-MM-dd'T'HH:mm:ss`.
Field name	Maximum length: 128 characters. The name cannot contain a period (`.`). To request a higher limit, submit a ticket or contact technical support through the Tablestore support group (ID: 36165029092).
Number of fields	Maximum of 200 fields. To request a higher limit, submit a ticket or contact technical support through the Tablestore support group (ID: 36165029092).
Reserved fields	`_uid`, `_id`, `_type`, `_all`, `_parent`, `_routing`, `_index`, `_size`, `_timestamp`, `_ttl`, and `_score`.

Important

Metadata field definitions cannot be added or deleted after the knowledge base is created. Before creation, identify all dimensions you might need for filtering and define them.

Embedding configuration

Parameter	Type	Description
`provider`	string	Model provider. Default value: `bailian` (built-in Model Studio models). `custom` is also supported.
`model`	string	Model name. Default value: `text-embedding-v4`. Model Studio also supports `text-embedding-v3`.
`dimension`	int	Vector dimension. Default value: 1024.
`apiKey`	string	Required only if `provider` is set to `custom`.
`url`	string	Required only if `provider` is set to `custom`. The URL must be registered with Tablestore in advance.

Retrieval configuration

Parameter	Type	Description
`searchType`	list<string>	Default retrieval type: `["DENSE_VECTOR", "FULL_TEXT"]`.
`denseVectorSearchConfiguration.numberOfResults`	int	Number of results to return from vector search. Default value: 20.
`fullTextSearchConfiguration.numberOfResults`	int	Number of results to return from full-text search. Default value: 20.
`rerankingConfiguration.type`	string	Rerank type: `RRF`, `WEIGHT`, or `MODEL`. Default value: `WEIGHT`.
`rerankingConfiguration.numberOfResults`	int	Number of results to return after reranking. Default value: 20.
`weightConfiguration.denseVectorSearchWeight`	double	Weight for vector search results. Default value: 0.7.
`weightConfiguration.fullTextSearchWeight`	double	Weight for full-text search results. Default value: 0.3.
`rrfConfiguration.denseVectorSearchWeight`	double	Weight for vector search in RRF mode. Default value: 1.0.
`rrfConfiguration.fullTextSearchWeight`	double	Weight for full-text search in RRF mode. Default value: 1.0.
`rrfConfiguration.k`	int	`k` parameter for the RRF algorithm. Default value: 60. Must be greater than 0.
`modelConfiguration.provider`	string	Rerank model provider. Default value: `bailian` (Model Studio). This is the only supported provider.
`modelConfiguration.model`	string	Rerank model name. Default value: `gte-rerank-v2`. In the Asia Pacific SE 1 (Singapore) region, the default is `qwen3-rerank`.

For details about retrieval configurations, see Retrieval and reranking.

Code examples

The following examples show how to create a knowledge base.

Minimal example

Creates a knowledge base with default settings: Model Studio text-embedding-v4 model (1024 dimensions) for embeddings, hybrid search (vector + full-text) for retrieval, and weighted fusion (vector: 0.7, full-text: 0.3) for reranking.

client.create_knowledge_base({
    "knowledgeBaseName": "product_docs_kb"
})

Complete example

Creates a knowledge base with custom embedding model, retrieval strategy, and metadata fields:

client.create_knowledge_base({
    "knowledgeBaseName": "product_docs_kb",
    "description": "Product documentation knowledge base",
    "subspace": True,
    "tags": ["Product", "Documentation"],
    "metadata": [
        {"name": "author", "type": "string"},
        {"name": "category", "type": "string"},
        {"name": "publish_date", "type": "date"}
    ],
    "embeddingConfiguration": {
        "provider": "bailian",
        "model": "text-embedding-v4",
        "dimension": 1024
    },
    "retrievalConfiguration": {
        "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
        "denseVectorSearchConfiguration": {"numberOfResults": 10},
        "fullTextSearchConfiguration": {"numberOfResults": 10},
        "rerankingConfiguration": {
            "type": "WEIGHT",
            "numberOfResults": 5,
            "weightConfiguration": {
                "denseVectorSearchWeight": 0.7,
                "fullTextSearchWeight": 0.3
            }
        }
    }
})

Response

Successful response:

{"code": "SUCCESS", "data": {}, "message": "succeed"}

Error response example:

{
  "code": "INVALID_PARAMETER",
  "message": "Unknown field type: strings, supported types: string, long, double, boolean, date, string_list, long_list, double_list, boolean_list, date_list"
}

Usage notes

embeddingConfiguration cannot be changed after creation. To use a different embedding model, delete and recreate the knowledge base.
metadata field definitions cannot be added or removed after creation.
subspace setting cannot be changed after creation.
A metadata field name cannot contain a period (.) or use a reserved field name. A misspelled field type causes an error.

Update a knowledge base

Call update_knowledge_base to update the description, tags, or retrieval configuration of an existing knowledge base.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	The name of the knowledge base (Required).
`description`	string	The new description for the knowledge base. The maximum size is 4 KB.
`tags`	list<string>	The new list of tags.
`retrievalConfiguration`	object	The new default retrieval configuration.

Note

At least one of the following parameters is required: description, tags, or retrievalConfiguration. Otherwise, an error is returned.

Code example

client.update_knowledge_base({
    "knowledgeBaseName": "product_docs_kb",
    "description": "Updated description",
    "tags": ["Live"],
    "retrievalConfiguration": {
        "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
        "rerankingConfiguration": {
            "type": "RRF",
            "numberOfResults": 10,
            "rrfConfiguration": {
                "denseVectorSearchWeight": 0.7,
                "fullTextSearchWeight": 0.3,
                "k": 60
            }
        }
    }
})

Usage notes

After you update retrievalConfiguration, the new settings apply to all subsequent Retrieve requests that do not specify their own configuration.
embeddingConfiguration and metadata cannot be modified through this API.

Describe a knowledge base

Call describe_knowledge_base to retrieve the full configuration of a knowledge base.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	The name of the knowledge base (Required).

Code example

resp = client.describe_knowledge_base({
    "knowledgeBaseName": "product_docs_kb"
})

data = resp["data"]
print(f"Name: {data['knowledgeBaseName']}")
print(f"Embedding: {data['embeddingConfiguration']}")
print(f"Retrieval Configuration: {data['retrievalConfiguration']}")

Response

Response fields

Field	Type	Description
`knowledgeBaseName`	string	The name of the knowledge base.
`description`	string	The description of the knowledge base.
`tags`	list<string>	The list of tags.
`subspace`	boolean	Whether subspace multi-tenancy is enabled.
`createdAt`	int	Creation timestamp, in milliseconds.
`updatedAt`	int	Last update timestamp, in milliseconds.
`metadata`	list<object>	Metadata field definitions.
`embeddingConfiguration`	object	The embedding configuration.
`retrievalConfiguration`	object	The retrieval configuration.

Response example

{
  "code": "SUCCESS",
  "data": {
    "knowledgeBaseName": "product_docs_kb",
    "description": "Product documentation knowledge base",
    "tags": ["Product", "Documentation"],
    "subspace": true,
    "metadata": [{"name": "author", "type": "string"}],
    "createdAt": 1774494642525,
    "updatedAt": 1774494642525,
    "embeddingConfiguration": {
      "provider": "bailian",
      "model": "text-embedding-v4",
      "dimension": 1024
    },
    "retrievalConfiguration": {
      "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
      "denseVectorSearchConfiguration": {"numberOfResults": 20},
      "fullTextSearchConfiguration": {"numberOfResults": 20},
      "rerankingConfiguration": {
        "type": "WEIGHT",
        "numberOfResults": 20,
        "weightConfiguration": {
          "denseVectorSearchWeight": 0.7,
          "fullTextSearchWeight": 0.3
        }
      }
    }
  },
  "message": "succeed"
}

List knowledge bases

Call list_knowledge_base to retrieve a paginated list of all knowledge bases in the current project.

Request parameters

Parameter	Type	Description
`maxResults`	int	Maximum number of results to return per page. Default value: 10. Maximum value: 100.
`nextToken`	string	Pagination token for the next page. Omit for the first request.

Code example

# Retrieve the first page
resp = client.list_knowledge_base({"maxResults": 10})

for kb in resp["data"]["knowledgeBases"]:
    print(f"{kb['knowledgeBaseName']} - {kb.get('description', '')}")

# Paginate to the next page
next_token = resp["data"].get("nextToken")
if next_token:
    resp = client.list_knowledge_base({
        "maxResults": 10,
        "nextToken": next_token
    })

Response

Field	Type	Description
`knowledgeBases`	list<object>	A list of knowledge bases. Each item contains `knowledgeBaseName`, `description`, `subspace`, `tags`, `createdAt`, and `updatedAt`.
`nextToken`	string	Pagination token. An empty or null value indicates no more results.

Usage notes

maxResults has a maximum value of 100. Values greater than 100 return an INVALID_PARAMETER error.

Delete a knowledge base

Call delete_knowledge_base to delete a knowledge base.

Important

This operation is irreversible. Deleting a knowledge base also removes all associated document and chunk data.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	The name of the knowledge base (Required).

Code example

client.delete_knowledge_base({
    "knowledgeBaseName": "product_docs_kb"
})

Response

Successful response:

{"code": "SUCCESS", "data": {}, "message": "succeed"}

Error response example:

{"code": "NOT_FOUND", "message": "KnowledgeBaseName:[product_docs_kb] not found"}