# Parâmetros condicionais legados do DynamoDB
Este documento oferece uma visão geral dos parâmetros condicionais herdados no DynamoDB e recomenda o uso dos novos parâmetros de expressão. Ele aborda detalhes sobre determinados parâmetros, como AttributesToGet, AttributeUpdates, ConditionalOperator, Expected, KeyConditions, QueryFilter e ScanFilter, e fornece exemplos de como usar os novos parâmetros de expressão como substitutos.
**Importante**
Sugerimos que você use os novos parâmetros de expressão, em vez desses parâmetros herdados. Para obter mais informações, consulte [Usar expressões no DynamoDB](Expressions.md).
Além disso, o DynamoDB não permite combinar parâmetros condicionais herdados e parâmetros de expressão em uma única chamada. Por exemplo, chamar a operação `Query` com `AttributesToGet` e `ConditionExpression` resultará em um erro.
A tabela a seguir mostra as operações de API do DynamoDB que ainda comportam esses parâmetros herdados e quais parâmetros de expressão devem ser usados. Esta tabela pode ser útil se você estiver considerando atualizar os aplicativos para que eles usem os parâmetros de expressão.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/LegacyConditionalParameters.html)
As seções a seguir oferecem mais informações sobre os parâmetros condicionais herdados.
**Topics**
+ [AttributesToGet (herdado)](LegacyConditionalParameters.AttributesToGet.md)
+ [AttributeUpdates (herdado)](LegacyConditionalParameters.AttributeUpdates.md)
+ [ConditionalOperator (herdado)](LegacyConditionalParameters.ConditionalOperator.md)
+ [Expected (herdado)](LegacyConditionalParameters.Expected.md)
+ [KeyConditions (herdado)](LegacyConditionalParameters.KeyConditions.md)
+ [QueryFilter (herdado)](LegacyConditionalParameters.QueryFilter.md)
+ [ScanFilter (herdado)](LegacyConditionalParameters.ScanFilter.md)
+ [Criar condições com parâmetros herdados](LegacyConditionalParameters.Conditions.md)
# AttributesToGet (herdado)
**nota**
Sugerimos que você use os novos parâmetros de expressão, em vez desses parâmetros herdados. Para obter mais informações, consulte [Usar expressões no DynamoDB](Expressions.md). Para obter informações específicas sobre o novo parâmetro que substitui este, [Use *ProjectionExpression* em vez disso](#ProjectionExpression.instead).
O parâmetro condicional herdado `AttributesToGet` é um conjunto de um ou mais atributos a serem recuperados do DynamoDB. Se os nomes de atributo não forem fornecidos, todos os atributos serão retornados. Se qualquer um dos atributos solicitados não for encontrado, ele não aparecerá no resultado.
`AttributesToGet` permite que você recupere atributos do tipo List ou Map; no entanto, ele não pode recuperar elementos individuais em uma lista ou um mapa.
Observe que `AttributesToGet` 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 um aplicativo.
## Use *ProjectionExpression* em vez disso: exemplo
Suponha que você quisesse recuperar um item da tabela *Music*, mas desejasse retornar somente alguns dos atributos. Você poderia usar uma solicitação `GetItem` com um parâmetro `AttributesToGet`, como neste exemplo da AWS CLI:
```
aws dynamodb get-item \
--table-name Music \
--attributes-to-get '["Artist", "Genre"]' \
--key '{
"Artist": {"S":"No One You Know"},
"SongTitle": {"S":"Call Me Today"}
}'
```
Você pode usar `ProjectionExpression` em vez disso:
```
aws dynamodb get-item \
--table-name Music \
--projection-expression "Artist, Genre" \
--key '{
"Artist": {"S":"No One You Know"},
"SongTitle": {"S":"Call Me Today"}
}'
```
# AttributeUpdates (herdado)
**nota**
Sugerimos que você use os novos parâmetros de expressão, em vez desses parâmetros herdados. Para obter mais informações, consulte [Usar expressões no DynamoDB](Expressions.md). Para obter informações específicas sobre o novo parâmetro que substitui este, [Use *UpdateExpression* em vez disso.](#UpdateExpression.instead).
Em uma operação `UpdateItem`, o parâmetro condicional herdado `AttributeUpdates` contém os nomes dos atributos a serem modificados, a ação a ser realizada em cada um e o novo valor de cada um. Se você estiver atualizando um atributo que é um atributo de chave de índice de quaisquer índices dessa tabela, o tipo de atributo deverá coincidir com o tipo de chave de índice definido na `AttributesDefinition` da descrição da tabela. Você pode usar `UpdateItem` para atualizar todos os atributos que não são chave.
Os valores de atributo não podem ser nulos. Os atributos do tipo String e Binary devem ter tamanhos maior que zero. Os atributos do tipo Set não podem ficar vazios. As solicitações com valores vazios serão rejeitadas com uma exceção `ValidationException`.
Cada elemento `AttributeUpdates` consiste em um nome de atributo a ser modificado, junto com o seguinte:
+ `Value` - O novo valor, se aplicável, desse atributo.
+ `Action`: um valor que especifica como executar a atualização. Essa ação só é válida para um atributo existente cujo tipo de dados é Number ou é Set; não use `ADD` para outros tipos de dados.
Se um item com a chave primária especificada for encontrado na tabela, os seguintes valores executam as ações a seguir:
+ `PUT`: adiciona o atributo especificado ao item. Se o atributo já existir, ele será substituído pelo novo valor.
+ `DELETE` - remove o atributo e o respectivo valor, se nenhum valor for especificado para `DELETE`. O tipo de dados do valor especificado deve corresponder ao tipo de dados do valor existente.
Se um conjunto de valores for especificado, esses valores serão subtraídos do conjunto antigo. Por exemplo, se o valor do atributo era o conjunto `[a,b,c]` e a ação `DELETE` especifica `[a,c]`, o valor do atributo final será `[b]`. Especificar um conjunto vazio é um erro.
+ `ADD`: adiciona o valor especificado ao item se o atributo ainda não existir. Se o atributo não existir, o comportamento de `ADD` dependerá do tipo de dados do atributo:
+ Se o atributo existente for um número e se `Value` também for um número, então `Value` será matematicamente adicionado ao atributo existente. Se `Value` for um número negativo, ele será subtraído do atributo existente.
**nota**
Se você usar `ADD` para aumentar ou reduzir um valor de número de um item que não existe antes da atualização, o DynamoDB usará 0 como o valor inicial.
Da mesma forma, se você usar `ADD` para um item existente para aumentar ou diminuir um valor de atributo que não existia antes da atualização, o DynamoDB usará `0` como o valor inicial. Por exemplo, suponha que o item que você deseja atualizar não tem um atributo chamado *itemcount*, mas você decide `ADD` o número `3` a esse atributo mesmo assim. O DynamoDB criará o atributo *itemcount*, definir seu valor inicial como `0` e, finalmente, adicionar `3` a ele. O resultado será um novo atributo *itemcount*, com um valor `3`.
+ Se o tipo de dados existente for um conjunto, e se `Value` também for um conjunto, então `Value` será anexado ao conjunto existente. Por exemplo, se o valor do atributo for o conjunto `[1,2]` e a ação `ADD` especificou `[3]`, o valor do atributo final será `[1,2,3]`. Ocorrerá um erro se uma ação `ADD` for especificada para um atributo de conjunto e o tipo de atributo especificado não corresponder ao tipo de conjunto existente.
Ambos os conjuntos devem ter o mesmo tipo de dados primitivo. Por exemplo, se o tipo de dados existente for um conjunto de strings, `Value` também deve ser um conjunto de strings.
Se nenhum item com a chave especificada for encontrado na tabela, os seguintes valores executam as ações a seguir:
+ `PUT` - faz com que o DynamoDB crie um novo item com a chave primária especificada e, em seguida, adiciona o atributo.
+ `DELETE`: nada acontece, pois os atributos não podem ser excluídos de um item inexistente. A operação é bem-sucedida, mas o DynamoDB não cria um novo item.
+ `ADD`: faz com que o DynamoDB crie um item com o número e a chave primária fornecidos (ou conjunto de números) para o valor de atributo. Os únicos tipos de dados permitidos são Number e Number Set.
Se você fornecer quaisquer atributos que sejam parte de uma chave de índice, então, os tipos de dados desses atributos devem corresponder aos do esquema na definição de atributo da tabela.
## Use *UpdateExpression* em vez disso: exemplo
Suponha que você quisesse modificar um item na tabela *Music*. Você poderia usar uma solicitação `UpdateItem` com um parâmetro `AttributeUpdates`, como neste exemplo da AWS CLI:
```
aws dynamodb update-item \
--table-name Music \
--key '{
"SongTitle": {"S":"Call Me Today"},
"Artist": {"S":"No One You Know"}
}' \
--attribute-updates '{
"Genre": {
"Action": "PUT",
"Value": {"S":"Rock"}
}
}'
```
Você pode usar `UpdateExpression` em vez disso:
```
aws dynamodb update-item \
--table-name Music \
--key '{
"SongTitle": {"S":"Call Me Today"},
"Artist": {"S":"No One You Know"}
}' \
--update-expression 'SET Genre = :g' \
--expression-attribute-values '{
":g": {"S":"Rock"}
}'
```
# ConditionalOperator (herdado)
**nota**
Sugerimos que você use os novos parâmetros de expressão, em vez desses parâmetros herdados. Para obter mais informações, consulte [Usar expressões no DynamoDB](Expressions.md).
O parâmetro condicional herdado `ConditionalOperator` é um operador lógico usado para ser aplicado às condições em um mapa `Expected`, `ScanFilter` ou `QueryFilter`:
+ AND – Se todas as condições forem avaliadas como verdadeiras, o mapa inteiro será avaliado como verdadeiro.
+ OR: se pelo menos uma das condições for avaliada como verdadeira, o mapa inteiro será avaliado como verdadeiro.
Se você omitir `ConditionalOperator`, então, `AND` será o padrão.
A operação será bem-sucedida somente se o mapa inteiro for avaliado como verdadeiro.
**nota**
Este parâmetro não tem suporte a atributos do tipo List ou Map.
# Expected (herdado)
**nota**
Sugerimos que você use os novos parâmetros de expressão, em vez desses parâmetros herdados. Para obter mais informações, consulte [Usar expressões no DynamoDB](Expressions.md). Para obter informações específicas sobre o novo parâmetro que substitui este, [Use *ConditionExpression* em vez disso.](#Expected.instead).
O parâmetro condicional herdado `Expected` é um bloco condicional para uma operação `UpdateItem`. `Expected` é um mapa de pares de atributo/condição. Cada elemento do mapa consiste em um nome de atributo, um operador de comparação e um ou mais valores. O DynamoDB compara o atributo com os valores que você forneceu usando o operador de comparação. Para cada elemento `Expected`, o resultado da avaliação é verdadeiro ou falso.
Se você especificar mais de um elemento no mapa `Expected`, por padrão, todas as condições deverão ser avaliadas como verdadeiras. Em outras palavras, as condições são combinadas usando o operador `AND`. (Em vez disso, você pode usar o parâmetro `ConditionalOperator` processar as condições com o operador OR. Se fizer isso, pelo menos uma das condições deverá ser avaliada como true, em vez de todas elas.)
Se o mapa `Expected` for avaliado como verdadeiro, a operação condicional será bem-sucedida; caso contrário, há uma falha.
`Expected` contém o seguinte:
+ `AttributeValueList`: um ou mais valores para avaliar em relação ao atributo fornecido. O número de valores na lista depende do `ComparisonOperator` que está sendo usado.
Para o tipo Number, as comparações de valor são numéricas.
As comparações de valor String para "maior que", "igual a" ou "menor que" são baseadas em Unicode com codificação UTF-8 binária. Por exemplo, `a` é maior que `A`, e `a` é maior que `B`.
Para o tipo Binary, o DynamoDB trata cada byte de dados binários como não assinados ao comparar valores binários.
+ `ComparisonOperator` - um comparador para avaliar atributos na `AttributeValueList`. Ao executar a comparação, o DynamoDB usa leituras fortemente consistentes.
Os seguintes operadores de comparação estão disponíveis:
`EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN`
Veja a seguir as descrições de cada operador de comparação.
+ `EQ`: igual. `EQ` é aceito por todos os tipos de dados, incluindo listas e mapas.
`AttributeValueList` pode conter apenas um elemento `AttributeValue` do tipo String, Number, Binary, String Set, Number Set ou Binary Set. Se um item contém um elemento `AttributeValue` de um tipo diferente do fornecido na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não é igual a `{"NS":["6", "2", "1"]}`.
+ `NE`: não é igual. `NE` é aceito por todos os tipos de dados, incluindo listas e mapas.
`AttributeValueList` pode conter apenas um `AttributeValue` do tipo String, Number, Binary, String Set, Number Set ou Binary Set. Se um item contém um `AttributeValue` de um tipo diferente do fornecido na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não é igual a `{"NS":["6", "2", "1"]}`.
+ `LE` : Menor ou igual a.
`AttributeValueList` pode conter apenas um elemento `AttributeValue` do tipo String, Number ou Binary (não um tipo Set). Se um item contém um elemento `AttributeValue` de um tipo diferente do fornecido na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não se compara a `{"NS":["6", "2", "1"]}`.
+ `LT` : Menor que.
`AttributeValueList` pode conter apenas um `AttributeValue` do tipo String, Number ou Binary (não um tipo Set). Se um item contém um elemento `AttributeValue` de um tipo diferente do fornecido na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não se compara a `{"NS":["6", "2", "1"]}`.
+ `GE` : Maior ou igual a.
`AttributeValueList` pode conter apenas um elemento `AttributeValue` do tipo String, Number ou Binary (não um tipo Set). Se um item contém um elemento `AttributeValue` de um tipo diferente do fornecido na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não se compara a `{"NS":["6", "2", "1"]}`.
+ `GT` : Maior que.
`AttributeValueList` pode conter apenas um elemento `AttributeValue` do tipo String, Number ou Binary (não um tipo Set). Se um item contém um elemento `AttributeValue` de um tipo diferente do fornecido na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não se compara a `{"NS":["6", "2", "1"]}`.
+ `NOT_NULL`: o atributo existe. `NOT_NULL` é aceito por todos os tipos de dados, incluindo listas e mapas.
**nota**
Este operador testa a existência de um atributo, não o tipo de dados. Se o tipo de dados do atributo "`a`" for nulo e você avaliá-lo usando `NOT_NULL`, o resultado será um Boolean `true`. Isso acontece porque o atributo "`a`" existe; o tipo de dados não é relevante para o operador de comparação `NOT_NULL`.
+ `NULL`: o atributo não existe. `NULL` é aceito por todos os tipos de dados, incluindo listas e mapas.
**nota**
Este operador testa a não existência de um atributo, e não seu tipo de dados. Se o tipo de dados do atributo "`a`" for nulo e você avaliá-lo usando `NULL`, o resultado será um Boolean `false`. Isso acontece porque o atributo "`a`" existe; o tipo de dados não é relevante para o operador de comparação `NULL`.
+ `CONTAINS` : verifica uma subsequência ou valor em um conjunto.
`AttributeValueList` pode conter apenas um elemento `AttributeValue` do tipo String, Number ou Binary (não um tipo Set). Se o atributo de destino da comparação for do tipo String, o operador procurará uma substring correspondente. Se o atributo de destino da comparação for do tipo Binary, o operador procurará uma subsequência do destino que corresponda à entrada. Se o atributo de destino da comparação for um conjunto ("`SS`", "`NS`" ou "`BS`"), o operador será avaliado como verdadeiro, se ele encontrar uma correspondência exata com qualquer membro do conjunto.
CONTAINS tem suporte em listas: ao avaliar "`a CONTAINS b`", " `a`" pode ser uma lista. No entanto, "`b`" não pode ser um conjunto, um mapa ou uma lista.
+ `NOT_CONTAINS` : verifica a ausência de uma subsequência ou a ausência de um valor em um conjunto.
`AttributeValueList` pode conter apenas um elemento `AttributeValue` do tipo String, Number ou Binary (não um tipo Set). Se o atributo de destino da comparação for String, o operador verificará a ausência de uma substring correspondente. Se o atributo de destino da comparação for Binary, o operador verificará a ausência de uma subsequência do destino que corresponda à entrada. Se o atributo de destino da comparação for um conjunto ("`SS`", "`NS`" ou "`BS`"), o operador será avaliado como verdadeiro se ele `does not` encontrar uma correspondência exata com qualquer membro do conjunto.
NOT\$1CONTAINS tem suporte em listas: ao avaliar "`a NOT CONTAINS b`", " `a`" pode ser uma lista. No entanto, "`b`" não pode ser um conjunto, um mapa ou uma lista.
+ `BEGINS_WITH` : procura um prefixo.
`AttributeValueList` pode conter apenas um elemento `AttributeValue` do tipo String ou Binary (não um tipo Number ou Set). O atributo de destino da comparação deve ser do tipo String ou Binary (e não Number ou um tipo de conjunto).
+ `IN` : procura elementos correspondentes dentro de dois conjuntos.
`AttributeValueList` pode conter um ou mais elementos `AttributeValue` do tipo String, Number ou Binary (não um tipo Set). Esses atributos são comparados com um atributo do tipo Set existente de um item. Se quaisquer elementos do conjunto de entradas estiverem presentes no atributo do item, a expressão será avaliada como verdadeira.
+ `BETWEEN` : maior ou igual ao primeiro valor e menor ou igual ao segundo valor.
`AttributeValueList` deve conter dois elementos `AttributeValue` do mesmo tipo, seja String, Number ou Binary (não um tipo Set). Um atributo de destino corresponderá se o valor de destino for maior que ou igual ao primeiro elemento e menor que ou igual ao segundo elemento. Se um item contém um elemento `AttributeValue` de um tipo diferente do fornecido na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não se compara a `{"N":"6"}`. Além disso, `{"N":"6"}` não se compara a `{"NS":["6", "2", "1"]}`
Os parâmetros a seguir podem ser usados em vez de `AttributeValueList` e `ComparisonOperator`:
+ `Value` - um valor para o DynamoDB comparar com um atributo.
+ `Exists` - um valor Booleano que faz com que o DynamoDB avalie o valor antes de tentar a operação condicional:
+ Se `Exists` for `true`, o DynamoDB verificará se esse valor de atributo já existe na tabela. Se ele for encontrado, a condição será avaliada como verdadeira; caso contrário, a condição será avaliada como falsa.
+ Se `Exists` for `false`, o DynamoDB assumirá que o valor do atributo `not` existe na tabela. Se, na verdade, o valor não existir, a suposição será válida e a condição será avaliada como verdadeira. Se o valor for encontrado, apesar da suposição de que ele não existe, a condição será avaliada como falsa.
Observe que o valor padrão para `Exists` é `true`.
Os parâmetros `Value` e `Exists` são incompatíveis com `AttributeValueList` e `ComparisonOperator`. Observe que se você usar os dois conjuntos de parâmetros de uma só vez, o DynamoDB retornará uma exceção `ValidationException`.
**nota**
Este parâmetro não tem suporte a atributos do tipo List ou Map.
## Use *ConditionExpression* em vez disso: exemplo
Suponha que você quisesse modificar um item na tabela *Music*, mas somente se uma determinada condição fosse verdadeira. Você poderia usar uma solicitação `UpdateItem` com um parâmetro `Expected`, como neste exemplo da AWS CLI:
```
aws dynamodb update-item \
--table-name Music \
--key '{
"Artist": {"S":"No One You Know"},
"SongTitle": {"S":"Call Me Today"}
}' \
--attribute-updates '{
"Price": {
"Action": "PUT",
"Value": {"N":"1.98"}
}
}' \
--expected '{
"Price": {
"ComparisonOperator": "LE",
"AttributeValueList": [ {"N":"2.00"} ]
}
}'
```
Você pode usar `ConditionExpression` em vez disso:
```
aws dynamodb update-item \
--table-name Music \
--key '{
"Artist": {"S":"No One You Know"},
"SongTitle": {"S":"Call Me Today"}
}' \
--update-expression 'SET Price = :p1' \
--condition-expression 'Price <= :p2' \
--expression-attribute-values '{
":p1": {"N":"1.98"},
":p2": {"N":"2.00"}
}'
```
# KeyConditions (herdado)
**nota**
Sugerimos que você use os novos parâmetros de expressão, em vez desses parâmetros herdados. Para obter mais informações, consulte [Usar expressões no DynamoDB](Expressions.md). Para obter informações específicas sobre o novo parâmetro que substitui este, [Use *KeyConditionExpression* em vez disso.](#KeyConditionExpression.instead).
O parâmetro condicional herdado `KeyConditions` contém critérios de seleção para uma operação `Query`. Para consultar uma tabela, você pode ter condições apenas em atributos de chave primária da tabela. Você deve fornecer o nome e o valor da chave de partição como uma condição `EQ`. Opcionalmente, você pode fornecer uma segunda condição, referente à chave de classificação.
**nota**
Se você não fornecer uma condição de chave de classificação, todos os itens que correspondem à chave de partição serão recuperados. Se `FilterExpression` ou `QueryFilter` estiver presente, isso será aplicado depois que os itens forem recuperados.
Para consultar um índice, você pode ter condições apenas em atributos da chave do índice. Você deve fornecer o nome e o valor da chave de partição do índice como uma condição `EQ`. Opcionalmente, você pode fornecer uma segunda condição, referente à chave de classificação do índice.
Cada elemento `KeyConditions` consiste em um nome de atributo a ser comparado, junto com o seguinte:
+ `AttributeValueList`: um ou mais valores para avaliar em relação ao atributo fornecido. O número de valores na lista depende do `ComparisonOperator` que está sendo usado.
Para o tipo Number, as comparações de valor são numéricas.
As comparações de valor String para "maior que", "igual a" ou "menor que" são baseadas em Unicode com codificação UTF-8 binária. Por exemplo, `a` é maior que `A`, e `a` é maior que `B`.
Para Binary, o DynamoDB trata cada byte de dados binários como não assinados ao comparar valores binários.
+ `ComparisonOperator`: um comparador para avaliar atributos. Por exemplo: é igual a, maior que e, menor que.
Para `KeyConditions`, somente os seguintes operadores de comparação têm suporte:
`EQ | LE | LT | GE | GT | BEGINS_WITH | BETWEEN`
Veja a seguir as descrições desses operadores de comparação.
+ `EQ` : Igual.
`AttributeValueList` pode conter apenas um `AttributeValue` do tipo String, Number ou Binary (não um tipo Set). Se um item contém um elemento `AttributeValue` de um tipo diferente do especificado na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não é igual a `{"NS":["6", "2", "1"]}`.
+ `LE` : Menor ou igual a.
`AttributeValueList` pode conter apenas um elemento `AttributeValue` do tipo String, Number ou Binary (não um tipo Set). Se um item contém um elemento `AttributeValue` de um tipo diferente do fornecido na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não se compara a `{"NS":["6", "2", "1"]}`.
+ `LT` : Menor que.
`AttributeValueList` pode conter apenas um `AttributeValue` do tipo String, Number ou Binary (não um tipo Set). Se um item contém um elemento `AttributeValue` de um tipo diferente do fornecido na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não se compara a `{"NS":["6", "2", "1"]}`.
+ `GE` : Maior ou igual a.
`AttributeValueList` pode conter apenas um elemento `AttributeValue` do tipo String, Number ou Binary (não um tipo Set). Se um item contém um elemento `AttributeValue` de um tipo diferente do fornecido na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não se compara a `{"NS":["6", "2", "1"]}`.
+ `GT` : Maior que.
`AttributeValueList` pode conter apenas um elemento `AttributeValue` do tipo String, Number ou Binary (não um tipo Set). Se um item contém um elemento `AttributeValue` de um tipo diferente do fornecido na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não se compara a `{"NS":["6", "2", "1"]}`.
+ `BEGINS_WITH` : procura um prefixo.
`AttributeValueList` pode conter apenas um elemento `AttributeValue` do tipo String ou Binary (não um tipo Number ou Set). O atributo de destino da comparação deve ser do tipo String ou Binary (e não Number ou um tipo de conjunto).
+ `BETWEEN` : maior ou igual ao primeiro valor e menor ou igual ao segundo valor.
`AttributeValueList` deve conter dois elementos `AttributeValue` do mesmo tipo, seja String, Number ou Binary (não um tipo Set). Um atributo de destino corresponderá se o valor de destino for maior que ou igual ao primeiro elemento e menor que ou igual ao segundo elemento. Se um item contém um elemento `AttributeValue` de um tipo diferente do fornecido na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não se compara a `{"N":"6"}`. Além disso, `{"N":"6"}` não se compara a `{"NS":["6", "2", "1"]}`.
## Use *KeyConditionExpression* em vez disso: exemplo
Suponha que você quisesse recuperar vários itens com a mesma chave de partição da tabela *Music*. Você poderia usar uma solicitação `Query` com um parâmetro `KeyConditions`, como neste exemplo da AWS CLI:
```
aws dynamodb query \
--table-name Music \
--key-conditions '{
"Artist":{
"ComparisonOperator":"EQ",
"AttributeValueList": [ {"S": "No One You Know"} ]
},
"SongTitle":{
"ComparisonOperator":"BETWEEN",
"AttributeValueList": [ {"S": "A"}, {"S": "M"} ]
}
}'
```
Você pode usar `KeyConditionExpression` em vez disso:
```
aws dynamodb query \
--table-name Music \
--key-condition-expression 'Artist = :a AND SongTitle BETWEEN :t1 AND :t2' \
--expression-attribute-values '{
":a": {"S": "No One You Know"},
":t1": {"S": "A"},
":t2": {"S": "M"}
}'
```
# QueryFilter (herdado)
**nota**
Sugerimos que você use os novos parâmetros de expressão, em vez desses parâmetros herdados. Para obter mais informações, consulte [Usar expressões no DynamoDB](Expressions.md). Para obter informações específicas sobre o novo parâmetro que substitui este, [Use *FilterExpression* em vez disso.](#FilterExpression.instead).
Em uma operação `Query`, parâmetro condicional herdado `QueryFilter` é uma condição que avalia os resultados da consulta depois que os itens são lidos e retorna apenas os valores desejados.
Este parâmetro não tem suporte a atributos do tipo List ou Map.
**nota**
Um `QueryFilter` é aplicado depois que os itens já foram lidos, o processo de filtragem não consome unidades de capacidade de leitura adicionais.
Se você fornecer mais de uma condição no mapa `QueryFilter`, por padrão, todas as condições deverão ser avaliadas como verdadeiras. Em outras palavras, as condições são combinadas usando o operador `AND`. (Em vez disso, você pode usar o parâmetro [ConditionalOperator (herdado)](LegacyConditionalParameters.ConditionalOperator.md) processar as condições com o operador OR. Se fizer isso, pelo menos uma das condições deverá ser avaliada como true, em vez de todas elas.)
Observe que `QueryFilter` não permite atributos de chave. Você não pode definir uma condição de filtro em uma chave de partição ou uma chave de classificação.
Cada elemento `QueryFilter` consiste em um nome de atributo a ser comparado, junto com o seguinte:
+ `AttributeValueList`: um ou mais valores para avaliar em relação ao atributo fornecido. O número de valores na lista depende do operador especificado em `ComparisonOperator`.
Para o tipo Number, as comparações de valor são numéricas.
As comparações de valor String para "maior que", "igual a" ou "menor que" são baseadas em codificação UTF-8 binária. Por exemplo, `a` é maior que `A`, e `a` é maior que `B`.
Para o tipo Binary, o DynamoDB trata cada byte de dados binários como não assinados ao comparar valores binários.
Para obter mais informações sobre como especificar tipos de dados em JSON, consulte [API de baixo nível do DynamoDB](Programming.LowLevelAPI.md).
+ `ComparisonOperator`: um comparador para avaliar atributos. Por exemplo: é igual a, maior que e, menor que.
Os seguintes operadores de comparação estão disponíveis:
`EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN`
## Use *FilterExpression* em vez disso: exemplo
Suponha que você quisesse consultar a tabela *Music* e aplicar uma condição aos itens correspondentes. Você poderia usar uma solicitação `Query` com um parâmetro `QueryFilter`, como neste exemplo da AWS CLI:
```
aws dynamodb query \
--table-name Music \
--key-conditions '{
"Artist": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"S": "No One You Know"} ]
}
}' \
--query-filter '{
"Price": {
"ComparisonOperator": "GT",
"AttributeValueList": [ {"N": "1.00"} ]
}
}'
```
Você pode usar `FilterExpression` em vez disso:
```
aws dynamodb query \
--table-name Music \
--key-condition-expression 'Artist = :a' \
--filter-expression 'Price > :p' \
--expression-attribute-values '{
":p": {"N":"1.00"},
":a": {"S":"No One You Know"}
}'
```
# ScanFilter (herdado)
**nota**
Sugerimos que você use os novos parâmetros de expressão, em vez desses parâmetros herdados. Para obter mais informações, consulte [Usar expressões no DynamoDB](Expressions.md). Para obter informações específicas sobre o novo parâmetro que substitui este, [Use *FilterExpression* em vez disso.](#FilterExpression2.instead).
Em uma operação `Scan`, o parâmetro condicional herdado `ScanFilter` é uma condição que avalia os resultados da verificação e retorna apenas os valores desejados.
**nota**
Este parâmetro não tem suporte a atributos do tipo List ou Map.
Se você especificar mais de uma condição no mapa `ScanFilter`, por padrão, todas as condições deverão ser avaliadas como verdadeiras. Em outras palavras, as condições são processadas com o operador AND. (Em vez disso, você pode usar o parâmetro [ConditionalOperator (herdado)](LegacyConditionalParameters.ConditionalOperator.md) processar as condições com o operador OR. Se fizer isso, pelo menos uma das condições deverá ser avaliada como true, em vez de todas elas.)
Cada elemento `ScanFilter` consiste em um nome de atributo a ser comparado, junto com o seguinte:
+ `AttributeValueList`: um ou mais valores para avaliar em relação ao atributo fornecido. O número de valores na lista depende do operador especificado em `ComparisonOperator` .
Para o tipo Number, as comparações de valor são numéricas.
As comparações de valor String para "maior que", "igual a" ou "menor que" são baseadas em codificação UTF-8 binária. Por exemplo, `a` é maior que `A`, e `a` é maior que `B`.
Para Binary, o DynamoDB trata cada byte de dados binários como não assinados ao comparar valores binários.
Para obter mais informações sobre como especificar tipos de dados em JSON, consulte [API de baixo nível do DynamoDB](Programming.LowLevelAPI.md).
+ `ComparisonOperator`: um comparador para avaliar atributos. Por exemplo: é igual a, maior que e, menor que.
Os seguintes operadores de comparação estão disponíveis:
`EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN`
## Use *FilterExpression* em vez disso: exemplo
Suponha que você quisesse examinar a tabela *Music* e aplicar uma condição aos itens correspondentes. Você poderia usar uma solicitação `Scan` com um parâmetro `ScanFilter`, como neste exemplo da AWS CLI:
```
aws dynamodb scan \
--table-name Music \
--scan-filter '{
"Genre":{
"AttributeValueList":[ {"S":"Rock"} ],
"ComparisonOperator": "EQ"
}
}'
```
Você pode usar `FilterExpression` em vez disso:
```
aws dynamodb scan \
--table-name Music \
--filter-expression 'Genre = :g' \
--expression-attribute-values '{
":g": {"S":"Rock"}
}'
```
# Criar condições com parâmetros herdados
**nota**
Sugerimos que você use os novos parâmetros de expressão, em vez desses parâmetros herdados. Para obter mais informações, consulte [Usar expressões no DynamoDB](Expressions.md).
A seção a seguir descreve como criar condições a serem usadas com parâmetros herdados, como `Expected`, `QueryFilter` e `ScanFilter`.
**nota**
Em vez disso, as novas aplicações devem usar parâmetros de expressão. Para obter mais informações, consulte [Usar expressões no DynamoDB](Expressions.md).
## Condições simples
Com valores de atributo, você pode escrever condições para comparações com atributos da tabela. Uma condição sempre é avaliada como verdadeira ou falsa, e consiste em:
+ `ComparisonOperator` - maior que, menor que, igual a e assim por diante.
+ `AttributeValueList` (opcional): valores de atributo para comparar. Dependendo do `ComparisonOperator` que está sendo usado, `AttributeValueList` pode conter um, dois ou mais valores ou pode não estar presente.
As seções a seguir descrevem os vários operadores de comparação, juntamente com exemplos de como usá-los em condições.
### Operadores de comparação sem valores de atributo
+ `NOT_NULL` - verdadeiro se um atributo existir.
+ `NULL` - verdadeiro se um atributo não existir.
Use esses operadores para verificar se um atributo existe ou não. Como não há valor de comparação, não especifique `AttributeValueList`.
**Exemplo**
A expressão a seguir é avaliada como verdadeira se o atributo *Dimensions* existir.
```
...
"Dimensions": {
ComparisonOperator: "NOT_NULL"
}
...
```
### Operadores de comparação com um valor de atributo
+ `EQ` - verdadeiro se um atributo for igual a um valor.
`AttributeValueList` pode conter apenas um valor do tipo String, Number, Binary, String Set, Number Set ou Binary Set. Se um item contém um valor de um tipo diferente do especificado na solicitação, os valores não coincidem. Por exemplo, a string `"3"` não é igual ao número `3`. Além disso, o número `3` não é igual ao conjunto de números `[3, 2, 1]`.
+ `NE` - verdadeiro se um atributo não for igual a um valor.
`AttributeValueList` pode conter apenas um valor do tipo String, Number, Binary, String Set, Number Set ou Binary Set. Se um item contém um valor de um tipo diferente do especificado na solicitação, os valores não coincidem.
+ `LE` - verdadeiro se um atributo for menor ou igual a um valor.
`AttributeValueList` pode conter apenas um valor do tipo String, Number ou Binary (não um tipo Set). Se um item contém um `AttributeValue` de um valor diferente do especificado na solicitação, os valores não coincidem.
+ `LT` - verdadeiro se um atributo for menor que um valor.
`AttributeValueList` pode conter apenas um valor do tipo String, Number ou Binary (não um tipo Set). Se um item contém um valor de um tipo diferente do especificado na solicitação, os valores não coincidem.
+ `GE` - verdadeiro se um atributo for maior ou igual a um valor.
`AttributeValueList` pode conter apenas um valor do tipo String, Number ou Binary (não um tipo Set). Se um item contém um valor de um tipo diferente do especificado na solicitação, os valores não coincidem.
+ `GT` - verdadeiro se um atributo é maior que um valor.
`AttributeValueList` pode conter apenas um valor do tipo String, Number ou Binary (não um tipo Set). Se um item contém um valor de um tipo diferente do especificado na solicitação, os valores não coincidem.
+ `CONTAINS` - verdadeiro se um valor estiver presente em um conjunto ou se um valor contiver outro.
`AttributeValueList` pode conter apenas um valor do tipo String, Number ou Binary (não um tipo Set). Se o atributo de destino da comparação for String, o operador procurará uma substring correspondente. Se o atributo de destino da comparação for Binary, o operador procurará uma subsequência do destino que corresponda à entrada. Se o atributo de destino da comparação for um conjunto, o operador será avaliado como verdadeiro caso encontre uma correspondência exata com qualquer membro do conjunto.
+ `NOT_CONTAINS` - verdadeiro se um valor *não* estiver presente em um conjunto, ou se um valor não contiver outro valor.
`AttributeValueList` pode conter apenas um valor do tipo String, Number ou Binary (não um tipo Set). Se o atributo de destino da comparação for String, o operador verificará a ausência de uma substring correspondente. Se o atributo de destino da comparação for Binary, o operador verificará a ausência de uma subsequência do destino que corresponda à entrada. Se o atributo de destino da comparação for um conjunto, o operador será avaliado como verdadeiro se ele *não* encontrar uma correspondência exata com qualquer membro do conjunto.
+ `BEGINS_WITH`: verdadeiro se os primeiros caracteres de um atributo corresponderem ao valor fornecido. Não use este operador para comparar números.
`AttributeValueList` pode conter apenas um valor do tipo String ou Binary (não um tipo Number ou Set). O atributo de destino da comparação deve ser String ou Binary (não Number ou um conjunto).
Use esses operadores para comparar um atributo com um valor. Você deve especificar um `AttributeValueList` consistindo em um único valor. Para a maioria dos operadores, esse valor deve ser escalar. No entanto, os operadores `EQ` e `NE` também dão suporte a conjuntos.
**Exemplos**
As expressões a seguir serão avaliadas como verdadeiras se:
+ O preço de um produto for maior que 100.
```
...
"Price": {
ComparisonOperator: "GT",
AttributeValueList: [ {"N":"100"} ]
}
...
```
+ A categoria de um produto começar com "Bo".
```
...
"ProductCategory": {
ComparisonOperator: "BEGINS_WITH",
AttributeValueList: [ {"S":"Bo"} ]
}
...
```
+ Um produto estiver disponível em vermelho, verde ou preto:
```
...
"Color": {
ComparisonOperator: "EQ",
AttributeValueList: [
[ {"S":"Black"}, {"S":"Red"}, {"S":"Green"} ]
]
}
...
```
**nota**
Ao comparar tipos de dados Set, a ordem dos elementos não importa. O DynamoDB retornará apenas os itens com o mesmo conjunto de valores, independentemente da ordem em que você especificá-los em sua solicitação.
### Operadores de comparação com dois valores de atributo
+ `BETWEEN` - verdadeiro se um valor for entre um limite inferior e um limite superior, inclusive endpoints.
`AttributeValueList` deve conter dois elementos do mesmo tipo, seja String, Number ou Binary (não Set). Um atributo de destino corresponderá se o valor de destino for maior que ou igual ao primeiro elemento e menor que ou igual ao segundo elemento. Se um item contém um valor de um tipo diferente do especificado na solicitação, os valores não coincidem.
Use este operador para determinar se um valor de atributo está dentro de um intervalo. A `AttributeValueList` deve conter dois elementos escalares do mesmo tipo – String, Number ou Binary.
**Exemplo**
A expressão a seguir será avaliada como verdadeira, se o preço de um produto estiver entre 100 e 200.
```
...
"Price": {
ComparisonOperator: "BETWEEN",
AttributeValueList: [ {"N":"100"}, {"N":"200"} ]
}
...
```
### Operadores de comparação com *n* valores de atributo
+ `IN`: verdadeiro se um valor for igual a qualquer um dos valores em uma lista enumerada. Somente valores escalares são aceitos na lista, mas não conjuntos. O atributo de destino deve ser do mesmo tipo e o valor exato para corresponder.
`AttributeValueList` pode conter um ou mais elementos do tipo String, Number ou Binary (não um tipo Set). Esses atributos são comparados com um atributo do tipo que não é Set existente de um item. Se *quaisquer* elementos do conjunto de entradas estiverem presentes no atributo do item, a expressão será avaliada como verdadeira.
`AttributeValueList` pode conter um ou mais valores do tipo String, Number ou Binary (não um tipo Set). O atributo de destino da comparação deve ser do mesmo tipo e ter o valor exato para corresponder. Um atributo String nunca corresponde a um String set.
Use este operador para determinar se o valor fornecido está em uma lista enumerada. Você pode especificar qualquer número de valores escalares em `AttributeValueList`, mas todos eles devem ser do mesmo tipo de dados.
**Exemplo**
A expressão a seguir será avaliada como verdadeira se o valor para *Id* for 201, 203 ou 205.
```
...
"Id": {
ComparisonOperator: "IN",
AttributeValueList: [ {"N":"201"}, {"N":"203"}, {"N":"205"} ]
}
...
```
## Uso de várias condições
O DynamoDB permite combinar várias condições para formar expressões complexas. Isso é feito ao fornecer pelo menos duas expressões, com um opcional [ConditionalOperator (herdado)](LegacyConditionalParameters.ConditionalOperator.md).
Por padrão, quando você especifica mais de uma condição, *todas* as condições devem ser avaliadas como verdadeiras para que a expressão inteira também seja avaliada assim. Em outras palavras, uma operação *AND* implícita acontece.
**Exemplo**
A expressão a seguir será avaliada como verdadeira se um produto for um livro que tem 600 páginas, pelo menos. Ambas as condições devem ser avaliadas como verdadeiras, já que elas são implicitamente *AND*ed (associadas).
```
...
"ProductCategory": {
ComparisonOperator: "EQ",
AttributeValueList: [ {"S":"Book"} ]
},
"PageCount": {
ComparisonOperator: "GE",
AttributeValueList: [ {"N":600"} ]
}
...
```
Você pode usar [ConditionalOperator (herdado)](LegacyConditionalParameters.ConditionalOperator.md) para esclarecer que uma operação *AND* acontecerá. O exemplo a seguir se comporta da mesma forma que o anterior.
```
...
"ConditionalOperator" : "AND",
"ProductCategory": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"N":"Book"} ]
},
"PageCount": {
"ComparisonOperator": "GE",
"AttributeValueList": [ {"N":600"} ]
}
...
```
Você também pode definir `ConditionalOperator` como *OR*, o que significa que *pelo menos uma* das condições deve ser avaliada como verdadeira.
**Exemplo**
A expressão a seguir será avaliada como verdadeira, se um produto for uma mountain bike, se ele for de uma marca específica ou se o preço for maior que 100.
```
...
ConditionalOperator : "OR",
"BicycleType": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"S":"Mountain" ]
},
"Brand": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"S":"Brand-Company A" ]
},
"Price": {
"ComparisonOperator": "GT",
"AttributeValueList": [ {"N":"100"} ]
}
...
```
**nota**
Em uma expressão complexa, as condições são processadas na ordem, da primeira condição para a última.
Não é possível usar AND e OR em uma única expressão.
## Outros operadores condicionais
Em versões anteriores do DynamoDB, o parâmetro `Expected` se comportava de forma diferente em gravações condicionais. Cada item no mapa `Expected` representava um nome de atributo para o DynamoDB verificar, juntamente com o seguinte:
+ `Value` - um valor para comparar com o atributo.
+ `Exists` - determina se o valor existe antes de tentar a operação.
As opções `Value` e `Exists` continuam a ter suporte no DynamoDB; no entanto, elas só permitem que você teste uma condição de igualdade ou se um atributo existe. Recomendamos que você use `ComparisonOperator` e `AttributeValueList` em vez disso, pois essas opções permitem que você crie uma gama muito maior de condições.
**Example**
Uma operação `DeleteItem` pode verificar se um livro não está mais em publicação e excluí-lo somente se essa condição for verdadeira. Veja um exemplo da AWS CLI que usa uma condição herdada:
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{
"Id": {"N":"600"}
}' \
--expected '{
"InPublication": {
"Exists": true,
"Value": {"BOOL":false}
}
}'
```
O exemplo a seguir executa a mesma ação, mas não usa uma condição herdada:
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{
"Id": {"N":"600"}
}' \
--expected '{
"InPublication": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"BOOL":false} ]
}
}'
```
**Example**
Uma operação `PutItem` pode proteger contra a substituição de um item existente com os mesmos atributos da chave primária. Veja um exemplo que usa uma condição herdada:
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item '{
"Id": {"N":"500"},
"Title": {"S":"Book 500 Title"}
}' \
--expected '{
"Id": { "Exists": false }
}'
```
O exemplo a seguir executa a mesma ação, mas não usa uma condição herdada:
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item '{
"Id": {"N":"500"},
"Title": {"S":"Book 500 Title"}
}' \
--expected '{
"Id": { "ComparisonOperator": "NULL" }
}'
```
**nota**
Para condições no mapa `Expected`, não use as opções herdadas `Value` e `Exists` com `ComparisonOperator` e `AttributeValueList`. Se você fizer isso, sua gravação condicional falhará.