Tablestore:ドキュメント管理

リクエストパラメータ

コード例

resp = client.upload_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "filePath": "/home/user/docs/product_manual.pdf",
            "metadata": {"author": "田中愛", "category": "Product Manual"}
        },
        {
            "filePath": "/home/user/docs/faq.docx",
            "metadata": {"author": "山田太郎", "category": "FAQ"}
        }
    ]
})

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

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

レスポンス

{
  "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"
}

使用上の注意

• 200 OK の HTTP レスポンスに code: SUCCESS が含まれていても、すべてのドキュメントが正常に処理されたことを保証するものではありません。 status 配列内の各ドキュメントの documentDetails フィールドを確認する必要があります。

• status: "succeed" は、アップロードタスクが受け付けられたことを示しますが、インデックス作成が完了したことを意味するものではありません。ドキュメントのステータスが 完了 に変わった後にのみ、ドキュメントを取得できます。

• ナレッジベースでサブスペースが有効になっている場合は、subspace パラメータを渡す必要があります。指定しない場合、INVALID_PARAMETER エラーが返されます。

• サポートされていない形式を使用するとドキュメントのステータスが failed になるため、yyyy-MM-dd HH:mm:ss のようなサポートされているメタデータの日付形式を使用する必要があります。

インデックス作成ステータスの確認

ドキュメントのアップロードは非同期処理です。アップロード後、検索可能になる前に処理が必要です。インデックス作成が完了したかどうかを確認するには、エクスポネンシャルバックオフを使用したポーリング戦略を推奨します。

import time

def wait_for_document(client, kb_name, doc_id, max_interval=30):
    """エクスポネンシャルバックオフでドキュメントのステータスをポーリングし、インデックス作成が完了するまで待機します。"""
    interval = 3
    while True:
        resp = client.get_document({
            "knowledgeBaseName": kb_name,
            "docId": doc_id
        })
        status = resp["data"][0]["status"]
        if status == "完了":
            print(f"インデックス作成が完了しました。チャンク数: {resp['data'][0].get('chunkNum', 'N/A')}")
            return resp
        elif status == "失敗":
            raise Exception(f"インデックス作成が失敗しました: {resp['data'][0].get('failedDetails')}")
        print(f"現在のステータス: {status}、{interval} 秒後に再試行します...")
        time.sleep(interval)
        interval = min(interval * 2, max_interval)

処理時間は、ファイルのサイズ、種類、数によって異なります。小さなファイルは通常数秒で処理されますが、大きなファイルや一括インポートの場合は数分かかることがあります。

リクエストパラメータ

コード例

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

doc = resp["data"][0]
print(f"ステータス: {doc['status']}、チャンク数: {doc.get('chunkNum', 'N/A')}")

レスポンス

使用上の注意

同じ ossKey が作成、削除され、その後再度作成された場合、get_document は履歴レコードを含む複数のレコードを返す可能性があります。有効なドキュメントを特定するには、status フィールドを確認し、ステータスが 完了 のレコードを使用してください。

リクエストパラメータ

コード例

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

for doc in resp["data"]["documentDetails"]:
    print(f"[{doc['status']}] {doc['ossKey']} (チャンク数: {doc.get('chunkNum', '-')})")

使用上の注意

subspace パラメータは、最大 10 個の値のリストをサポートします。この制限を超えた場合、エラーが返されます。

リクエストパラメータ

コード例

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

print(f"更新ステータス: {resp['data']['updateStatus']}")  # UPDATED または NO_OP

レスポンス

使用上の注意

• メタデータの更新は上書き操作です。指定した新しいメタデータが、既存のメタデータを完全に置き換えます。単一のフィールドのみを更新したい場合は、他のすべての既存フィールドもリクエストに含める必要があります。

• "metadata": null を渡すと、すべてのメタデータがクリアされます。

• metadata フィールドを指定しない場合、元の値が保持されます。

• 制限事項： メタデータの合計サイズ (キーと値) は 4 KB を超えることはできません。フィールドの最大数は 200 です。

リクエストパラメータ

コード例

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

# 各ドキュメントの削除結果を確認
for detail in resp["data"]["documentDetails"]:
    print(f"{detail['ossKey']}: {detail['status']}")

使用上の注意

AddDocuments API と同様に、削除結果についても documentDetails 内の各ドキュメントの status を個別に確認する必要があります。