Tablestore:Document management

Request parameters

Code examples

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

resp = client.add_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "ossKey": "oss://example-bucket/docs/product_manual.pdf",
            "metadata": {"author": "Jane Doe"}
        }
    ]
})

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

Response

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

{
  "code": "SUCCESS",
  "data": {
    "documentDetails": [
      {"status": "failed", "failureReason": "Metadata field 'date' date string format is not supported", "ossKey": "oss://..."},
      {"status": "succeed", "ossKey": "oss://...", "docId": "940f2c5c-..."}
    ]
  },
  "message": "succeed"
}

Usage notes

• A 200 OK HTTP response with code: SUCCESS does not guarantee that all documents were processed successfully. You must check the status field for each document in the documentDetails array.

• status: "succeed" indicates that the upload task is received, not that indexing is complete. The document can be retrieved only after the document status changes to Completed.

• If subspace is enabled for the knowledge base, you must pass the subspace parameter. Otherwise, an INVALID_PARAMETER error is returned.

• You must use a supported metadata date format, such as yyyy-MM-dd HH:mm:ss, because an unsupported format will result in a failed document status.

Check indexing status

Document upload is an asynchronous process. After a document is uploaded, it must be processed before it can be searched. We recommend using a polling strategy with exponential backoff to check if indexing is complete.

import time

def wait_for_document(client, kb_name, doc_id, max_interval=30):
    """Polls the document status with exponential backoff until indexing is 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. Number of chunks: {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)

The processing time depends on the size, type, and number of files. Small files are typically processed in a few seconds, while large files or batch imports may take several minutes.

Request parameters

Code example

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

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

Response

Usage notes

If the same ossKey is created, deleted, and then created again, get_document may return multiple records, including historical records. To identify the valid document, check the status field and use the record with a Completed status.

Request parameters

Code example

resp = client.list_documents({
    "knowledgeBaseName": "product_docs_kb",
    "maxResults": 20
})

for doc in resp["data"]["documentDetails"]:
    print(f"[{doc['status']}] {doc['ossKey']} (Number of chunks: {doc.get('chunkNum', '-')})")

Usage notes

The subspace parameter supports a list of up to 10 values. If you exceed this limit, an error is returned.

Request parameters

Code example

resp = client.update_document({
    "knowledgeBaseName": "product_docs_kb",
    "docId": "fc6ed97f-...",
    "metadata": {"author": "Jane Doe", "category": "Technical Docs", "version": 2}
})

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

Response

Usage notes

• Metadata updates are overwrite operations. The new metadata you provide completely replaces the existing metadata. If you only want to update a single field, you must include all other existing fields in the request.

• Passing "metadata": null will clear all metadata.

• If the metadata field is not specified, the original value is retained.

• Limitations: The total size of the metadata (keys and values) cannot exceed 4 KB. The maximum number of fields is 200.

Request parameters

Code example

resp = client.delete_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {"docId": "fc6ed97f-..."},
        {"ossKey": "oss://example-bucket/docs/faq.docx"}
    ]
})

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

Usage notes

Similar to AddDocuments, the deletion result also requires you to individually check the status of each document in documentDetails.