Tablestore:Document management

Python

from tablestore_agent_storage import AgentStorageClient

# Configure OSS to upload local files. The SDK uploads files to OSS first, then triggers chunking and vectorization.
client = AgentStorageClient(
    access_key_id="<AccessKey ID>",
    access_key_secret="<AccessKey Secret>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
    oss_endpoint="https://oss-<region>.aliyuncs.com",
    oss_bucket_name="<bucket-name>",
)

resp = client.upload_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "filePath": "/home/user/docs/product_manual.pdf",
            "metadata": {"author": "John", "category": "Product documentation"}
        },
        {
            "filePath": "/home/user/docs/faq.docx",
            "metadata": {"author": "Jane", "category": "FAQ"}
        }
    ]
})

for detail in resp["data"]["documentDetails"]:
    print(detail["ossKey"], detail["status"])

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.add_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "ossKey": "oss://example-bucket/docs/product_manual.pdf",
            "metadata": {"author": "John"}
        }
    ]
})

resp = client.add_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "ossKey": "oss://example-bucket/docs/",
            "inclusionFilters": ["*.pdf", "*.docx"],
            "exclusionFilters": ["*draft*"]
        }
    ]
})

TypeScript

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

const client = new NodeAgentStorageClient({
  accessKeyId: '<AccessKey ID>',
  accessKeySecret: '<AccessKey Secret>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
  ossEndpoint: 'https://oss-<region>.aliyuncs.com',
  ossBucketName: '<bucket-name>',
  ossAccessKeyId: '<AccessKey ID>',
  ossAccessKeySecret: '<AccessKey Secret>',
});

const resp = await client.uploadDocuments({
  knowledgeBaseName: 'product_docs_kb',
  documents: [
    {
      filePath: '/home/user/docs/product_manual.pdf',
      metadata: { author: 'John', category: 'Product documentation' },
    },
  ],
});

for (const detail of resp.data.documentDetails) {
  console.log(detail.ossKey, detail.status);
}

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.addDocuments({
  knowledgeBaseName: 'product_docs_kb',
  documents: [
    {
      ossKey: 'oss://example-bucket/docs/product_manual.pdf',
      metadata: { author: 'John' },
    },
  ],
});

const resp = await client.addDocuments({
  knowledgeBaseName: 'product_docs_kb',
  documents: [
    {
      ossKey: 'oss://example-bucket/docs/',
      inclusionFilters: ['*.pdf', '*.docx'],
      exclusionFilters: ['*draft*'],
    },
  ],
});

Python

import time

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>",
)

def wait_for_document(client, kb_name, doc_id, max_interval=30):
    """Poll document status with exponential backoff and wait for indexing to complete."""
    interval = 3
    while True:
        resp = client.get_document({
            "knowledgeBaseName": kb_name,
            "docId": doc_id
        })
        status = resp["data"][0]["status"]
        if status == "Completed":
            print(f"Indexing complete. Chunk count: {resp['data'][0].get('chunkNum', 'N/A')}")
            return resp
        elif status == "Failed":
            raise Exception(f"Indexing failed: {resp['data'][0].get('failedDetails')}")
        print(f"Current status: {status}. Retrying in {interval}s...")
        time.sleep(interval)
        interval = min(interval * 2, max_interval)

wait_for_document(client, "product_docs_kb", "fc6ed97f-...")

TypeScript

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

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

async function waitForDocument(kbName: string, docId: string, maxInterval = 30) {
  let interval = 3;
  while (true) {
    const resp = await client.getDocument({
      knowledgeBaseName: kbName,
      docId,
    });
    const doc = resp.data[0];
    if (doc.status === 'Completed') {
      console.log(`Indexing complete. Chunk count: ${doc.chunkNum ?? 'N/A'}`);
      return resp;
    } else if (doc.status === 'Failed') {
      throw new Error(`Indexing failed: ${doc.failedDetails}`);
    }
    console.log(`Current status: ${doc.status}. Retrying in ${interval}s...`);
    await new Promise((r) => setTimeout(r, interval * 1000));
    interval = Math.min(interval * 2, maxInterval);
  }
}

await waitForDocument('product_docs_kb', 'fc6ed97f-...');

Python

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.get_document({
    "knowledgeBaseName": "product_docs_kb",
    "docId": "fc6ed97f-..."
})

doc = resp["data"][0]
print(f"Status: {doc['status']}, chunk count: {doc.get('chunkNum', 'N/A')}")

TypeScript

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.getDocument({
  knowledgeBaseName: 'product_docs_kb',
  docId: 'fc6ed97f-...',
});

const doc = resp.data[0];
console.log(`Status: ${doc.status}, chunk count: ${doc.chunkNum ?? 'N/A'}`);

Python

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>",
)

# Get the first page
resp = client.list_documents({
    "knowledgeBaseName": "product_docs_kb",
    "maxResults": 20
})
for doc in resp["data"]["documentDetails"]:
    print(f"[{doc['status']}] {doc['ossKey']} (chunk count: {doc.get('chunkNum', '-')})")

# Get the next page
next_token = resp["data"].get("nextToken")
if next_token:
    resp = client.list_documents({
        "knowledgeBaseName": "product_docs_kb",
        "maxResults": 20,
        "nextToken": next_token
    })

TypeScript

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.listDocuments({
  knowledgeBaseName: 'product_docs_kb',
  maxResults: 20,
});
for (const doc of resp.data.documentDetails) {
  console.log(`[${doc.status}] ${doc.ossKey} (chunk count: ${doc.chunkNum ?? '-'})`);
}

Python

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_document({
    "knowledgeBaseName": "product_docs_kb",
    "docId": "fc6ed97f-...",
    "metadata": {"author": "John", "category": "Technical documentation", "version": 2}
})

print(f"Update status: {resp['data']['updateStatus']}")  # UPDATED or NO_OP

TypeScript

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.updateDocument({
  knowledgeBaseName: 'product_docs_kb',
  docId: 'fc6ed97f-...',
  metadata: { author: 'John', category: 'Technical documentation', version: 2 },
});

console.log(`Update status: ${resp.data.updateStatus}`); // UPDATED or NO_OP

Python

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.delete_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {"docId": "fc6ed97f-..."},
        {"ossKey": "oss://example-bucket/docs/faq.docx"}
    ]
})

# Check each deletion result individually
for detail in resp["data"]["documentDetails"]:
    print(f"{detail['ossKey']}: {detail['status']}")

TypeScript

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.deleteDocuments({
  knowledgeBaseName: 'product_docs_kb',
  documents: [
    { docId: 'fc6ed97f-...' },
    { ossKey: 'oss://example-bucket/docs/faq.docx' },
  ],
});

// Check each deletion result individually
for (const detail of resp.data.documentDetails) {
  console.log(`${detail.ossKey}: ${detail.status}`);
}