View and update document chunks (ListChunks, UpdateChunks)-Tablestore(Tablestore)-阿里云帮助中心

After you upload a document, the system splits it into chunks. Each chunk stores vector data and the original text as the smallest retrieval unit. Use the following APIs to view and update chunks.

View chunks

Call list_chunks to paginate through chunks of a specified document.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	The name of the knowledge base. Required.
`subspace`	string	The name of the subspace. Required if subspaces are enabled.
`docId`	string	The document ID. Required if `ossKey` is not provided.
`ossKey`	string	The OSS path of the document. Required if `docId` is not provided.
`maxResults`	int	Maximum results to return. Default: 10. Maximum: 1,000.
`nextToken`	string	The next token for pagination.

Code example

resp = client.list_chunks({
    "knowledgeBaseName": "product_docs_kb",
    "docId": "fc6ed97f-...",
    "maxResults": 5
})

for chunk in resp["data"]["chunkDetails"]:
    print(f"[Chunk {chunk['chunkId']}] ({chunk['status']}) {chunk['content'][:80]}...")

Response fields

Parameter	Type	Description
`chunkDetails[].subspace`	string	Subspace of the chunk.
`chunkDetails[].chunkId`	int	The ID of the chunk.
`chunkDetails[].content`	string	The content of the chunk.
`chunkDetails[].title`	string	The title of the chunk.
`chunkDetails[].chunkType`	string	Chunk type, such as `TEXT`.
`chunkDetails[].status`	string	Status: `active` (retrievable) or `inactive` (not retrievable).
`chunkDetails[].docId`	string	ID of the document that contains the chunk.
`chunkDetails[].ossKey`	string	OSS path of the document that contains the chunk.
`chunkDetails[].createdAt`	int	The creation timestamp.
`chunkDetails[].updatedAt`	int	The update timestamp.
`nextToken`	string	Pagination token. Empty if this is the last page.

Update chunks

Call update_chunks to batch-update the title, content, or status of chunks.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	The name of the knowledge base. Required.
`subspace`	string	The name of the subspace. Required if subspaces are enabled.
`chunks`	list<object>	List of chunks to update. Required. Maximum: 10 per request. Note To increase this limit, submit a ticket or join the Tablestore DingTalk support group (ID: 36165029092).
`chunks[].docId`	string	The document ID. Required if `ossKey` is not provided.
`chunks[].ossKey`	string	The OSS path of the document. Required if `docId` is not provided.
`chunks[].chunkId`	int	The ID of the chunk. Required.
`chunks[].title`	string	New chunk title.
`chunks[].content`	string	New chunk content.
`chunks[].status`	string	New status: `active` (retrievable) or `inactive` (not retrievable).

Code examples

Update the content of a chunk:

resp = client.update_chunks({
    "knowledgeBaseName": "product_docs_kb",
    "chunks": [
        {
            "docId": "fc6ed97f-...",
            "chunkId": 1,
            "title": "Updated title",
            "content": "Updated content"
        }
    ]
})

Set a chunk to inactive to block inaccurate content:

resp = client.update_chunks({
    "knowledgeBaseName": "product_docs_kb",
    "chunks": [
        {
            "docId": "fc6ed97f-...",
            "chunkId": 0,
            "status": "inactive"
        }
    ]
})

Response fields

Parameter	Type	Description
`updateDetails[].docId`	string	The ID of the document.
`updateDetails[].ossKey`	string	The OSS path of the document.
`updateDetails[].chunkId`	int	The ID of the chunk.
`updateDetails[].updateStatus`	string	Update result: `succeed` or `failed`.
`updateDetails[].failureReason`	string	Failure reason. Returned only when the update status is `failed`.

Usage notes

Setting a chunk's status to inactive removes it from retrieval results. Use this to temporarily block inaccurate content without deleting the document.