概觀

文件是 JSON 物件。文件也是您資料的容器、是 IBM® Cloudant® for IBM Cloud® 資料庫的基礎。

如果您使用 IBM Cloudant 服務於 IBM Cloud®，文件的最大大小限制為 1 MB。超過此限制將導致錯誤 413。

IBM Cloudant 採用最終一致性模型來處理資料。若採用最終一致性模型，在某些條件下，可能檢索到較舊的文件內容。例如，當您的應用程式寫入或更新某個文件後，隨即讀取同一個文件時，系統便會檢索較舊的內容。

換言之，您的應用程式將看到文件內容在寫入或更新發生前的狀態。有關此模型的更多資訊，請參閱「一致性」主題。

文件欄位

所有文件必須包含兩個欄位：

除了這兩個必填欄位外，文件通常可包含任何能透過 JSON 描述的內容，但須遵循下列各節所述的若干注意事項

文件識別碼的格式會因資料庫是否進行分區處理而有所不同當資料庫進行分區時，每個文件的分區鍵將作為文件識別碼的一部分進行定義，詳情將於下一節說明

當您使用分區資料庫時，文件 ID 同時指定分區鍵和文件鍵。這些鍵值是透過將文件識別碼分割為兩部分來指定的，兩部分之間以冒號分隔：

$PARTITION_KEY:$DOCUMENT_KEY

文件之間的內容 $PARTITION_KEY 可能相同。該 $DOCUMENT_KEY 在每個分區內必須是唯一的。換言之，整體而言，整個文件 ID 須在資料庫內保持唯一性。文件鍵可能包含更多冒號字元。

對於非分割資料庫，_id 該欄位要麼由您創建，要麼由IBM Cloudant自動產生為 UUID。

如果您選擇指定文件 _id 欄位，則必須限制為不超過 7168 個字元 ( 7k )。

如同分區資料庫，文件識別碼必須在單一資料庫內保持唯一性。

以下劃線字元 (_) 開頭的欄位名稱在中為 IBM Cloudant 保留字元。此規則表示您通常不能使用以下劃線開頭的自訂欄位名稱。例如，欄位 example 將被接受，但欄位 _example 會導致錯誤 doc_validation 訊息。

以下是一個嘗試建立帶有底線前綴欄位的 JSON 文件範例：

{
	"_top_level_field_name": "some data"
}

嘗試建立以下字段時，會看到系統返回的錯誤訊息：

{
	"error": "doc_validation",
	"reason": "Bad special document member: _top_level_field_name"
}

然而，若欄位名稱所指的物件是嵌套於文件內的，則可使用底線作為欄位名稱的前綴。

以下是一個嘗試在物件內部建立帶有底線前綴欄位的 JSON 文件範例：

{
	"another_top_level_field_name": "some data",
	"another_field": {
		"_lower_level_field_name": "some more data"
	}
}

參見建立帶有底線前綴的嵌套欄位時返回的成功訊息範例（節錄）：

{
	"ok": true,
	"id": "2",
	"rev": "1-9ce...8d4"
}

在分散式系統中，請求可能需要一段時間才能完成。採用「法定人數」機制來協助判定請求（例如寫入或讀取操作）何時成功完成

如需進一步了解法定人數設定及其對專用 IBM Cloudant 系統的影響，請聯絡 IBM Cloudant 技術支援部門。

存活時間（TTL）是資料的一項屬性，當經過一段相對時間後，或在絕對時間點到達時，該資料即被視為已過期。資料本身可能會被刪除或移轉至替代（歸檔）位置。

IBM Cloudant 不支援存活時間功能於資料庫內。客戶可透過以下方式實現此功能：使用 [Views] 根據文件的到期時間戳建立索引，並定期查詢該檢視結果以找出需刪除的文件。