As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Trabalhar com documentos Como um banco de dados de documentos, o Amazon DocumentDB facilita o armazenamento, a consulta e a indexação de dados JSON. No Amazon DocumentDB, uma coleção de banco de dados de documentos é semelhante a uma tabela em um banco de dados relacional, exceto pelo fato de não haver um único esquema aplicado a todos os documentos. As coleções permitem agrupar documentos semelhantes, mantendo-os todos no mesmo banco de dados, sem exigir que eles tenham a estrutura idêntica. Usando os exemplos de documentos das seções anteriores, é provável que você tenha coleções de `reading_material` e `office_supplies`. É função do software impor a que coleção um documento pertence. Os exemplos a seguir usam a API do MongoDB para mostrar como adicionar, consultar, atualizar e excluir documentos. **Topics** + [Adicionar documentos](#document-database-adding-documents) + [Consultar documentos](#document-database-queries) + [Como atualizar documentos](#document-database-updating) + [Como excluir documentos](#document-database-deleting) ## Adicionar documentos No Amazon DocumentDB, um banco de dados é criado quando você adiciona um documento a uma coleção. Neste exemplo, você está criando uma coleção chamada `example` no banco de dados `test`, que é o banco de dados padrão quando ao conectar-se a um cluster. Como a coleção é criada implicitamente quando o primeiro documento é inserido, não há erro ao verificar o nome da coleção. Portanto, um erro de digitação no nome da coleção, como `eexample` em vez de `example`, criará e adicionará o documento à coleção `eexample` em vez de à coleção pretendida. A verificação de erros deve ser processada pela sua aplicação. Os exemplos a seguir usam a API do MongoDB para adicionar documentos. **Topics** + [Adicionar um único documento](#document-database-adding-documents-single) + [Adicionar diversos documentos](#document-database-adding-documents-multiple) ### Adicionar um único documento Para adicionar um único documento a uma coleção, use a operação `insertOne( {} )` com o documento que você deseja adicionar à coleção. ``` db.example.insertOne( { "Item": "Ruler", "Colors": ["Red","Green","Blue","Clear","Yellow"], "Inventory": { "OnHand": 47, "MinOnHand": 40 }, "UnitPrice": 0.89 } ) ``` A saída dessa operação é semelhante ao seguinte (formato JSON). ``` { "acknowledged" : true, "insertedId" : ObjectId("5bedafbcf65ff161707de24f") } ``` ### Adicionar diversos documentos Para adicionar diversos documentos a uma coleção, use a operação `insertMany( [{},...,{}] )` com uma lista dos documentos que você deseja adicionar à coleção. Embora os documentos nessa lista específica tenham esquemas diferentes, todos eles podem ser adicionados à mesma coleção. ``` 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 } } ] ) ``` A saída dessa operação é semelhante ao seguinte (formato JSON). ``` { "acknowledged" : true, "insertedIds" : [ ObjectId("5bedb07941ca8d9198f5934c"), ObjectId("5bedb07941ca8d9198f5934d"), ObjectId("5bedb07941ca8d9198f5934e") ] } ``` ## Consultar documentos Às vezes, pode ser necessário examinar o inventário da sua loja online para que os clientes possam visualizar e comprar o que você está vendendo. Consultar uma coleção é relativamente fácil, quer você queira todos os documentos na coleção ou apenas os documentos que satisfazem a um critério específico. Para consultar documentos, use a operação `find()`. O comando `find()` tem um único parâmetro do documento que define os critérios a serem usados na escolha dos documentos a serem retornados. A saída de `find()` é um documento formatado como uma única linha de texto sem quebras de linha. Para formatar o documento de saída para facilitar a leitura, use `find().pretty()`. Todos os exemplos deste tópico usam `.pretty()` para formatar a saída. Use os quatro documentos inseridos na coleção `example` nos últimos dois exercícios - `insertOne()` e `insertMany()`. **Topics** + [Recuperar todos os documentos em uma coleção](#document-database-queries-all-documents) + [Recuperar documentos que correspondem a um valor de campo](#document-database-queries-match-criteria) + [Recuperar documentos que correspondem a um documento incorporado](#document-database-queries-entire-embedded-document) + [Recuperar documentos que correspondem a um valor de campo em um documento incorporado](#document-database-queries-embeded-document-field) + [Recuperar documentos que correspondem a uma matriz](#document-database-queries-array-match) + [Recuperar documentos que correspondem a um valor em uma matriz](#document-database-queries-array-value-match) + [Recuperar documentos usando operadores](#document-database-query-operators) ### Recuperar todos os documentos em uma coleção Para recuperar todos os documentos em sua coleção, use a operação `find()` com um documento de consulta vazio. A consulta a seguir retorna todos os documentos da coleção `example`. ``` db.example.find( {} ).pretty() ``` ### Recuperar documentos que correspondem a um valor de campo Para recuperar todos os documentos que correspondem a um campo e valor, use a operação `find()` com um documento de consulta que identifica os campos e valores a serem correspondidos. Usando documentos anteriores, essa consulta retorna todos os documentos em que o campo "Item" será igual a "Pen". ``` db.example.find( { "Item": "Pen" } ).pretty() ``` ### Recuperar documentos que correspondem a um documento incorporado Para localizar todos os documentos que correspondem a um documento incorporado, use a operação `find()` com um documento de consulta que especifica o nome do documento incorporado e todos os campos e valores desse documento incorporado. Ao vincular um documento incorporado, o documento incorporado do documento deve ter o mesmo nome que na consulta. Além disso, os campos e os valores no documento incorporado devem corresponder à consulta. A consulta a seguir retorna apenas o documento "Poster Paint". Isso ocorre porque a "Caneta" tem valores diferentes para "`OnHand`" e "`MinOnHand`", e a "Tinta spray" tem um campo a mais (`OrderQnty`) que o documento de consulta. ``` db.example.find({"Inventory": { "OnHand": 47, "MinOnHand": 50 } } ).pretty() ``` ### Recuperar documentos que correspondem a um valor de campo em um documento incorporado Para localizar todos os documentos que correspondem a um documento incorporado, use a operação `find()` com um documento de consulta que especifica o nome do documento incorporado e todos os campos e valores desse documento incorporado. Considerando os documentos anteriores, a consulta a seguir usa "notação de pontos" para especificar o documento incorporado e os campos de interesse. Qualquer documento que seja correspondente será retornado, independentemente de quais outros campos possam estar presentes no documento incorporado. A consulta retorna "Poster Paint" e "Spray Paint", pois ambos correspondem aos campos e valores especificados. ``` db.example.find({"Inventory.OnHand": 47, "Inventory.MinOnHand": 50 }).pretty() ``` ### Recuperar documentos que correspondem a uma matriz Para localizar todos os documentos que correspondem a uma matriz, use a operação `find()` com o nome da matriz de interesse e todos os valores na matriz. A consulta retorna todos os documentos que têm uma matriz com esse nome, com valores idênticos aos da matriz, e na mesma ordem que na consulta. A consulta a seguir retorna apenas o documento "Pen", pois o "Poster Paint" tem uma cor adicional (White), e "Spray Paint" tem as cores em ordem diferente. ``` db.example.find( { "Colors": ["Red","Green","Blue","Black"] } ).pretty() ``` ### Recuperar documentos que correspondem a um valor em uma matriz Para localizar todos os documentos que possuem um valor de matriz específico, use a operação `find()` com o valor e o nome da matriz de interesse. ``` db.example.find( { "Colors": "Red" } ).pretty() ``` A operação anterior retorna todos os três documentos, pois cada um deles tem uma matriz chamada `Colors` e o valor `Red` em algum lugar da matriz. Se você especificar o valor "`White`", a consulta retornará apenas "Tinta de cartaz". ### Recuperar documentos usando operadores A consulta a seguir retorna todos os documentos em que o valor "`Inventory.OnHand`" é inferior a 50. ``` db.example.find( { "Inventory.OnHand": { $lt: 50 } } ) ``` Para obter uma lista de operadores de consulta compatíveis, consulte [Operadores de consulta e projeção](mongo-apis.md#mongo-apis-query). ## Como atualizar documentos Normalmente, seus documentos não são estáticos e são atualizados como parte de seus fluxos de trabalho de aplicações. Os exemplos a seguir mostram algumas maneiras de como atualizar documentos. Para atualizar um documento existente, use a operação `update()`. A operação `update()` tem dois parâmetros de documento. O primeiro documento identifica qual(is) documento(s) atualizar. O segundo documento especifica as atualizações a fazer. Ao atualizar um campo existente - seja esse campo um campo simples, uma matriz ou um documento incorporado - você especifica o nome do campo e seus valores. No final da operação, é como se o campo no documento antigo tivesse sido substituído pelo novo campo e por novos valores. **Topics** + [Atualizar os valores de um campo existente](#document-database-updating-existing-fields) + [Adição de um novo campo](#document-database-updating-adding-field) + [Substituir um documento incorporado](#document-database-replacing-embedded-document) + [Inserir novos campos em um documento incorporado](#document-database-updating-adding-field-embedded) + [Remover um campo de um documento](#document-database-remove-field) + [Remover um campo de vários documentos](#document-database-remove-field-all) ### Atualizar os valores de um campo existente Use os quatro documentos a seguir, que você adicionou anteriormente, para as seguintes operações de atualização. ``` { "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 } } ``` **Para atualizar um campo simples** Para atualizar um campo simples, use `update()` com `$set` para especificar o nome e o novo valor do campo. O exemplo a seguir altera o `Item` de "Pen" para "Gel Pen". ``` db.example.update( { "Item" : "Pen" }, { $set: { "Item": "Gel Pen" } } ) ``` Os resultados dessa operação são semelhantes ao seguinte. ``` { "Item": "Gel Pen", "Colors": ["Red","Green","Blue","Black"], "Inventory": { "OnHand": 244, "MinOnHand": 72 } } ``` **Para atualizar uma matriz** O exemplo a seguir substitui a matriz de cores existente por uma nova matriz que inclui `Orange` e descarta `White` da lista de cores. A nova lista de cores está na ordem especificada na operação `update()`. ``` db.example.update( { "Item" : "Poster Paint" }, { $set: { "Colors": ["Red","Green","Blue","Orange","Black"] } } ) ``` Os resultados dessa operação são semelhantes ao seguinte. ``` { "Item": "Poster Paint", "Colors": ["Red","Green","Blue","Orange","Black"], "Inventory": { "OnHand": 47, "MinOnHand": 50 } } ``` ### Adição de um novo campo Para modificar um documento adicionando um ou mais novos campos, use a operação `update()` com um documento de consulta que identifica o documento a ser inserido e os novos campos e valores a serem inseridos usando o operador `$set`. O exemplo a seguir adiciona o campo `UnitPrice` com o valor `3.99` para o documento Spray Paints. Observe que o valor `3.99` é numérico, e não uma string. ``` db.example.update( { "Item": "Spray Paint" }, { $set: { "UnitPrice": 3.99 } } ) ``` Os resultados dessa operação são semelhantes ao seguinte (formato JSON). ``` { "Item": "Spray Paint", "Colors": ["Black","Red","Green","Blue"], "Inventory": { "OnHand": 47, "MinOnHand": 50, "OrderQnty": 36 }, "UnitPrice": 3.99 } ``` ### Substituir um documento incorporado Para modificar um documento substituindo um documento incorporado, use a operação `update()` com documentos que identificam o documento incorporado e seus novos campos e valores com o uso do operador `$set`. Considerando o seguinte documento. ``` db.example.insert({ "DocName": "Document 1", "Date": { "Year": 1987, "Month": 4, "Day": 18 } }) ``` **Substituir um documento incorporado** O exemplo a seguir substitui o documento de data atual por um novo que tem somente os campos `Month` e `Day`. O campo `Year` foi eliminado. ``` db.example.update( { "DocName" : "Document 1" }, { $set: { "Date": { "Month": 4, "Day": 18 } } } ) ``` Os resultados dessa operação são semelhantes ao seguinte. ``` { "DocName": "Document 1", "Date": { "Month": 4, "Day": 18 } } ``` ### Inserir novos campos em um documento incorporado **Como adicionar campos a um documento incorporado** Para modificar um documento adicionando um ou mais novos campos a um documento incorporado, use a operação `update()` com documentos que identificam o documento incorporado e "notação de pontos" para especificar o documento incorporado e os novos campos e valores a serem inseridos usando o operador `$set`. Considerando o documento a seguir, o código usa a "notação de pontos" para inserir os campos `Year` e `DoW` no documento `Date` incorporado, e `Words` no documento pai. ``` { "DocName": "Document 1", "Date": { "Month": 4, "Day": 18 } } ``` ``` db.example.update( { "DocName" : "Document 1" }, { $set: { "Date.Year": 1987, "Date.DoW": "Saturday", "Words": 2482 } } ) ``` Os resultados dessa operação são semelhantes ao seguinte. ``` { "DocName": "Document 1", "Date": { "Month": 4, "Day": 18, "Year": 1987, "DoW": "Saturday" }, "Words": 2482 } ``` ### Remover um campo de um documento Para modificar um documento removendo um campo do documento, use a operação `update()` com um documento de consulta que identifica o campo a ser removido do documento e o operador `$unset` para especificar o campo a ser removido. O exemplo a seguir remove o campo `Words` do documento anterior. ``` db.example.update( { "DocName" : "Document 1" }, { $unset: { Words:1 } } ) ``` Os resultados dessa operação são semelhantes ao seguinte. ``` { "DocName": "Document 1", "Date": { "Month": 4, "Day": 18, "Year": 1987, "DoW": "Saturday" } } ``` ### Remover um campo de vários documentos Para modificar um documento removendo um campo de vários documentos, use a operação `update()` com o operador `$unset` e a opção `multi` definida como `true`. O exemplo a seguir remove o campo `Inventory` de todos os documentos na coleção de exemplo. Se um documento não tiver o campo `Inventory`, nenhuma ação será executada nesse documento. Se `multi: true` for omitido, a ação será executada apenas no primeiro documento que atenda ao critério. ``` db.example.update( {}, { $unset: { Inventory:1 } }, { multi: true } ) ``` ## Como excluir documentos Para remover um documento do banco de dados, use a operação `remove()`, especificando qual documento remover. O código a seguir remove "Gel Pen" da sua coleção `example`. ``` db.example.remove( { "Item": "Gel Pen" } ) ``` Para remover todos os documentos do seu banco de dados, use a operação `remove()` com uma consulta vazia. ``` db.example.remove( { } ) ```