Knowledge Storage HTTP JSON API reference-Tablestore(Tablestore)-阿里云帮助中心

Call Knowledge Storage directly through HTTP JSON APIs, covering knowledge base management, document management, retrieval, and chunk management. Use these APIs for custom integration without an SDK.

Knowledge base management

CreateKnowledgeBase

Create a knowledge base. Tablestore automatically creates the corresponding Document table, Chunk table, and index table.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	Knowledge base name (required). Must start with a letter and contain only letters, digits, and underscores. Length: 1-64 characters. Must be unique
`description`	string	Knowledge base description. Maximum 4 KB
`subspace`	boolean	Whether to enable subspaces. Defaults to false. When enabled, all document operations and retrievals must specify the subspace field. Cannot be changed after creation
`tags`	list<string>	Tag list. Total length cannot exceed 4 KB
`metadata`	list<object>	Metadata field definitions. See the following section for details
`embeddingConfiguration`	object	Embedding configuration. Cannot be changed after creation. If not specified, the system uses Alibaba Cloud Model Studio `text-embedding-v4` (1024 dimensions) by default
`retrievalConfiguration`	object	Default retrieval configuration. Used when the Retrieve API is called without a configuration. Can be updated through UpdateKnowledgeBase after creation

Metadata field definitions

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

Item	Description
Supported types	`string`, `long`, `double`, `boolean`, `date`, `string_list`, `long_list`, `double_list`, `boolean_list`, `date_list`
Field name	Maximum 128 characters. Cannot contain `.`
Field count	Maximum 200 fields
Reserved fields	`_uid`, `_id`, `_type`, `_all`, `_parent`, `_routing`, `_index`, `_size`, `_timestamp`, `_ttl`, `_score`

Important

Metadata field definitions cannot be added or removed after creation. Identify all dimensions that you may need for filtering retrieval results, and define them all at once when you create the knowledge base.

embeddingConfiguration

Parameter	Type	Description
`provider`	string	Model provider. Defaults to `bailian` (Alibaba Cloud Model Studio built-in). Also supports `custom`
`model`	string	Model name. Defaults to `text-embedding-v4`. Model Studio also supports `text-embedding-v3`
`dimension`	int	Vector dimension. Defaults to 1024
`apiKey`	string	Required only for `custom` mode
`url`	string	Required only for `custom` mode. Contact Tablestore support to register the URL before use

retrievalConfiguration

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

For the complete retrieval configuration reference, see Retrieve and rerank.

Request example

{
  "knowledgeBaseName": "product_docs_kb",
  "description": "Product documentation knowledge base",
  "subspace": true,
  "tags": ["Product", "Documentation"],
  "metadata": [
    {"name": "author", "type": "string"},
    {"name": "date", "type": "date"},
    {"name": "score", "type": "double"}
  ],
  "embeddingConfiguration": {
    "provider": "bailian",
    "model": "text-embedding-v4",
    "dimension": 1024
  },
  "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
      }
    }
  }
}

Response example

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

UpdateKnowledgeBase

Update the description, tags, or retrieval configuration of a knowledge base. At least one of description, tags, or retrievalConfiguration must be specified.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	Knowledge base name (required)
`description`	string	Updated description. Maximum 4 KB
`tags`	list<string>	Updated tags
`retrievalConfiguration`	object	Updated default retrieval configuration

Note

At least one of description, tags, or retrievalConfiguration must be specified. Otherwise, an error is returned.

Request example

{
  "knowledgeBaseName": "product_docs_kb",
  "description": "Updated description",
  "tags": ["production"]
}

Response example

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

DescribeKnowledgeBase

Query the full configuration of a specified knowledge base.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	Knowledge base name (required)

Response fields

Field	Type	Description
`knowledgeBaseName`	string	Knowledge base name
`description`	string	Knowledge base description
`tags`	list<string>	Tag list
`subspace`	boolean	Whether subspaces are enabled
`createdAt`	int	Creation timestamp in milliseconds
`updatedAt`	int	Last update timestamp in milliseconds
`metadata`	list<object>	Metadata field definitions
`embeddingConfiguration`	object	Embedding configuration
`retrievalConfiguration`	object	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"
}

ListKnowledgeBase

List all knowledge bases in the current project with pagination.

Request parameters

Parameter	Type	Description
`maxResults`	int	Number of results to return. Defaults to 10. Maximum 100
`nextToken`	string	Pagination token. Do not specify for the first request

Response fields

Field	Type	Description
`knowledgeBases`	list<object>	List of knowledge bases. Each item contains `knowledgeBaseName`, `description`, `subspace`, `tags`, `createdAt`, and `updatedAt`
`nextToken`	string	Pagination token. Empty when no more pages remain

Request example

{"maxResults": 10}

DeleteKnowledgeBase

Delete a specified knowledge base along with all its documents and chunks.

Important

This operation is irreversible. Deleting a knowledge base permanently removes all documents and chunks within it.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	Knowledge base name (required)

Request example

{"knowledgeBaseName": "product_docs_kb"}

Document management

AddDocuments

Import documents into a knowledge base. Tablestore automatically parses, chunks, vectorizes, and indexes the documents. Uploading a document with a duplicate ossKey overwrites the existing document.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	Knowledge base name (required)
`subspace`	string	Subspace name. Maximum 128 characters. Required when subspaces are enabled
`documents`	list<object>	Document list (required). Maximum 10 documents per request
`documents[].filePath`	string	Local file path. Required for upload_documents
`documents[].ossKey`	string	OSS file or directory path. Length: 1-256. Required for add_documents
`documents[].metadata`	object	Document metadata. Must match the metadata schema defined in the knowledge base
`documents[].inclusionFilters`	list<string>	Inclusion filters. Support leading and trailing `` wildcards (for example, `.pdf`). Used for OSS directory scanning
`documents[].exclusionFilters`	list<string>	Exclusion filters. Support leading and trailing `` wildcards (for example, `draft*`)

Response fields

Field	Type	Description
`documentDetails`	list<object>	Processing result for each document
`documentDetails[].docId`	string	Document ID
`documentDetails[].ossKey`	string	Document OSS path
`documentDetails[].status`	string	`succeed` or `failed`
`documentDetails[].failureReason`	string	Failure reason (only when status is failed)

Request example

{
  "knowledgeBaseName": "product_docs_kb",
  "subspace": "default",
  "documents": [
    {
      "ossKey": "oss://example-bucket/docs/manual.pdf",
      "metadata": {"author": "Zhang San", "date": "2026-01-22 10:00:59"}
    }
  ]
}

Response example

{
  "code": "SUCCESS",
  "data": {
    "documentDetails": [
      {"docId": "fc6ed97f-...", "status": "succeed", "ossKey": "oss://example-bucket/docs/manual.pdf"}
    ]
  },
  "message": "succeed"
}

Note

An HTTP 200 response with code: SUCCESS does not mean all documents were processed successfully. Check the status field in each item of documentDetails. A status: "succeed" indicates the upload task was accepted, not that indexing is complete.

GetDocument

Query detailed information about a specified document.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	Knowledge base name (required)
`subspace`	string	Subspace name. Required when subspaces are enabled
`docId`	string	Document ID. Specify either this or `ossKey`
`ossKey`	string	OSS file path. Specify either this or `docId`

Response fields

Field	Type	Description
`docId`	string	Document ID
`ossKey`	string	OSS path
`subspace`	string	Subspace
`chunkNum`	int	Number of chunks
`status`	string	Document status: `Pending`/`Indexing`/`Completed`/`Failed`/`Deleting`
`createdAt`	int	Creation timestamp
`updatedAt`	int	Last update timestamp
`eTag`	string	Document eTag
`failedDetails`	string	Failure reason (only when status is Failed)
`metadata`	object	Document metadata

ListDocuments

List documents in a knowledge base with pagination.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	Knowledge base name (required)
`subspace`	list<string>	Subspace list. Maximum 10 entries. Required when subspaces are enabled
`maxResults`	int	Number of results to return. Defaults to 10. Maximum 1000
`nextToken`	string	Pagination token

UpdateDocument

Update the metadata of a specified document. Only documents with Completed status can be updated.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	Knowledge base name (required)
`subspace`	string	Subspace name. Required when subspaces are enabled
`ossKey`	string	Document OSS path. Specify either this or `docId`
`docId`	string	Document ID. Specify either this or `ossKey`
`metadata`	map	New metadata (required)

Response fields

Field	Type	Description
`docId`	string	Document ID
`ossKey`	string	OSS path
`updatedAt`	long	Last update timestamp
`updateStatus`	string	`NO_OP` or `UPDATED`

Note

Metadata updates are full replacements. The provided metadata completely replaces the existing values. To update a single field, include all fields in the request. Setting "metadata": null clears all metadata.

DeleteDocuments

Delete specified documents and all their chunks.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	Knowledge base name (required)
`subspace`	string	Subspace name. Required when subspaces are enabled
`documents`	list<object>	List of documents to delete (required)
`documents[].docId`	string	Document ID. Specify either this or `ossKey`
`documents[].ossKey`	string	OSS path. Specify either this or `docId`

Retrieval

Retrieve

Perform semantic retrieval in a knowledge base. Returns a list of chunks most relevant to the query text.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	Knowledge base name (required)
`subspace`	list<string>	Subspace list. Maximum 32 entries. Required when subspaces are enabled
`retrievalQuery`	object	Retrieval query (required)
`retrievalQuery.type`	string	Query type (required). Currently only `TEXT` is supported
`retrievalQuery.text`	string	Query text (required). Maximum 128 characters
`retrievalConfiguration`	object	Retrieval configuration. If not specified, the knowledge base-level configuration or system defaults are used
`retrievalConfiguration.searchType`	list<string>	Retrieval types
`retrievalConfiguration.denseVectorSearchConfiguration.numberOfResults`	int	Number of results from vector search. Maximum 100
`retrievalConfiguration.fullTextSearchConfiguration.numberOfResults`	int	Number of results from full-text search. Maximum 100
`retrievalConfiguration.rerankingConfiguration`	object	Reranking configuration
`retrievalConfiguration.filter`	object	Metadata filter conditions

Retrieval configuration priority

The effective retrieval configuration (retrievalConfiguration) is determined by the following priority order:

Priority	Source	Description
1 (highest)	Retrieve API parameters	The `retrievalConfiguration` passed in the current request. Applies only to this request
2	Knowledge base-level configuration	Set when the knowledge base is created. Can be updated through UpdateKnowledgeBase
3 (lowest)	System defaults	Hybrid search with vector + full-text, WEIGHT fusion (vector 0.7 : full-text 0.3), returns 20 results

The simplest retrieval request only requires knowledgeBaseName and retrievalQuery. All other parameters use the knowledge base configuration or defaults.

Supported filter operators

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

Logical combination operators

Operator	Description
`andAll`	All conditions must be met
`orAll`	At least one condition must be met
`notAll`	None of the conditions are met

andAll, orAll, and notAll support nesting, which allows you to build complex filter logic.

Response fields

Field	Type	Description
`retrievalResults`	list<object>	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. Higher values indicate greater relevance
`retrievalResults[].content`	string	Chunk text content
`retrievalResults[].subspace`	string	Subspace that the chunk belongs to
`retrievalResults[].metadata`	object	Document metadata

Request example

{
  "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 example

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

Chunk management

ListChunks

List chunks of a specified document with pagination.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	Knowledge base name (required)
`subspace`	string	Subspace name. Required when subspaces are enabled
`docId`	string	Document ID. Specify either this or `ossKey`
`ossKey`	string	OSS path. Specify either this or `docId`
`maxResults`	int	Number of results to return. Defaults to 10. Maximum 1000
`nextToken`	string	Pagination token

Response fields

Field	Type	Description
`chunkDetails[].subspace`	string	Subspace that the chunk belongs to
`chunkDetails[].chunkId`	int	Chunk ID
`chunkDetails[].content`	string	Chunk content
`chunkDetails[].title`	string	Chunk title
`chunkDetails[].chunkType`	string	Chunk type, such as `TEXT`
`chunkDetails[].status`	string	`active` (searchable) or `inactive` (not searchable)
`chunkDetails[].docId`	string	Parent document ID
`chunkDetails[].ossKey`	string	Parent document OSS path
`chunkDetails[].createdAt`	int	Creation timestamp
`chunkDetails[].updatedAt`	int	Last update timestamp
`nextToken`	string	Pagination token. Empty when no more pages remain

UpdateChunks

Update the title, content, or status of chunks in batches.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	Knowledge base name (required)
`subspace`	string	Subspace name. Required when subspaces are enabled
`chunks`	list<object>	List of chunks to update (required). Maximum 10 chunks per request
`chunks[].docId`	string	Document ID. Specify either this or `ossKey`
`chunks[].ossKey`	string	OSS path. Specify either this or `docId`
`chunks[].chunkId`	int	Chunk ID (required)
`chunks[].title`	string	Updated title. Maximum 100 tokens
`chunks[].content`	string	Updated content. Maximum 320 tokens
`chunks[].status`	string	Updated status: `active` (searchable) or `inactive` (not searchable)

Response fields

Field	Type	Description
`updateDetails[].docId`	string	Document ID
`updateDetails[].ossKey`	string	OSS path
`updateDetails[].chunkId`	int	Chunk ID
`updateDetails[].updateStatus`	string	`succeed` or `failed`
`updateDetails[].failureReason`	string	Failure reason (only when status is failed)

Request example

{
  "knowledgeBaseName": "product_docs_kb",
  "subspace": "default",
  "chunks": [
    {"ossKey": "oss://example-bucket/docs/manual.pdf", "chunkId": 0, "status": "inactive"},
    {"ossKey": "oss://example-bucket/docs/manual.pdf", "chunkId": 1, "title": "Updated title", "content": "Updated content"}
  ]
}

Common error codes

Error code	Meaning	Common causes
`INVALID_PARAMETER`	Parameter validation failed	Field type mismatch, length limit exceeded, or missing required fields
`NOT_FOUND`	Resource not found	Knowledge base name is misspelled or the knowledge base has been deleted
`BAD_REQUEST`	Invalid request format	JSON format is invalid
`VALIDATION_ERROR`	Business validation failed	RRF k value is 0, or retrieval parameters are invalid

Note

For AddDocuments, DeleteDocuments, and UpdateChunks, an HTTP 200 response with code: SUCCESS does not mean all items were processed successfully. Each item has an independent status field that must be checked individually.