Trabalhar com documentos - Amazon DocumentDB
Adicionar documentosConsultar documentosComo atualizar documentosComo excluir documentos

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.

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 pelo seu aplicativo.

Os exemplos a seguir usam a API do MongoDB para adicionar documentos.

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().

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.

Como atualizar documentos

Normalmente, seus documentos não são estáticos e são atualizados como parte de seus fluxos de trabalho de aplicativos. 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.

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

Como adicionar 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, conforme exemplo a seguir.

db.example.remove( { } )