View and update document chunks (ListChunks, UpdateChunks) - Tablestore

After a document is uploaded, the system automatically splits it into chunks. Each chunk stores vector data and the original text, and serves as the smallest unit for retrieval. Use the following APIs to view and adjust chunk content.

View chunks

Call list_chunks to retrieve a paginated list of chunks for 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	The maximum number of results to return. The default is 10, and the maximum is 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	The subspace to which the chunk belongs.
`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	The type of the chunk, such as `TEXT`.
`chunkDetails[].status`	string	The status can be `active` (retrievable) or `inactive` (not retrievable).
`chunkDetails[].docId`	string	The ID of the document to which the chunk belongs.
`chunkDetails[].ossKey`	string	The OSS path of the document to which the chunk belongs.
`chunkDetails[].createdAt`	int	The creation timestamp.
`chunkDetails[].updatedAt`	int	The update timestamp.
`nextToken`	string	The next token for pagination. If this field is empty, it indicates the last page of results.

Update chunks

Call update_chunks to update the title, content, or status of multiple chunks in a batch.

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>	A list of chunks to update. Required. You can update a maximum of 10 chunks per request. Note To request an increase to this limit, submit a ticket or join the Tablestore technical support DingTalk 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	The new title for the chunk.
`chunks[].content`	string	The new content for the chunk.
`chunks[].status`	string	The new status for the chunk: `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"
        }
    ]
})

Block an inaccurate chunk by setting its status to inactive:

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	The status of the update operation. Valid values are `succeed` or `failed`.
`updateDetails[].failureReason`	string	The reason for the failure. This parameter is returned only when the status is `failed`.

Usage notes

After you set the status of a chunk to inactive, it no longer appears in retrieval results. You can use this feature to temporarily block inaccurate content without deleting the entire document.