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" means the upload task was accepted, not that indexing finished. The document can only be retrieved after its status reaches Completed.

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

• Use a supported metadata date format such as yyyy-MM-dd HH:mm:ss. Unsupported formats cause a failed document status.

Check indexing status

Document upload is asynchronous — documents must finish processing before they become searchable. Use polling with exponential backoff to check indexing status.

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)

Processing time depends on file size, type, and count. Small files typically complete in seconds; 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 full replacements. To update a single field, 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.

• Limits: metadata size cannot exceed 4 KB; maximum 200 fields.

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

As with AddDocuments, check the status of each document in documentDetails individually.