# Usar expressões de projeção no DynamoDB
<a name="Expressions.ProjectionExpressions"></a>

Para ler dados de uma tabela, você pode usar operações como `GetItem`, `Query`ou `Scan`. O Amazon DynamoDB retornará todos os atributos de item por padrão. Para obter somente alguns, em vez de todos os atributos, use uma expressão de projeção.

Uma *expressão de projeção* é uma string que identifica os atributos que você deseja. Para recuperar um único atributo, especifique o seu nome. Para vários atributos, os nomes devem ser separados por vírgulas.

Veja a seguir alguns exemplos de expressões de projeção, com base no item do `ProductCatalog` em [Referir-se a atributos de item ao usar expressões no DynamoDB](Expressions.Attributes.md):
+ Um único atributo de nível superior.

  `Title `
+ Três atributos de nível superior. O DynamoDB recupera o conjunto `Color` inteiro.

  `Title, Price, Color`
+ Quatro atributos de nível superior. O DynamoDB retorna todo o conteúdo de `RelatedItems` e `ProductReviews`.

  `Title, Description, RelatedItems, ProductReviews`

**nota**  
A expressão de projeção não afeta o consumo de throughput provisionado. O DynamoDB determina as unidades de capacidade consumidas com base no tamanho do item, e não na quantidade de dados que são retornados para uma aplicação.

**Palavras reservadas e caracteres especiais**

O DynamoDB inclui palavras reservadas e caracteres especiais. O DynamoDB permite usar essas palavras reservadas e caracteres especiais nos nomes, mas é recomendável evitar, pois será necessário usar aliases sempre que esses nomes forem utilizados em uma expressão. Para obter uma lista completa, consulte [Palavras reservadas no DynamoDB](ReservedWords.md).

Você precisará usar nomes de atributo de expressão no lugar do nome real se: 
+ O nome do atributo estiver na lista de palavras reservadas do DynamoDB.
+ O nome do atributo não atender ao requisito de que o primeiro caractere deve ser `a-z` ou `A-Z` e que o segundo caractere (se houver) deve ser `a-Z`, `A-Z` ou `0-9`.
+ O nome do atributo contiver **\$1** (cerquilha) ou **:** (dois-pontos).

O exemplo de AWS CLI a seguir mostra como usar uma expressão de projeção com uma operação `GetItem`. Essa expressão de projeção recupera um atributo escalar de nível superior (`Description`), o primeiro elemento em uma lista (`RelatedItems[0]`) e uma lista aninhada em um mapa (`ProductReviews.FiveStar`).

```
aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '"Id": { "N": "123" } \
    --projection-expression "Description, RelatedItems[0], ProductReviews.FiveStar"
```

O JSON a seguir seria retornado para este exemplo.

```
{
    "Item": {
        "Description": {
            "S": "123 description"
        },
        "ProductReviews": {
            "M": {
                "FiveStar": {
                    "L": [
                        {
                            "S": "Excellent! Can't recommend it highly enough! Buy it!"
                        },
                        {
                            "S": "Do yourself a favor and buy this."
                        }
                    ]
                }
            }
        },
        "RelatedItems": {
            "L": [
                {
                    "N": "341"
                }
            ]
        }
    }
}
```