本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用文件 作為文件資料庫，Amazon DocumentDB 可讓您輕鬆儲存、查詢和索引 JSON 資料。在 Amazon DocumentDB 中，集合類似於關聯式資料庫中的資料表，但不會在所有文件上強制執行單一結構描述。集合可讓您將類似的文件分組，同時將它們全都保存在同一個資料庫中，而不要求文件的結構一致。 若使用前面各節的範例文件，您可能會有 `reading_material` 和 `office_supplies` 的集合。您的軟體需負責強制執行文件屬於哪一個集合。 以下範例使用 MongoDB API 顯示如何新增、查詢、更新和刪除文件。 **Topics** + [新增文件](#document-database-adding-documents) + [查詢文件](#document-database-queries) + [更新文件](#document-database-updating) + [刪除文件](#document-database-deleting) ## 新增文件 在 Amazon DocumentDB 中，資料庫會在您第一次將文件新增至集合時建立。在此範例中，您在 `test` 資料庫中建立名為 `example` 的集合，這是當您連接到叢集時的預設資料庫。由於集合是在插入第一個文件時隱含建立的，因此集合名稱沒有錯誤檢查。因此，系列名稱中的錯字 (例如，`eexample` 而不是 `example`) 會建立文件，並將文件新增至 `eexample` 集合，而不是預期的集合。錯誤檢查必須由您的應用程式處理。 以下範例使用 MongoDB API 來新增文件。 **Topics** + [新增單一文件](#document-database-adding-documents-single) + [新增多個文件](#document-database-adding-documents-multiple) ### 新增單一文件 若要新增單一文件至集合，請對您要新增至集合中的文件使用 `insertOne( {} )` 操作。 ``` db.example.insertOne( { "Item": "Ruler", "Colors": ["Red","Green","Blue","Clear","Yellow"], "Inventory": { "OnHand": 47, "MinOnHand": 40 }, "UnitPrice": 0.89 } ) ``` 此操作的輸出將會如下所示 (JSON 格式)。 ``` { "acknowledged" : true, "insertedId" : ObjectId("5bedafbcf65ff161707de24f") } ``` ### 新增多個文件 若要新增多個文件至集合，請對您要新增至集合中的文件清單使用 `insertMany( [{},...,{}] )` 操作。雖然這份特定清單中的文件有不同的結構描述，但是全都可以新增至相同的集合。 ``` db.example.insertMany( [ { "Item": "Pen", "Colors": ["Red","Green","Blue","Black"], "Inventory": { "OnHand": 244, "MinOnHand": 72 } }, { "Item": "Poster Paint", "Colors": ["Red","Green","Blue","Black","White"], "Inventory": { "OnHand": 47, "MinOnHand": 50 } }, { "Item": "Spray Paint", "Colors": ["Black","Red","Green","Blue"], "Inventory": { "OnHand": 47, "MinOnHand": 50, "OrderQnty": 36 } } ] ) ``` 此操作的輸出將會如下所示 (JSON 格式)。 ``` { "acknowledged" : true, "insertedIds" : [ ObjectId("5bedb07941ca8d9198f5934c"), ObjectId("5bedb07941ca8d9198f5934d"), ObjectId("5bedb07941ca8d9198f5934e") ] } ``` ## 查詢文件 有時候，您可能需要查詢線上商店的庫存，讓客戶可以查看和購買您銷售的商品。查詢集合相當容易，無論您需要的是集合中的所有文件，或僅需要滿足特定條件的文件。 若要查詢文件，請使用 `find()` 操作。`find()` 命令擁有單一文件參數，負責定義選擇要傳回的文件時所使用的條件。`find()` 輸出的文件格式會是單一行文字且沒有換行。若要將輸出文件格式化，以更方便閱讀，請使用 `find().pretty()`。這個主題的所有範例都使用 `.pretty()` 設定輸出格式。 使用您在上述兩個練習中插入`example`集合的四個文件： `insertOne()`和 `insertMany()`。 **Topics** + [擷取集合中的所有文件](#document-database-queries-all-documents) + [擷取符合欄位值的文件](#document-database-queries-match-criteria) + [擷取符合內嵌文件的文件](#document-database-queries-entire-embedded-document) + [擷取符合內嵌文件中欄位值的文件](#document-database-queries-embeded-document-field) + [擷取符合陣列的文件](#document-database-queries-array-match) + [擷取符合陣列中值的文件](#document-database-queries-array-value-match) + [使用運算子擷取文件](#document-database-query-operators) ### 擷取集合中的所有文件 若要擷取集合中的所有文件，請使用空的查詢文件使用 `find()` 操作。 以下查詢會傳回 `example` 集合中的所有文件。 ``` db.example.find( {} ).pretty() ``` ### 擷取符合欄位值的文件 若要擷取符合某個欄位和值的所有文件，請使用識別要符合的欄位和值的查詢文件使用 `find()` 操作。 使用先前文件，此查詢會傳回所有文件，其中「項目」欄位等於「筆」。 ``` db.example.find( { "Item": "Pen" } ).pretty() ``` ### 擷取符合內嵌文件的文件 若要尋找符合嵌入文件的所有文件，請使用 `find()` 操作，其附帶的查詢文件會指定內嵌文件名稱和該內嵌文件的所有欄位和值。 當符合嵌入文件，文件的內嵌文件必須擁有與查詢相同的名稱。此外，內嵌文件的欄位和值必須符合查詢。 以下查詢只會傳回「Poster Paint」(廣告顏料) 文件。這是因為「Pen」(筆) 的 `OnHand` 和 `MinOnHand` 有不同值，而「Spray Paint」(噴漆) 比查詢文件多一個欄位 (`OrderQnty`)。 ``` db.example.find({"Inventory": { "OnHand": 47, "MinOnHand": 50 } } ).pretty() ``` ### 擷取符合內嵌文件中欄位值的文件 若要尋找符合嵌入文件的所有文件，請使用 `find()` 操作，其附帶的查詢文件會指定內嵌文件名稱和該內嵌文件的所有欄位和值。 鑒於前述文件，以下查詢使用「點表示法」指定內嵌文件和關注欄位。符合這些的任何文件將會傳回，無論內嵌文件中可能有哪些其他欄位。查詢將傳回「廣告顏料」和「噴漆」，因為它們都符合指定的欄位和值。 ``` db.example.find({"Inventory.OnHand": 47, "Inventory.MinOnHand": 50 }).pretty() ``` ### 擷取符合陣列的文件 若要尋找符合陣列的所有文件，請使用 `find()` 操作與您感興趣的陣列名稱，以及在該陣列中的所有值。查詢將傳回所有具有該名稱的文件，其中陣列值與查詢中值及順序相同。 以下查詢只會傳回「筆」，因為「廣告顏料」有額外的顏色 (白色)，而「噴漆」有不同順序的顏色。 ``` db.example.find( { "Colors": ["Red","Green","Blue","Black"] } ).pretty() ``` ### 擷取符合陣列中值的文件 若要尋找具有特殊陣列值的所有文件，請使用 `find()` 操作與您感興趣的陣列名稱和值。 ``` db.example.find( { "Colors": "Red" } ).pretty() ``` 前述操作會傳回全部三個文件，因為每個文件都有一個名為 `Colors` 的陣列，且陣列中某處具有「`Red`」值。如果您指定數值「`White`」，查詢只會傳回「廣告顏料」。 ### 使用運算子擷取文件 以下查詢會傳回其中「`Inventory.OnHand`」值小於 50 的所有文件。 ``` db.example.find( { "Inventory.OnHand": { $lt: 50 } } ) ``` 如需支援的查詢運算子清單的詳細資訊，請參閱[查詢和投影運算子](mongo-apis.md#mongo-apis-query)。 ## 更新文件 您的文件通常不是靜態的，而且會做為應用程式工作流程的一部分進行更新。以下範例說明一些可更新文件的方式。 若要更新現有文件，請使用 `update()` 操作。`update()` 操作有兩個文件參數。第一份文件識別要進行更新的文件。第二份文件指定要進行的更新。 當您更新現有欄位時，無論該欄位是簡單欄位、陣列或內嵌文件，您都可以指定欄位名稱及其值。操作到最後，舊文件的欄位已經由新欄位和值取代。 **Topics** + [更新現有欄位的值](#document-database-updating-existing-fields) + [新增欄位](#document-database-updating-adding-field) + [取代內嵌文件](#document-database-replacing-embedded-document) + [將新欄位插入內嵌文件](#document-database-updating-adding-field-embedded) + [從文件移除欄位](#document-database-remove-field) + [從多個文件移除欄位](#document-database-remove-field-all) ### 更新現有欄位的值 使用以下您稍早為下列更新操作新增的四個文件。 ``` { "Item": "Ruler", "Colors": ["Red","Green","Blue","Clear","Yellow"], "Inventory": { "OnHand": 47, "MinOnHand": 40 }, "UnitPrice": 0.89 }, { "Item": "Pen", "Colors": ["Red","Green","Blue","Black"], "Inventory": { "OnHand": 244, "MinOnHand": 72 } }, { "Item": "Poster Paint", "Colors": ["Red","Green","Blue","Black","White"], "Inventory": { "OnHand": 47, "MinOnHand": 50 } }, { "Item": "Spray Paint", "Colors": ["Black","Red","Green","Blue"], "Inventory": { "OnHand": 47, "MinOnHand": 50, "OrderQnty": 36 } } ``` **更新簡單欄位** 若要更新簡單欄位，請搭配使用 `update()` 和 `$set` 以指定欄位名稱和新值。以下範例會將 `Item` 從「Pen」(筆) 變更為「Gel Pen」(簽字筆)。 ``` db.example.update( { "Item" : "Pen" }, { $set: { "Item": "Gel Pen" } } ) ``` 此操作的結果將會如下所示。 ``` { "Item": "Gel Pen", "Colors": ["Red","Green","Blue","Black"], "Inventory": { "OnHand": 244, "MinOnHand": 72 } } ``` **更新陣列** 以下範例會取代現有顏色陣列和新陣列，其包含 `Orange` ，並從顏色清單放棄 `White`。新顏色清單的順序為 `update()` 操作中所指定的順序。 ``` db.example.update( { "Item" : "Poster Paint" }, { $set: { "Colors": ["Red","Green","Blue","Orange","Black"] } } ) ``` 此操作的結果將會如下所示。 ``` { "Item": "Poster Paint", "Colors": ["Red","Green","Blue","Orange","Black"], "Inventory": { "OnHand": 47, "MinOnHand": 50 } } ``` ### 新增欄位 若要藉由新增一或多個新的欄位來修改文件，請使用 `update()` 操作搭配查詢文件，以使用 `$set` 運算子識別要插入其中的文件及要插入的新欄位和值。 以下範例會將欄位 `UnitPrice` 的值 `3.99` 加入到噴漆文件。請注意，值 `3.99` 是數字，不是字串。 ``` db.example.update( { "Item": "Spray Paint" }, { $set: { "UnitPrice": 3.99 } } ) ``` 此操作的結果如下所示 (JSON 格式）。 ``` { "Item": "Spray Paint", "Colors": ["Black","Red","Green","Blue"], "Inventory": { "OnHand": 47, "MinOnHand": 50, "OrderQnty": 36 }, "UnitPrice": 3.99 } ``` ### 取代內嵌文件 若要藉由取代內嵌文件來修改文件，請使用 `update()` 操作搭配文件，以使用 `$set` 運算子識別內嵌文件及要插入的新欄位和值。 鑒於以下文件。 ``` db.example.insert({ "DocName": "Document 1", "Date": { "Year": 1987, "Month": 4, "Day": 18 } }) ``` **取代內嵌文件** 以下範例將目前日期文件取代為新的欄位，其中只包含 `Month` 和 `Day`，`Year` 已刪除。 ``` db.example.update( { "DocName" : "Document 1" }, { $set: { "Date": { "Month": 4, "Day": 18 } } } ) ``` 此操作的結果將會如下所示。 ``` { "DocName": "Document 1", "Date": { "Month": 4, "Day": 18 } } ``` ### 將新欄位插入內嵌文件 **將新欄位加入至內嵌文件** 若要藉由新增一或多個新欄位至內嵌文件來修改文件，請搭配文件使用 `update()` 操作，其識別內嵌文件及「點表示法」，以使用 `$set` 運算子指定內嵌文件和要插入的新欄位和值。 鑒於以下文件，以下程式碼使用「點表示法」將 `Year` 和 `DoW` 欄位插入到內嵌的 `Date` 文件，並將 `Words` 插入到父文件。 ``` { "DocName": "Document 1", "Date": { "Month": 4, "Day": 18 } } ``` ``` db.example.update( { "DocName" : "Document 1" }, { $set: { "Date.Year": 1987, "Date.DoW": "Saturday", "Words": 2482 } } ) ``` 此操作的結果將會如下所示。 ``` { "DocName": "Document 1", "Date": { "Month": 4, "Day": 18, "Year": 1987, "DoW": "Saturday" }, "Words": 2482 } ``` ### 從文件移除欄位 若要藉由移除文件中的欄位來修改文件，請使用 `update()` 操作搭配查詢文件，以使用 `$unset` 運算子識別要從中移除欄位的文件，以指定要移除的欄位。 下列範例會從前述文件中移除 `Words` 欄位。 ``` db.example.update( { "DocName" : "Document 1" }, { $unset: { Words:1 } } ) ``` 此操作的結果將會如下所示。 ``` { "DocName": "Document 1", "Date": { "Month": 4, "Day": 18, "Year": 1987, "DoW": "Saturday" } } ``` ### 從多個文件移除欄位 若要從多個文件中移除欄位來修改文件，請使用 `$unset` 操作搭配 `multi` 運算子，並將 `update()` 選項設定為 `true`。 以下範例會從範例集合的所有文件中移除 `Inventory` 欄位。如果文件沒有 `Inventory` 欄位，則不會對該文件執行任何動作。如果省略 `multi: true`，則只會對符合條件的第一個文件執行動作。 ``` db.example.update( {}, { $unset: { Inventory:1 } }, { multi: true } ) ``` ## 刪除文件 若要從資料庫中移除文件，請使用 `remove()` 操作，指定要移除的文件。以下程式碼會從您的 `example` 集合移除「簽字筆」。 ``` db.example.remove( { "Item": "Gel Pen" } ) ``` 若要從資料庫中移除所有文件，請使用 `remove()`操作搭配空白查詢。 ``` db.example.remove( { } ) ```