# Usar expressões no DynamoDB
No Amazon DynamoDB, você pode usar *expressões* para especificar quais atributos devem ser lidos em um item, gravar dados quando uma condição é atendida, especificar como atualizar um item, definir consultas e filtrar os resultados de uma consulta.
Esta tabela descreve a gramática de expressão básica e os tipos de expressão disponíveis.
| Tipo de expressão | Descrição |
| --- | --- |
| Expressão de projeção | Uma expressão de projeção identifica os atributos que você deseja recuperar de um item ao usar operações como GetItem, Query ou Scan. |
| Expressão de condição | Uma expressão de condição determina quais itens devem ser modificados ao usar as operações PutItem, UpdateItem e DeleteItem. |
| Expressão de atualização | Uma expressão de atualização especifica como UpdateItem modificará os atributos de um item. Por exemplo, definindo um valor escalar ou removendo elementos de uma lista ou de um mapa. |
| Expressão de condição principal | Uma expressão de condição principal determina quais itens uma consulta lerá em uma tabela ou índice. |
| Expressão de filtro | Uma expressão de filtro determina quais itens dos resultados de Query devem ser retornados para você. Todos os outros resultados serão descartados. |
Para saber mais sobre sintaxe de expressão e mais detalhes sobre cada tipo de expressão, consulte as seções a seguir.
**Topics**
+ [Referir-se a atributos de item ao usar expressões no DynamoDB](Expressions.Attributes.md)
+ [Nomes (aliases) de atributo de expressão no DynamoDB](Expressions.ExpressionAttributeNames.md)
+ [Usar valores de atributos de expressão no DynamoDB](Expressions.ExpressionAttributeValues.md)
+ [Usar expressões de projeção no DynamoDB](Expressions.ProjectionExpressions.md)
+ [Usar expressões de atualização no DynamoDB](Expressions.UpdateExpressions.md)
+ [Expressões de condição e filtro, operadores e funções no DynamoDB](Expressions.OperatorsAndFunctions.md)
+ [Exemplo de expressão de condição do DynamoDB na CLI](Expressions.ConditionExpressions.md)
**nota**
Para fins de compatibilidade com versões anteriores, o DynamoDB também aceita parâmetros condicionais que não usam expressões. Para obter mais informações, consulte [Parâmetros condicionais legados do DynamoDB](LegacyConditionalParameters.md).
Novas aplicações devem usar expressões em vez de parâmetros herdados.
# Referir-se a atributos de item ao usar expressões no DynamoDB
Esta seção descreve como consultar atributos de item em uma expressão no Amazon DynamoDB. Você pode trabalhar com qualquer atributo, mesmo se ele estiver profundamente aninhado dentro de várias listas e mapas.
**Topics**
+ [Atributos de nível superior](#Expressions.Attributes.TopLevelAttributes)
+ [Atributos aninhados](#Expressions.Attributes.NestedAttributes)
+ [Caminhos de documentos](#Expressions.Attributes.NestedElements.DocumentPathExamples)
**Um item de exemplo: ProductCatalog**
Os exemplos desta página usam o item de amostra a seguir na tabela `ProductCatalog`. (Esta tabela é descrita na seção [Exemplos de tabelas e dados para uso no DynamoDB](AppendixSampleTables.md).)
```
{
"Id": 123,
"Title": "Bicycle 123",
"Description": "123 description",
"BicycleType": "Hybrid",
"Brand": "Brand-Company C",
"Price": 500,
"Color": ["Red", "Black"],
"ProductCategory": "Bicycle",
"InStock": true,
"QuantityOnHand": null,
"RelatedItems": [
341,
472,
649
],
"Pictures": {
"FrontView": "http://example.com/products/123_front.jpg",
"RearView": "http://example.com/products/123_rear.jpg",
"SideView": "http://example.com/products/123_left_side.jpg"
},
"ProductReviews": {
"FiveStar": [
"Excellent! Can't recommend it highly enough! Buy it!",
"Do yourself a favor and buy this."
],
"OneStar": [
"Terrible product! Do not buy this."
]
},
"Comment": "This product sells out quickly during the summer",
"Safety.Warning": "Always wear a helmet"
}
```
Observe o seguinte:
+ O valor da chave de partição (`Id`) é `123`. Não há chave de classificação.
+ A maioria dos atributos têm tipos de dados escalares, como `String`, `Number`, `Boolean` e `Null`.
+ Um atributo (`Color`) é um `String Set`.
+ Os atributos a seguir são tipos de dados de documento:
+ Uma lista de `RelatedItems`. Cada elemento é um `Id` de um produto relacionado.
+ Um mapa de `Pictures`. Cada elemento é uma breve descrição de uma imagem, juntamente com um URL para o arquivo de imagem correspondente.
+ Um mapa de `ProductReviews`. Cada elemento representa uma classificação e uma lista de avaliações correspondentes a essa classificação. Inicialmente, esse mapa é preenchido com avaliações de cinco estrelas e de uma estrela.
## Atributos de nível superior
Um atributo será considerado como de *nível superior* se ele não estiver incorporado a outro atributo. Para o item do `ProductCatalog`, os atributos de nível superior são os seguintes:
+ `Id`
+ `Title`
+ `Description`
+ `BicycleType`
+ `Brand`
+ `Price`
+ `Color`
+ `ProductCategory`
+ `InStock`
+ `QuantityOnHand`
+ `RelatedItems`
+ `Pictures`
+ `ProductReviews`
+ `Comment`
+ `Safety.Warning`
Todos esses atributos de nível superior são escalares, exceto `Color` (lista), `RelatedItems` (lista), `Pictures` (mapa) e `ProductReviews` (mapa).
## Atributos aninhados
Um atributo é considerado *aninhado* se ele estiver incorporado a outro atributo. Para acessar um atributo aninhado, utiliza-se *operadores de cancelamento de referência*:
+ `[n]`: para elementos de lista
+ `.` (ponto): para elementos de mapa
### Acesso a elementos de lista
O operador de desreferência de um elemento de lista é **[*N*]**, onde *n* é o número do elemento. Os elementos de lista são baseados em zero, portanto, [0] representa o primeiro elemento na lista, [1] representa o segundo, e assim por diante. Veja alguns exemplos:
+ `MyList[0]`
+ `AnotherList[12]`
+ `ThisList[5][11]`
O próprio elemento `ThisList[5]` é uma lista aninhada. Portanto, `ThisList[5][11]` refere-se ao décimo segundo elemento na lista.
O número dentro de colchetes deve ser um inteiro não negativo. Portanto, as seguintes expressões são inválidas:
+ `MyList[-1]`
+ `MyList[0.4]`
### Acessar elementos de mapas
O operador de cancelamento de referência de um elemento de mapa é **.** (um ponto). Use um ponto como um separador entre os elementos em um mapa:
+ `MyMap.nestedField`
+ `MyMap.nestedField.deeplyNestedField`
## Caminhos de documentos
Em uma expressão, você usa um *caminho de documento* para informar ao DynamoDB onde encontrar um atributo. Para um atributo de nível superior, o caminho do documento é simplesmente o nome do atributo. Para um atributo aninhado, você pode construir o caminho do documento usando operadores de cancelamento de referência.
Veja a seguir alguns exemplos de caminhos de documentos. (Consulte o item mostrado em [Referir-se a atributos de item ao usar expressões no DynamoDB](#Expressions.Attributes).)
+ Um atributo escalar de nível superior.
`Description`
+ Um atributo de lista de nível superior. (Isso retorna a lista inteira, não apenas alguns dos elementos.)
`RelatedItems`
+ O terceiro elemento na lista `RelatedItems`. (Lembre-se de que os elementos de lista são baseadas em zero.)
`RelatedItems[2]`
+ A imagem da visão frontal do produto.
`Pictures.FrontView`
+ Todas as críticas de cinco estrelas.
`ProductReviews.FiveStar`
+ A primeira das críticas de cinco estrelas.
`ProductReviews.FiveStar[0]`
**nota**
A profundidade máxima de um caminho de documento é 32. Portanto, o número de operadores de cancelamento de referência em um caminho não pode exceder esse limite.
É possível usar qualquer nome de atributo em um caminho de documento, desde ele que cumpra estes requisitos:
+ O primeiro caractere deve ser `a-z` ou `A-Z` e ou `0-9`
+ O segundo caractere (se presente) deve ser `a-z`, `A-Z`
**nota**
Se um nome de atributo não cumprir essas exigências, você deverá definir um nome de atributo de expressão como um espaço reservado.
Para obter mais informações, consulte [Nomes (aliases) de atributo de expressão no DynamoDB](Expressions.ExpressionAttributeNames.md).
# Nomes (aliases) de atributo de expressão no DynamoDB
Um *nome de atributo de expressão* é um alias (ou espaço reservado) usado em uma expressão do Amazon DynamoDB como alternativa ao nome de atributo real. Um nome de atributo de expressão deve começar com um sinal de cerquilha (`#`) seguido de um ou mais caracteres alfanuméricos. O sublinhado (`_`) também é permitido.
Esta seção descreve várias situações em que você precisa usar nomes de atributos de expressão.
**nota**
Os exemplos desta seção usam a AWS Command Line Interface (AWS CLI).
**Topics**
+ [Palavras reservadas](#Expressions.ExpressionAttributeNames.ReservedWords)
+ [Nomes de atributos com caracteres especiais](#Expressions.ExpressionAttributeNames.AttributeNamesContainingSpecialCharacters)
+ [Atributos aninhados](#Expressions.ExpressionAttributeNames.NestedAttributes)
+ [Consultar nomes de atributo de forma repetida](#Expressions.ExpressionAttributeNames.RepeatingAttributeNames)
## Palavras reservadas
Algumas vezes, pode ser necessário escrever uma expressão que contém um nome de atributo que está em conflito com uma palavra reservada do DynamoDB. (Para obter uma lista completa de palavras reservadas, consulte [Palavras reservadas no DynamoDB](ReservedWords.md).)
Por exemplo, haveria falha no seguinte exemplo da AWS CLI porque `COMMENT` é uma palavra reservada.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "Comment"
```
Para resolver esse problema, substitua `Comment` por um nome de atributo de expressão, como `#c`. A `#` (cerquilha) é obrigatória e indica que esse é um espaço reservado para um nome de atributo. O exemplo da AWS CLI agora deve ter a seguinte aparência.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "#c" \
--expression-attribute-names '{"#c":"Comment"}'
```
**nota**
Se o nome de um atributo começar com um número, contiver um espaço ou incluir uma palavra reservada, você *deverá* usar um nome de atributo de expressão para substituir esse nome de atributo na expressão.
## Nomes de atributos com caracteres especiais
Em uma expressão, um ponto (“.”) é interpretado como um caractere de separação em um caminho de documento. No entanto, o DynamoDB também permite que você use um ponto e outros caracteres especiais, como um hífen (“-”) como parte do nome de um atributo. Isso pode ser ambíguo em alguns casos. Para ilustrar, vamos supor que você queira recuperar o atributo `Safety.Warning` de um item do `ProductCatalog` (consulte [Referir-se a atributos de item ao usar expressões no DynamoDB](Expressions.Attributes.md)).
Suponha que você queira acessar `Safety.Warning` usando uma expressão de projeção.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "Safety.Warning"
```
O DynamoDB retorna um resultado vazio, em vez da string esperada (“”). ("`Always wear a helmet`"). Isso ocorre porque o DynamoDB interpreta um ponto em uma expressão como um separador de caminho de documento. Neste caso, defina um nome de atributo de expressão (por exemplo, `#sw`) como um substituto para `Safety.Warning`. Você poderia usar a seguinte expressão de projeção.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "#sw" \
--expression-attribute-names '{"#sw":"Safety.Warning"}'
```
Em seguida, o DynamoDB deverá retornar o resultado correto.
**nota**
Se o nome de um atributo contiver um ponto (“.”) ou um hífen (“-”), você *deverá* usar um nome de atributo de expressão para substituir o nome desse atributo na expressão.
## Atributos aninhados
Suponha que você queira acessar o atributo `ProductReviews.OneStar` aninhado. No nome de atributo de expressão, o DynamoDB trata o ponto (“.”) como um caractere no nome de um atributo. Para consultar o atributo aninhado, defina um nome de atributo de expressão para cada elemento no caminho do documento:
+ `#pr — ProductReviews`
+ `#1star — OneStar`
Você poderia usar `#pr.#1star` para a expressão de projeção.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "#pr.#1star" \
--expression-attribute-names '{"#pr":"ProductReviews", "#1star":"OneStar"}'
```
Em seguida, o DynamoDB deverá retornar o resultado correto.
## Consultar nomes de atributo de forma repetida
Os nomes de atributo de expressão são úteis quando você precisa consultar o mesmo nome de atributo repetidamente. Por exemplo, considere a seguinte expressão para recuperar algumas das revisões de um item do `ProductCatalog`.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "ProductReviews.FiveStar, ProductReviews.ThreeStar, ProductReviews.OneStar"
```
Para tornar isso mais conciso, você pode substituir `ProductReviews` por um nome de atributo de expressão, como `#pr`. A expressão revisada agora teria a seguinte aparência.
+ `#pr.FiveStar, #pr.ThreeStar, #pr.OneStar`
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "#pr.FiveStar, #pr.ThreeStar, #pr.OneStar" \
--expression-attribute-names '{"#pr":"ProductReviews"}'
```
Caso defina um nome de atributo de expressão, você deverá usá-lo de forma consistente na expressão inteira. Além disso, não é possível omitir o símbolo `#`.
# Usar valores de atributos de expressão no DynamoDB
Os *valores de atributo de expressão* no Amazon DynamoDB atuam como variáveis. Eles substituem os valores reais que você deseja comparar; isto é, valores que talvez não conheça antes do tempo de execução. Um valor de atributo de expressão deve começar com um sinal de dois pontos (`:`) seguido por um ou mais caracteres alfanuméricos.
Por exemplo, suponha que você quisesse retornar todos os itens de `ProductCatalog` que estão disponíveis em `Black` e custam `500` ou menos. Você poderia usar uma operação `Scan` com uma expressão de filtro, como neste exemplo da AWS Command Line Interface (AWS CLI).
```
aws dynamodb scan \
--table-name ProductCatalog \
--filter-expression "contains(Color, :c) and Price <= :p" \
--expression-attribute-values file://values.json
```
Os argumentos de `--expression-attribute-values` são armazenados no arquivo `values.json`.
```
{
":c": { "S": "Black" },
":p": { "N": "500" }
}
```
Caso defina um valor de atributo de expressão, você deverá usá-lo de forma consistente na expressão inteira. Além disso, não é possível omitir o símbolo `:`.
Os valores de atributo de expressão são usados com expressões de condições de chaves, expressões de condições, expressões de atualização e expressões de filtro.
# Usar expressões de projeção no DynamoDB
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"
}
]
}
}
}
```
# Usar expressões de atualização no DynamoDB
A ação `UpdateItem` atualiza um item existente ou adiciona um item novo à tabela, caso ele ainda não exista. Você deve fornecer a chave do item que deseja atualizar. Você também deve fornecer uma expressão de atualização indicando os atributos que deseja modificar e os valores que deseja atribuir a eles.
Uma *expressão de atualização* especifica como `UpdateItem` modificará os atributos de um item. Por exemplo, definindo um valor escalar ou removendo elementos de uma lista ou de um mapa.
Veja a seguir um resumo da sintaxe para expressões de atualização.
```
update-expression ::=
[ SET action [, action] ... ]
[ REMOVE action [, action] ...]
[ ADD action [, action] ... ]
[ DELETE action [, action] ...]
```
Uma expressão de atualização consiste em uma ou mais cláusulas. Cada cláusula começa com uma palavra-chave `SET`, `REMOVE`, `ADD` ou `DELETE`. Você pode incluir qualquer uma dessas cláusulas em uma expressão de atualização, em qualquer ordem. No entanto, cada palavra-chave de ação pode aparecer apenas uma vez.
Dentro de cada cláusula há uma ou mais ações, separadas por vírgulas. Cada ação representa uma modificação de dados.
Os exemplos desta seção se baseiam no item `ProductCatalog` mostrado em [Usar expressões de projeção no DynamoDB](Expressions.ProjectionExpressions.md).
Os tópicos abaixo abrangem alguns casos de uso diferentes da ação `SET`.
**Topics**
+ [SET: modificar ou adicionar atributos de um item](#Expressions.UpdateExpressions.SET)
+ [REMOVE: excluir atributos de um item](#Expressions.UpdateExpressions.REMOVE)
+ [ADD: atualizar números e conjuntos](#Expressions.UpdateExpressions.ADD)
+ [DELETE: remover elementos de um conjunto](#Expressions.UpdateExpressions.DELETE)
+ [Usar várias expressões de atualização](#Expressions.UpdateExpressions.Multiple)
## SET: modificar ou adicionar atributos de um item
Use a ação `SET` em uma expressão de atualização para adicionar um ou mais atributos a um item. Se qualquer um desses atributos já existir, eles serão substituídos pelos novos valores. Se você deseja evitar a substituição de um atributo existente, pode usar `SET` com a função `if_not_exists`. A função `if_not_exists` é específica à ação `SET` e só pode ser usada em uma expressão de atualização.
Quando você usa `SET` para atualizar um elemento de lista, o conteúdo desse elemento é substituído pelos novos dados especificados. Se o elemento ainda não existir, `SET` acrescentará o novo elemento ao final da lista.
Se você adicionar vários elementos em uma única operação `SET`, estes serão classificados por número de elemento.
Você também pode usar `SET` para adicionar ou subtrair de um atributo do tipo `Number`. Para executar várias ações `SET`, separe-as com vírgulas.
No seguinte resumo de sintaxe:
+ O elemento *path* é o caminho do documento para o item.
+ Um elemento **operando** pode ser o caminho de um documento para um item ou uma função.
```
set-action ::=
path = value
value ::=
operand
| operand '+' operand
| operand '-' operand
operand ::=
path | function
function ::=
if_not_exists (path, value)
```
Se o item não contiver um atributo no caminho especificado, `if_not_exists` será avaliado como `value`. Caso contrário, será avaliado como `path`.
A seguinte operação `PutItem` cria um item de exemplo ao qual os exemplos fazem referência.
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item file://item.json
```
Os argumentos de `--item` são armazenados no arquivo `item.json`. (Para simplificar, apenas alguns atributos de item são usados.)
```
{
"Id": {"N": "789"},
"ProductCategory": {"S": "Home Improvement"},
"Price": {"N": "52"},
"InStock": {"BOOL": true},
"Brand": {"S": "Acme"}
}
```
**Topics**
+ [Modificar atributos](#Expressions.UpdateExpressions.SET.ModifyingAttributes)
+ [Adicionar listas e mapas](#Expressions.UpdateExpressions.SET.AddingListsAndMaps)
+ [Adicionar elementos a uma lista](#Expressions.UpdateExpressions.SET.AddingListElements)
+ [Adicionar atributos de mapa aninhados](#Expressions.UpdateExpressions.SET.AddingNestedMapAttributes)
+ [Incrementar e reduzir atributos numéricos](#Expressions.UpdateExpressions.SET.IncrementAndDecrement)
+ [Acrescentar elementos a uma lista](#Expressions.UpdateExpressions.SET.UpdatingListElements)
+ [Impedir substituições de um atributo existente](#Expressions.UpdateExpressions.SET.PreventingAttributeOverwrites)
### Modificar atributos
**Example**
Atualize os atributos `ProductCategory` e `Price`.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET ProductCategory = :c, Price = :p" \
--expression-attribute-values file://values.json \
--return-values ALL_NEW
```
Os argumentos de `--expression-attribute-values` são armazenados no arquivo `values.json`.
```
{
":c": { "S": "Hardware" },
":p": { "N": "60" }
}
```
**nota**
Na operação `UpdateItem`, `--return-values ALL_NEW` faz com que o DynamoDB retorne o item como ele aparece após a atualização.
### Adicionar listas e mapas
**Example**
Adicione uma nova lista e um novo mapa.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET RelatedItems = :ri, ProductReviews = :pr" \
--expression-attribute-values file://values.json \
--return-values ALL_NEW
```
Os argumentos de `--expression-attribute-values` são armazenados no arquivo `values.json`.
```
{
":ri": {
"L": [
{ "S": "Hammer" }
]
},
":pr": {
"M": {
"FiveStar": {
"L": [
{ "S": "Best product ever!" }
]
}
}
}
}
```
### Adicionar elementos a uma lista
**Example**
Adicione um novo atributo à lista `RelatedItems`. (Lembre-se de que elementos de lista são baseados em zero e, portanto, [0] representa o primeiro elemento da lista, [1] representa o segundo, e assim por diante.)
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET RelatedItems[1] = :ri" \
--expression-attribute-values file://values.json \
--return-values ALL_NEW
```
Os argumentos de `--expression-attribute-values` são armazenados no arquivo `values.json`.
```
{
":ri": { "S": "Nails" }
}
```
**nota**
Quando você usa `SET` para atualizar um elemento de lista, o conteúdo desse elemento é substituído pelos novos dados especificados. Se o elemento ainda não existir, `SET` acrescentará o novo elemento ao final da lista.
Se você adicionar vários elementos em uma única operação `SET`, estes serão classificados por número de elemento.
### Adicionar atributos de mapa aninhados
**Example**
Adicione alguns atributos de mapa aninhados.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET #pr.#5star[1] = :r5, #pr.#3star = :r3" \
--expression-attribute-names file://names.json \
--expression-attribute-values file://values.json \
--return-values ALL_NEW
```
Os argumentos de `--expression-attribute-names` são armazenados no arquivo `names.json`.
```
{
"#pr": "ProductReviews",
"#5star": "FiveStar",
"#3star": "ThreeStar"
}
```
Os argumentos de `--expression-attribute-values` são armazenados no arquivo `values.json`.
```
{
":r5": { "S": "Very happy with my purchase" },
":r3": {
"L": [
{ "S": "Just OK - not that great" }
]
}
}
```
**Importante**
Não será possível atualizar os atributos do mapa aninhado se o mapa pai não existir. Se você tentar atualizar um atributo aninhado (por exemplo, `ProductReviews.FiveStar`) quando o mapa pai (`ProductReviews`) não existir, o DynamoDB exibirá `ValidationException` com a mensagem *“O caminho do documento fornecido na expressão de atualização é inválido para atualização”*.
Ao criar itens que terão atributos de mapa aninhados atualizados posteriormente, inicialize mapas vazios para os atributos principais. Por exemplo:
```
{
"Id": {"N": "789"},
"ProductReviews": {"M": {}},
"Metadata": {"M": {}}
}
```
Isso permite que você atualize atributos aninhados, como `ProductReviews.FiveStar`, sem erros.
### Incrementar e reduzir atributos numéricos
Você pode adicionar ou subtrair de um atributo numérico existente. Para fazer isso, use os operadores `+` (mais) e `-` (menos).
**Example**
Diminua o valor do `Price` de um item.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET Price = Price - :p" \
--expression-attribute-values '{":p": {"N":"15"}}' \
--return-values ALL_NEW
```
Para aumentar o valor do `Price`, você usa o operador `+` na expressão de atualização.
### Acrescentar elementos a uma lista
É possível adicionar elementos ao final de uma lista. Para fazer isso, use `SET` com a função `list_append`. (O nome da função diferencia maiúsculas de minúsculas.) A função `list_append` é específica à ação `SET` e só pode ser usada em uma expressão de atualização. A sintaxe é a seguinte.
+ `list_append (list1, list2)`
A função utiliza duas listas como entrada e acrescenta todos os elementos de `list2` a ` list1`.
**Example**
Em [Adicionar elementos a uma lista](#Expressions.UpdateExpressions.SET.AddingListElements), você cria a lista `RelatedItems` e a preenche com dois elementos: `Hammer` e `Nails`. Na sequência, você acrescenta mais dois elementos ao final de `RelatedItems`.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET #ri = list_append(#ri, :vals)" \
--expression-attribute-names '{"#ri": "RelatedItems"}' \
--expression-attribute-values file://values.json \
--return-values ALL_NEW
```
Os argumentos de `--expression-attribute-values` são armazenados no arquivo `values.json`.
```
{
":vals": {
"L": [
{ "S": "Screwdriver" },
{"S": "Hacksaw" }
]
}
}
```
Por fim, você acrescenta mais um elemento ao *início* de `RelatedItems`. Para fazer isso, alterne a ordem dos elementos de `list_append`. (Lembre-se de que `list_append` usa duas listas como entrada e acrescenta a segunda lista à primeira.)
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET #ri = list_append(:vals, #ri)" \
--expression-attribute-names '{"#ri": "RelatedItems"}' \
--expression-attribute-values '{":vals": {"L": [ { "S": "Chisel" }]}}' \
--return-values ALL_NEW
```
Agora, o atributo `RelatedItems` resultante contém cinco elementos, na seguinte ordem: `Chisel`, `Hammer`, `Nails`, `Screwdriver`, `Hacksaw`.
### Impedir substituições de um atributo existente
**Example**
Defina o `Price` de um item, mas somente se o item ainda não tiver um atributo `Price`. (Se o atributo `Price` já existir, não acontecerá nada.)
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET Price = if_not_exists(Price, :p)" \
--expression-attribute-values '{":p": {"N": "100"}}' \
--return-values ALL_NEW
```
## REMOVE: excluir atributos de um item
Use a ação `REMOVE` em uma expressão de atualização para remover um ou mais atributos de um item no Amazon DynamoDB. Para executar várias ações `REMOVE`, separe-as com vírgulas.
O seguinte é um resumo da sintaxe de `REMOVE` em uma expressão de atualização. O único operando é o caminho do documento do atributo que você deseja remover.
```
remove-action ::=
path
```
**Example**
Remova alguns atributos de um item. (Se os atributos não existirem, nada acontecerá.)
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "REMOVE Brand, InStock, QuantityOnHand" \
--return-values ALL_NEW
```
### Remover elementos de uma lista
É possível usar `REMOVE` para excluir elementos individuais de uma lista.
**Example**
Em [Acrescentar elementos a uma lista](#Expressions.UpdateExpressions.SET.UpdatingListElements), você modifica um atributo da lista (`RelatedItems`) de forma que ele contenha cinco elementos:
+ `[0]`—`Chisel`
+ `[1]`—`Hammer`
+ `[2]`—`Nails`
+ `[3]`—`Screwdriver`
+ `[4]`—`Hacksaw`
O exemplo da AWS Command Line Interface (AWS CLI) a seguir exclui `Hammer` e `Nails` da lista.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "REMOVE RelatedItems[1], RelatedItems[2]" \
--return-values ALL_NEW
```
Depois que `Hammer` e `Nails` forem removidos, os elementos restantes serão deslocados. Agora, a lista contém o seguinte:
+ `[0]`—`Chisel`
+ `[1]`—`Screwdriver`
+ `[2]`—`Hacksaw`
## ADD: atualizar números e conjuntos
**nota**
Em geral, recomendamos usar `SET` em vez de `ADD` para garantir operações idempotentes.
Use a ação `ADD` em uma expressão de atualização para adicionar um novo atributo e seus valores a um item.
Se o atributo já existir, o comportamento de `ADD` dependerá do tipo de dados do atributo:
+ Se o atributo for um número, e o valor que você está adicionando também for um número, esse valor será matematicamente adicionado ao atributo existente. (Se o valor for um número negativo, ele será subtraído do atributo existente.)
+ Se o atributo for um conjunto, e o valor que você está adicionando também for um conjunto, esse valor será acrescentado ao conjunto existente.
**nota**
A ação `ADD` oferece suporte apenas a tipos de dados de número e conjunto.
Para executar várias ações `ADD`, separe-as com vírgulas.
No seguinte resumo de sintaxe:
+ O elemento *path* é o caminho do documento para um atributo. O atributo deve ser um `Number` ou um tipo de dados de conjunto.
+ O elemento *value* é um número que você deseja adicionar ao atributo (para tipos de dados `Number`) ou um conjunto a ser acrescentado ao atributo (para tipos de conjunto).
```
add-action ::=
path value
```
Os tópicos abaixo abrangem alguns casos de uso diferentes da ação `ADD`.
**Topics**
+ [Adicionar um número](#Expressions.UpdateExpressions.ADD.Number)
+ [Adicionar elementos a um conjunto](#Expressions.UpdateExpressions.ADD.Set)
### Adicionar um número
Suponha que o atributo `QuantityOnHand` não exista. O exemplo da AWS CLI a seguir define `QuantityOnHand` como 5.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "ADD QuantityOnHand :q" \
--expression-attribute-values '{":q": {"N": "5"}}' \
--return-values ALL_NEW
```
Agora que `QuantityOnHand` existe, você pode executar novamente o exemplo para incrementar `QuantityOnHand` em 5 de cada vez.
### Adicionar elementos a um conjunto
Suponha que o atributo `Color` não exista. O exemplo da AWS CLI a seguir define `Color` como um conjunto de strings com dois elementos.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "ADD Color :c" \
--expression-attribute-values '{":c": {"SS":["Orange", "Purple"]}}' \
--return-values ALL_NEW
```
Agora que `Color` existe, você pode adicionar mais elementos a ele.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "ADD Color :c" \
--expression-attribute-values '{":c": {"SS":["Yellow", "Green", "Blue"]}}' \
--return-values ALL_NEW
```
## DELETE: remover elementos de um conjunto
**Importante**
A ação `DELETE` oferece suporte apenas a tipos de dados `Set`.
Use a ação `DELETE` em uma expressão de atualização para remover um ou mais elementos de um conjunto. Para executar várias ações `DELETE`, separe-as com vírgulas.
No seguinte resumo de sintaxe:
+ O elemento *path* é o caminho do documento para um atributo. Esse atributo deve ser um tipo de dados de conjunto.
+ O elemento *subset* é um ou mais elementos que você deseja excluir de *path*. Você deve especificar o elemento *subset* como um tipo set.
```
delete-action ::=
path subset
```
**Example**
Em [Adicionar elementos a um conjunto](#Expressions.UpdateExpressions.ADD.Set), você cria o conjunto de tipo string `Color`. Este exemplo remove alguns dos elementos desse conjunto.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "DELETE Color :p" \
--expression-attribute-values '{":p": {"SS": ["Yellow", "Purple"]}}' \
--return-values ALL_NEW
```
## Usar várias expressões de atualização
É possível usar várias ações em uma única expressão de atualização. Todas as referências a atributos são resolvidas em relação ao estado do item antes que qualquer uma das ações seja aplicada.
**Example**
Dado um item `{"id": "1", "a": 1, "b": 2, "c": 3}`, a seguinte expressão remove `a` e muda os valores de `b` e `c`:
```
aws dynamodb update-item \
--table-name test \
--key '{"id":{"S":"1"}}' \
--update-expression "REMOVE a SET b = a, c = b" \
--return-values ALL_NEW
```
O resultado é `{"id": "1", "b": 1, "c": 2}`. Embora `a` seja removida e `b` reatribuída na mesma expressão, ambas as referências retornam os valores originais.
**Example**
Se quiser modificar o valor de um atributo e remover outro completamente, você poderá usar uma ação SET e uma REMOVE em uma única declaração. Essa operação reduziria o valor de `Price` para 15 e, ao mesmo tempo, removeria o atributo `InStock` do item.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET Price = Price - :p REMOVE InStock" \
--expression-attribute-values '{":p": {"N":"15"}}' \
--return-values ALL_NEW
```
**Example**
Se quiser adicionar a uma lista e, ao mesmo tempo, alterar o valor de outro atributo, você poderá usar duas ações SET em uma única declaração. Essa operação adicionaria “Unhas” ao atributo da lista `RelatedItems` e também definiria o valor de `Price` como 21.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET RelatedItems[1] = :newValue, Price = :newPrice" \
--expression-attribute-values '{":newValue": {"S":"Nails"}, ":newPrice": {"N":"21"}}' \
--return-values ALL_NEW
```
# Expressões de condição e filtro, operadores e funções no DynamoDB
Para manipular dados em uma tabela do DynamoDB, use as operações `PutItem`, `UpdateItem` e `DeleteItem`. Para essas operações de manipulação de dados, é possível especificar uma expressão de condição para determinar quais itens devem ser modificados. Se a expressão de condição for avaliada como verdadeira, a operação terá êxito. Caso contrário, haverá falha na operação.
Esta seção aborda as funções e palavras-chave integradas para escrever expressões de filtro e expressões de condição no Amazon DynamoDB. Para obter informações mais detalhadas sobre funções e programação com o DynamoDB, consulte [Programação com o DynamoDB e os AWS SDKs](Programming.md) e a [Referência da API do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/).
**Topics**
+ [Sintaxe para expressões de filtro e de condição](#Expressions.OperatorsAndFunctions.Syntax)
+ [Fazer comparações](#Expressions.OperatorsAndFunctions.Comparators)
+ [Funções](#Expressions.OperatorsAndFunctions.Functions)
+ [Avaliações lógicas](#Expressions.OperatorsAndFunctions.LogicalEvaluations)
+ [Parênteses](#Expressions.OperatorsAndFunctions.Parentheses)
+ [Precedência em condições](#Expressions.OperatorsAndFunctions.Precedence)
## Sintaxe para expressões de filtro e de condição
No seguinte resumo de sintaxe, um *operando* pode ser o seguinte:
+ Um nome de atributo de nível superior, como `Id`, `Title`, `Description` ou `ProductCategory`
+ Um caminho de documento que faz referência a um atributo aninhado
```
condition-expression ::=
operand comparator operand
| operand BETWEEN operand AND operand
| operand IN ( operand (',' operand (, ...) ))
| function
| condition AND condition
| condition OR condition
| NOT condition
| ( condition )
comparator ::=
=
| <>
| <
| <=
| >
| >=
function ::=
attribute_exists (path)
| attribute_not_exists (path)
| attribute_type (path, type)
| begins_with (path, substr)
| contains (path, operand)
| size (path)
```
## Fazer comparações
Use esses comparadores para comparar um operando com um único valor:
+ `a = b`: verdadeiro se *a* for igual a *b*.
+ `a <> b`: verdadeiro se *a* não for igual a *b*.
+ `a < b`: verdadeiro se *a* for menor que *b*.
+ `a <= b`: verdadeiro se *a* for menor que ou igual a *b*.
+ `a > b`: verdadeiro se *a* for maior que *b*.
+ `a >= b`: verdadeiro se *a* for maior ou igual a *b*.
Use as palavras-chave `BETWEEN` e `IN` para comparar um operando com um intervalo de valores ou com uma lista enumerada de valores:
+ `a BETWEEN b AND c`: verdadeiro se *a* for maior ou igual a *b* e menor ou igual a *c*.
+ `a IN (b, c, d) `: verdadeiro se *a* for igual a qualquer um dos valores na lista; por exemplo, *b*, *c* ou *d*. A lista pode conter até 100 valores, separados por vírgulas.
## Funções
Use as funções a seguir para determinar se um atributo existe em um item ou para avaliar o valor de um atributo. Esses nomes de funções diferenciam maiúsculas de minúsculas. Para um atributo aninhado, você deve fornecer o caminho completo do documento.
****
| Função | Descrição |
| --- | --- |
| `attribute_exists (path)` | True se o item contiver o atributo especificado por `path`. Exemplo: verificar se um item na tabela `Product` tem uma imagem de vista lateral. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) |
| `attribute_not_exists (path)` | True se o atributo especificado por `path` não existir no item. Exemplo: verificar se um item tem um atributo `Manufacturer`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) |
| `attribute_type (path, type)` | True se o atributo no caminho especificado for de um tipo de dados específico. O parâmetro `type` deve ser um dos seguintes: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Você deve usar um valor de atributo de expressão para o parâmetro `type`. Exemplo: verificar se o atributo `QuantityOnHand` é do tipo Lista. Neste exemplo, `:v_sub` é um espaço reservado para a string `L`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Você deve usar um valor de atributo de expressão para o parâmetro `type`. |
| `begins_with (path, substr)` | Verdadeiro se o atributo especificado por `path` começar com uma substring específica. Exemplo: verificar se os primeiros caracteres do URL da imagem de vista frontal são `http://`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) O valor do atributo de expressão `:v_sub` é um espaço reservado para `http://`. |
| `contains (path, operand)` | Verdadeiro se o atributo especificado por `path` for um dos seguintes: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Se o atributo especificado por `path` for `String`, o `operand` deve ser `String`. Se o atributo especificado por `path` for um `Set`, o `operand` deverá ser o tipo de elemento do conjunto. O caminho e o operando devem ser distintos. Isto é, `contains (a, a)` retorna um erro. Exemplo: verificar se o atributo `Brand` contém a substring `Company`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) O valor do atributo de expressão `:v_sub` é um espaço reservado para `Company`. Exemplo: verificar se o produto está disponível em vermelho. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) O valor do atributo de expressão `:v_sub` é um espaço reservado para `Red`. |
| `size (path)` | Retorna um número que representa o tamanho de um atributo. Veja a seguir os tipos de dados válidos para uso com `size`. Se o atributo for do tipo `String`, `size` retornará o comprimento da string. Exemplo: verificar se a string `Brand` é menor ou igual a 20 caracteres. O valor do atributo de expressão `:v_sub` é um espaço reservado para `20`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Se o atributo for do tipo `Binary`, `size` retornará o número de bytes no valor do atributo. Exemplo: suponha que o item de `ProductCatalog` tenha um atributo binário chamado `VideoClip`, que contém um curto vídeo sobre o produto em uso. A seguinte expressão verifica se `VideoClip` excede 64.000 bytes. O valor do atributo de expressão `:v_sub` é um espaço reservado para `64000`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Se o atributo for de um tipo de dados de `Set`, `size` retornará o número de elementos no conjunto. Exemplo: verificar se o produto está disponível em mais de uma cor. O valor do atributo de expressão `:v_sub` é um espaço reservado para `1`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Se o atributo for do tipo `List` ou `Map`, `size` retornará o número de elementos filho. Exemplo: verificar se o número de revisões `OneStar` excedeu um determinado limite. O valor do atributo de expressão `:v_sub` é um espaço reservado para `3`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) |
## Avaliações lógicas
Use as palavras-chave `AND`, `OR` e `NOT` para executar avaliações lógicas. Na lista a seguir, *a* e *b* representam condições a serem avaliadas.
+ `a AND b`: verdadeiro se *a* e *b* forem ambos verdadeiros.
+ `a OR b`: verdadeiro se *a* ou *b* ou ambos forem verdadeiros.
+ `NOT a`: verdadeiro se *a* for falso. Falso se *a* for verdadeiro.
Veja a seguir um exemplo de código de AND em uma operação.
`dynamodb-local (*)> select * from exprtest where a > 3 and a < 5;`
## Parênteses
Use parênteses para alterar a precedência de uma avaliação lógica. Por exemplo, suponha que as condições *a* e *b* sejam verdadeiras e que a condição *c* seja falsa. As expressões a seguir são avaliadas como verdadeiras:
+ `a OR b AND c`
No entanto, se você colocar uma condição entre parênteses, ela será avaliada primeiro. Por exemplo, o seguinte é avaliado como falso:
+ `(a OR b) AND c`
**nota**
Você pode aninhar parênteses em uma expressão. Os componentes mais internos são avaliados primeiro.
Veja a seguir um exemplo de código com parênteses em uma avaliação lógica.
`dynamodb-local (*)> select * from exprtest where attribute_type(b, string) or ( a = 5 and c = “coffee”);`
## Precedência em condições
O DynamoDB avalia as condições da esquerda para a direita usando as seguintes regras de precedência:
+ `= <> < <= > >=`
+ `IN`
+ `BETWEEN`
+ `attribute_exists attribute_not_exists begins_with contains`
+ Parênteses
+ `NOT`
+ `AND`
+ `OR`
# Exemplo de expressão de condição do DynamoDB na CLI
Veja a seguir alguns exemplos da AWS Command Line Interface (AWS CLI) para uso de expressões de condição. Estes exemplos se baseiam na tabela `ProductCatalog`, que foi apresentada em [Referir-se a atributos de item ao usar expressões no DynamoDB](Expressions.Attributes.md). A chave de partição dessa tabela é `Id`. Não há uma chave de classificação. A seguinte operação `PutItem` cria um item `ProductCatalog` de amostra ao qual os exemplos se referem.
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item file://item.json
```
Os argumentos de `--item` são armazenados no arquivo `item.json`. (Para simplificar, apenas alguns atributos de item são usados.)
```
{
"Id": {"N": "456" },
"ProductCategory": {"S": "Sporting Goods" },
"Price": {"N": "650" }
}
```
**Topics**
+ [Put condicional](#Expressions.ConditionExpressions.PreventingOverwrites)
+ [Exclusões condicionais](#Expressions.ConditionExpressions.AdvancedComparisons)
+ [Atualizações condicionais](#Expressions.ConditionExpressions.SimpleComparisons)
+ [Exemplos de expressão condicional](#Expressions.ConditionExpressions.ConditionalExamples)
## Put condicional
A operação `PutItem` substitui um item com a mesma chave primária (se houver). Se quiser evitar isso, use uma expressão de condição. Isso permitirá que a gravação continue apenas se o item em questão ainda não tiver a mesma chave primária.
O exemplo a seguir usa `attribute_not_exists()` para verificar se a chave primária existe na tabela antes de tentar a operação de gravação.
**nota**
Se a chave primária consistir em uma chave de partição (pk) e uma chave de classificação (sk), o parâmetro verificará se `attribute_not_exists(pk)` E `attribute_not_exists(sk)` são avaliados como uma declaração inteiramente verdadeira ou falsa antes de tentar a operação de gravação.
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item file://item.json \
--condition-expression "attribute_not_exists(Id)"
```
Se a expressão de condição for avaliada como falsa, o DynamoDB retornará uma mensagem de erro The conditional request failed (Falha na solicitação condicional).
**nota**
Para obter mais informações sobre `attribute_not_exists` e outras funções, consulte [Expressões de condição e filtro, operadores e funções no DynamoDB](Expressions.OperatorsAndFunctions.md).
## Exclusões condicionais
Para realizar uma exclusão condicional, use uma operação `DeleteItem` com uma expressão de condição. A expressão de condição deve ser avaliada como verdadeira para que a operação tenha êxito; caso contrário, haverá falha na operação.
Considere o item definido acima.
Suponha que você queira excluir o item, mas somente nas seguintes condições:
+ O valor de `ProductCategory` é “Sporting Goods” ou “Gardening Supplies”.
+ O valor de `Price` está entre 500 e 600.
O exemplo a seguir tenta excluir o item.
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"456"}}' \
--condition-expression "(ProductCategory IN (:cat1, :cat2)) and (Price between :lo and :hi)" \
--expression-attribute-values file://values.json
```
Os argumentos de `--expression-attribute-values` são armazenados no arquivo `values.json`.
```
{
":cat1": {"S": "Sporting Goods"},
":cat2": {"S": "Gardening Supplies"},
":lo": {"N": "500"},
":hi": {"N": "600"}
}
```
**nota**
Na expressão de condição, o caractere `:` (dois pontos) indica um *valor de atributo de expressão*: um espaço reservado para um valor real. Para obter mais informações, consulte [Usar valores de atributos de expressão no DynamoDB](Expressions.ExpressionAttributeValues.md).
Para obter mais informações sobre `IN`, `AND` e outras palavras-chave, consulte [Expressões de condição e filtro, operadores e funções no DynamoDB](Expressions.OperatorsAndFunctions.md).
Neste exemplo, a comparação `ProductCategory` é avaliada como true, mas a comparação `Price` é avaliada como false. Isso faz com que a expressão de condição seja avaliada como falsa e haja falha na operação `DeleteItem`.
## Atualizações condicionais
Para realizar uma atualização condicional, use uma operação `UpdateItem` com uma expressão de condição. A expressão de condição deve ser avaliada como verdadeira para que a operação tenha êxito. Caso contrário, haverá falha na operação.
**nota**
`UpdateItem` também oferece suporte a *expressões de atualização*, nas quais você especifica as modificações que deseja fazer em um item. Para obter mais informações, consulte [Usar expressões de atualização no DynamoDB](Expressions.UpdateExpressions.md).
Suponha que você tenha começado com o item definido acima.
O exemplo a seguir realiza uma operação `UpdateItem`. Ele tenta reduzir o `Price` de um produto em 75, mas a expressão de condição impedirá a atualização se o `Price` atual for menor ou igual a 500.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--update-expression "SET Price = Price - :discount" \
--condition-expression "Price > :limit" \
--expression-attribute-values file://values.json
```
Os argumentos de `--expression-attribute-values` são armazenados no arquivo `values.json`.
```
{
":discount": { "N": "75"},
":limit": {"N": "500"}
}
```
Se o valor inicial de `Price` for 650, a operação `UpdateItem` reduzirá o `Price` para 575. Se você executar a operação `UpdateItem` novamente, o valor de `Price` será reduzido para 500. Se você executá-la uma terceira vez, a expressão de condição será avaliada como falsa, e haverá falha na atualização.
**nota**
Na expressão de condição, o caractere `:` (dois pontos) indica um *valor de atributo de expressão*: um espaço reservado para um valor real. Para obter mais informações, consulte [Usar valores de atributos de expressão no DynamoDB](Expressions.ExpressionAttributeValues.md).
Para obter mais informações sobre "*>*" e outros operadores, consulte [Expressões de condição e filtro, operadores e funções no DynamoDB](Expressions.OperatorsAndFunctions.md).
## Exemplos de expressão condicional
Para obter mais informações sobre as funções usadas nos exemplos a seguir, consulte [Expressões de condição e filtro, operadores e funções no DynamoDB](Expressions.OperatorsAndFunctions.md). Se você quiser saber mais sobre como especificar diferentes tipos de atributo em uma expressão, consulte [Referir-se a atributos de item ao usar expressões no DynamoDB](Expressions.Attributes.md).
### Verificar atributos em um item
Você pode verificar a existência (ou inexistência) de qualquer atributo. Se a expressão da condição for avaliada como verdadeira, a operação terá êxito. Caso contrário, haverá falha.
O exemplo a seguir usa `attribute_not_exists` para excluir um produto apenas se ele não tiver um atributo `Price`.
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "attribute_not_exists(Price)"
```
O DynamoDB também fornece uma função `attribute_exists`. O exemplo a seguir excluirá um produto somente se ele tiver recebido revisões ruins.
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "attribute_exists(ProductReviews.OneStar)"
```
### Verificar tipo de atributo
É possível verificar o tipo de dados de um valor de atributo usando a função `attribute_type`. Se a expressão da condição for avaliada como verdadeira, a operação terá êxito. Caso contrário, haverá falha.
O exemplo a seguir usa `attribute_type` para excluir um produto somente se ele tiver um atributo `Color` do tipo Conjunto de strings.
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "attribute_type(Color, :v_sub)" \
--expression-attribute-values file://expression-attribute-values.json
```
Os argumentos de `--expression-attribute-values` são armazenados no arquivo expression-attribute-values.json.
```
{
":v_sub":{"S":"SS"}
}
```
### Verificar valor inicial da string
É possível verificar se um valor de atributo String começa com uma substring específica usando a função `begins_with`. Se a expressão da condição for avaliada como verdadeira, a operação terá êxito. Caso contrário, haverá falha.
O exemplo a seguir usará `begins_with` para excluir um produto somente se o elemento `FrontView` do mapa `Pictures` começar com um valor específico.
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "begins_with(Pictures.FrontView, :v_sub)" \
--expression-attribute-values file://expression-attribute-values.json
```
Os argumentos de `--expression-attribute-values` são armazenados no arquivo expression-attribute-values.json.
```
{
":v_sub":{"S":"http://"}
}
```
### Verificar um elemento em um conjunto
É possível verificar se há um elemento em um conjunto ou procurar uma substring em uma string usando a função `contains`. Se a expressão da condição for avaliada como verdadeira, a operação terá êxito. Caso contrário, haverá falha.
O exemplo a seguir usará `contains` para excluir um produto somente se o Conjunto de strings `Color` tiver um elemento com um valor específico.
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "contains(Color, :v_sub)" \
--expression-attribute-values file://expression-attribute-values.json
```
Os argumentos de `--expression-attribute-values` são armazenados no arquivo expression-attribute-values.json.
```
{
":v_sub":{"S":"Red"}
}
```
### Verificar o tamanho do valor de um atributo
É possível verificar o tamanho do valor de um atributo usando a função `size`. Se a expressão da condição for avaliada como verdadeira, a operação terá êxito. Caso contrário, haverá falha.
O exemplo a seguir usará `size` para excluir um produto somente se o tamanho do atributo binário `VideoClip` for maior que `64000` bytes.
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "size(VideoClip) > :v_sub" \
--expression-attribute-values file://expression-attribute-values.json
```
Os argumentos de `--expression-attribute-values` são armazenados no arquivo expression-attribute-values.json.
```
{
":v_sub":{"N":"64000"}
}
```