All Products
Search

This Product

    Tablestore:Manage knowledge chunks

    Document Center

    Tablestore:Manage knowledge chunks

    Last Updated:Oct 21, 2026

    A knowledge base in Agent Storage divides each imported document into knowledge chunks. Each chunk has its own ID, title, content, type, and retrievable status. View and update knowledge chunks in the Agent Storage console, through an SDK, or by calling an API operation.

    Prerequisites

    • A knowledge base has been created and documents have been imported into it. You can view and edit chunks only for documents whose status is Completed.

    • You have the docId of the document that contains the target chunks. Chunk operations locate chunks through the docId of their parent document.

    • If you call the API or use an SDK, you have an API key, an endpoint, and an instance name. Replace the <your-api-key>, <instance>, <region>, and <instance-name> placeholders in the examples with your actual values.

    • The Agent Storage SDK for your language installed: the tablestore_agent_storage package for Python or the @tablestore/agent-storage package for TypeScript.

    • If the knowledge base has a subspace enabled, you must specify subspace for chunk operations.

    View chunks

    List the chunks of a specified document with a paged query. The response includes the chunk ID, content, title, type, and retrievable status of each chunk.

    Console

    1. Log on to the Agent Storage console.

    2. In the Document management list, click View chunks in the Actions column of the target document.

      The chunk list dialog box opens. Each chunk displays its type, ID, content, retrievable status, and creation and update times.

    SDK

    Python

    The following example lists up to five chunks of a document and prints the ID, status, and a content preview of each chunk:

    from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

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

    TypeScript

    The following example lists up to five chunks of a document and prints the ID, status, and a content preview of each chunk:

    import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.listChunks({
  knowledgeBaseName: 'product_docs_kb',
  docId: 'fc6ed97f-...',
  maxResults: 5,
});
for (const chunk of resp.data.chunkDetails) {
  console.log(`[Chunk ${chunk.chunkId}] (${chunk.status}) ${chunk.content.slice(0, 80)}...`);
}

    API

    Call ListChunks to list the chunks of a document. For the complete field descriptions, see ListChunks API.

    Update chunks

    Update the title, content, or status of chunks in batches. Each request can update up to 10 chunks.

    • Retrievable status — After you set the status of a chunk to inactive, the chunk does not appear in Retrieve results. You can use this to temporarily exclude inaccurate content without deleting the entire document.

    • Result verification — An HTTP 200 response with code: SUCCESS does not mean that all chunks were updated successfully. Check the updateStatus of each chunk in updateDetails individually.

    • Field limits — title supports up to 100 tokens, and content supports up to 320 tokens.

    Console

    1. Log on to the Agent Storage console.

    2. In the Document management list, click View chunks in the Actions column of the target document.

    3. In the chunk list, click Edit for the target chunk.

    4. Modify the title and content, and then save the changes.

      To temporarily exclude a chunk, toggle its retrievable status.

    SDK

    Python

    Modify the title and content of a chunk:

    from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

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

for detail in resp["data"]["updateDetails"]:
    print(f"chunk {detail['chunkId']}: {detail['updateStatus']}")

    Temporarily exclude an inaccurate chunk (make it non-retrievable):

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

    Check the updateStatus of each entry in updateDetails to confirm that the chunk was excluded.

    TypeScript

    Modify the title and content of a chunk:

    import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.updateChunks({
  knowledgeBaseName: 'product_docs_kb',
  chunks: [
    {
      docId: 'fc6ed97f-...',
      chunkId: 1,
      title: 'Updated title',
      content: 'Updated content',
    },
  ],
});

for (const detail of resp.data.updateDetails) {
  console.log(`chunk ${detail.chunkId}: ${detail.updateStatus}`);
}

    Temporarily exclude an inaccurate chunk (make it non-retrievable):

    const excludeResp = await client.updateChunks({
  knowledgeBaseName: 'product_docs_kb',
  chunks: [
    {
      docId: 'fc6ed97f-...',
      chunkId: 0,
      status: 'inactive',
    },
  ],
});

    API

    Call UpdateChunks to update chunks. For the complete field descriptions, see UpdateChunks API.

    References