# Parámetros condicionales de DynamoDB heredados
En este documento se proporciona información general de los parámetros condicionales heredados de DynamoDB y se recomienda utilizar los nuevos parámetros de expresión en su lugar. Incluye detalles sobre parámetros como AttributeToGet, AttributeUpdates, ConditionalOperator, Expected, KeyConditions, QueryFilter y ScanFilter, y proporciona ejemplos de cómo utilizar los nuevos parámetros de expresión como sustitutos.
**importante**
Le recomendamos que utilice los nuevos parámetros de expresión en lugar de estos parámetros heredados siempre que sea posible. Para obtener más información, consulte [Uso de expresiones en DynamoDB](Expressions.md).
Además, DynamoDB no permite mezclar parámetros condicionales heredados con parámetros de expresión en una misma llamada. Por ejemplo, llamar a la operación `Query` con `AttributesToGet` y `ConditionExpression` dará lugar a un error.
En la siguiente tabla se muestran las operaciones de la API de DynamoDB que todavía admiten estos parámetros heredados, así como los parámetros de expresión que deben utilizarse en su lugar. Esta tabla puede resultarle útil si va a actualizar las aplicaciones de tal forma que utilicen parámetros de expresión a partir de ahora.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/LegacyConditionalParameters.html)
En las secciones siguientes se proporciona más información acerca de los parámetros condicionales heredados.
**Topics**
+ [AttributesToGet (heredado)](LegacyConditionalParameters.AttributesToGet.md)
+ [AttributeUpdates (heredado)](LegacyConditionalParameters.AttributeUpdates.md)
+ [ConditionalOperator (heredado)](LegacyConditionalParameters.ConditionalOperator.md)
+ [Expected (heredado)](LegacyConditionalParameters.Expected.md)
+ [KeyConditions (heredado)](LegacyConditionalParameters.KeyConditions.md)
+ [QueryFilter (heredado)](LegacyConditionalParameters.QueryFilter.md)
+ [ScanFilter (heredado)](LegacyConditionalParameters.ScanFilter.md)
+ [Escritura de condiciones con parámetros heredados](LegacyConditionalParameters.Conditions.md)
# AttributesToGet (heredado)
**nota**
Le recomendamos que utilice los nuevos parámetros de expresión en lugar de estos parámetros heredados siempre que sea posible. Para obtener más información, consulte [Uso de expresiones en DynamoDB](Expressions.md). Para obtener información específica sobre el nuevo parámetro que reemplaza a este, [Use *ProjectionExpression* en su lugar](#ProjectionExpression.instead).
El parámetro condicional heredado `AttributesToGet` es una matriz de uno o varios atributos que se recuperan de DynamoDB. Si no se proporcionan sus nombres, se devuelven todos los atributos. Si cualquiera de los atributos solicitados no se encuentra, no aparecerá en el resultado.
`AttributesToGet` permite recuperar atributos de tipo List o Map; sin embargo, no puede recuperar entradas individuales dentro de una lista o un mapa.
Tenga en cuenta que `AttributesToGet` no modifica el consumo de rendimiento aprovisionado. DynamoDB determina las unidades de capacidad de lectura consumidas según el tamaño de los elementos y no según la cantidad de datos que se devuelven a la aplicación.
## Use *ProjectionExpression* en su lugar; ejemplo
Supongamos que desea recuperar un elemento de la tabla *Music*, pero no devolverlo completo, sino solo algunos de los atributos. Podría usar una solicitud `GetItem` con un parámetro `AttributesToGet` como en este ejemplo de la 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"}
}'
```
Puede utilizar `ProjectionExpression` en su lugar:
```
aws dynamodb get-item \
--table-name Music \
--projection-expression "Artist, Genre" \
--key '{
"Artist": {"S":"No One You Know"},
"SongTitle": {"S":"Call Me Today"}
}'
```
# AttributeUpdates (heredado)
**nota**
Le recomendamos que utilice los nuevos parámetros de expresión en lugar de estos parámetros heredados siempre que sea posible. Para obtener más información, consulte [Uso de expresiones en DynamoDB](Expressions.md). Para obtener información específica sobre el nuevo parámetro que reemplaza a este, [Use *UpdateExpression* en su lugar.](#UpdateExpression.instead).
En una operación `UpdateItem`, el parámetro condicional heredado `AttributeUpdates` contiene los nombres de los atributos que se van a modificar, su nombre, la acción que se va a llevar a cabo y su nuevo valor. Si va a actualizar un atributo de clave de índice de alguno de los índices de esa tabla, el tipo de atributo debe coincidir con el tipo de clave de índice definido en el elemento `AttributesDefinition` de la descripción de la tabla. Puede utilizar `UpdateItem` para actualizar los atributos sin clave.
Los valores de los atributos no pueden ser null. La longitud de los atributos de tipo String (cadena) y Binary (binario) debe ser mayor que cero. Los atributos de tipo Set (conjunto) no pueden estar vacíos. Las solicitudes con valores vacíos se rechazan con la excepción `ValidationException`.
Cada entrada `AttributeUpdates` consta de un nombre de atributo que se va a modificar, junto con lo siguiente:
+ `Value`: el nuevo valor, si procede, de este atributo.
+ `Action`: un valor que especifica cómo llevar a cabo la actualización. Esta acción solo es válida para un atributo existente cuyo tipo de datos sea Number o que sea un conjunto; no use `ADD` con otros tipos de datos.
Si se encuentra en la tabla un elemento con la clave principal especificada, los valores siguientes llevan a cabo estas acciones:
+ `PUT`: añade el atributo especificado al elemento. Si el atributo ya existe, se sustituye por el nuevo valor.
+ `DELETE` - elimina el atributo y su valor, si no se ha especificado ningún valor para `DELETE`. El tipo de datos del valor especificado debe coincidir con el tipo de datos del valor existente.
Si se especifica un conjunto de valores, entonces esos valores se restarán del conjunto anterior. Por ejemplo, si el valor de atributo era el conjunto `[a,b,c]` y la acción `DELETE` especifica `[a,c]`, entonces el valor final del atributo es `[b]`. Especificar un conjunto vacío es un error.
+ `ADD`: si el atributo aún no existe, añade el valor especificado al elemento. Si el atributo existe, el comportamiento de `ADD` depende del tipo de datos del atributo:
+ Si el atributo existente es un número y `Value` también es un número, entonces `Value` se suma matemáticamente al atributo existente. Si `Value` es un número negativo, entonces se resta del atributo existente.
**nota**
Si utiliza `ADD` para sumar o restar de un valor numérico de un elemento que no existía antes de la actualización, DynamoDB utilizará 0 como valor inicial.
De igual forma, si utiliza `ADD` con un elemento existente para sumar o restar de un valor de un atributo que no existía antes de la actualización, DynamoDB utilizará `0` como valor inicial. Por ejemplo, supongamos que el elemento que desea actualizar no tiene un atributo denominado *itemcount*, pero que, a pesar de ello, usted decide aplicar `ADD` para sumar `3` a este atributo. DynamoDB creará el atributo *itemcount*, establecerá su valor inicial en `0` y, por último, le sumará `3`. El resultado será un nuevo atributo *itemcount*, cuyo valor será `3`.
+ Si el tipo de datos existente es un conjunto y, además, `Value` también es un conjunto, `Value` se adjunta al conjunto existente. Por ejemplo, si el valor del atributo es el conjunto `[1,2]` y la acción `ADD` especifica `[3]`, entonces el valor final del atributo es `[1,2,3]`. Se produce un error si se especifica una acción `ADD` para un atributo de tipo Set y el tipo de atributo especificado no coincide con el tipo de conjunto existente.
Ambos conjuntos deben tener el mismo tipo de datos primitivo. Por ejemplo, si el tipo de datos existente es un conjunto de cadenas, `Value` también debe ser un conjunto de cadenas.
Si no se encuentra en la tabla ningún elemento con la clave especificada, los valores siguientes llevan a cabo estas acciones:
+ `PUT`: hace que DynamoDB cree un nuevo elemento con la clave principal especificada y, a continuación, agrega el atributo.
+ `DELETE`: no sucede nada, porque no se pueden eliminar los atributos de un elemento que no existe. La operación se lleva a cabo, pero DynamoDB no crea ningún elemento nuevo.
+ `ADD`: hace que DynamoDB cree un elemento con la clave principal y el número (o el conjunto de números) suministrados para el valor del atributo. Los únicos tipos de datos permitidos son Number y Number Set.
Si proporciona atributos que forman parte de una clave de índice, entonces los tipos de datos de tales atributos deberán coincidir con los del esquema de la definición de atributos de la tabla.
## Use *UpdateExpression* en su lugar; ejemplo
Supongamos que desea modificar un elemento de la tabla *Music*. Podría usar una solicitud `UpdateItem` con un parámetro `AttributeUpdates` como en este ejemplo de la 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"}
}
}'
```
Puede utilizar `UpdateExpression` en su lugar:
```
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 (heredado)
**nota**
Le recomendamos que utilice los nuevos parámetros de expresión en lugar de estos parámetros heredados siempre que sea posible. Para obtener más información, consulte [Uso de expresiones en DynamoDB](Expressions.md).
El parámetro condicional heredado `ConditionalOperator` es un operador lógico que se utiliza para aplicar a las condiciones de `Expected`, `QueryFilter` o mapa de `ScanFilter`:
+ AND: si todas las condiciones se evalúan en true, entonces todo el mapa se evalúa en true.
+ OR: si al menos una de las condiciones se evalúa en true, entonces todo el mapa se evalúa en true.
Si se omite `ConditionalOperator`, entonces `AND` es el valor predeterminado.
La operación se llevará a cabo correctamente solo si todo el mapa se evalúa en true.
**nota**
Este parámetro no es compatible con atributos de tipo List o Map.
# Expected (heredado)
**nota**
Le recomendamos que utilice los nuevos parámetros de expresión en lugar de estos parámetros heredados siempre que sea posible. Para obtener más información, consulte [Uso de expresiones en DynamoDB](Expressions.md). Para obtener información específica sobre el nuevo parámetro que reemplaza a este, [Use *ConditionExpression* en su lugar.](#Expected.instead).
El parámetro condicional heredado `Expected` es un bloque condicional para una operación `UpdateItem`. `Expected` es un mapa de pares atributo-condición. Cada entrada del mapa consta de un nombre de atributo, un operador de comparación y uno o varios valores. DynamoDB utiliza el operador de comparación para comparar el atributo con el o los valores suministrados. Para cada entrada de `Expected`, el resultado de la evaluación es true o false.
Si especifica más de una entrada en el mapa `Expected`, de forma predeterminada todas las condiciones deben evaluarse en true (verdadero). Es decir, las condiciones se combinan con el operador `AND`. (Si lo desea, puede usar el parámetro `ConditionalOperator` para definir las condiciones en OR (o). En tal caso, deberá evaluarse en true (verdadero) al menos una de las condiciones, en lugar de todas ellas).
Si el mapa `Expected` se evalúa en true, entonces la operación condicional se realiza correctamente; de lo contrario, se produce un error.
`Expected` contiene lo siguiente:
+ `AttributeValueList`: uno o más valores que se evaluarán respecto al atributo suministrado. El número de valores de la lista depende del valor de `ComparisonOperator` que se utilice.
Para el tipo Number, las comparaciones de los valores son numéricas.
Las comparaciones de valores String (cadena) de tipo mayor que, igual que o menor que se basan en Unicode con la codificación UTF-8 binaria. Por ejemplo, `a` es mayor que `A` y `a` es mayor que `B`.
Al comparar valores de tipo Binary, DynamoDB trata cada byte de los datos binarios como sin signo.
+ `ComparisonOperator` - comparador que permite evaluar los atributos contenidos en `AttributeValueList`. Al realizar la comparación, DynamoDB utiliza lecturas de consistencia alta.
Están disponibles los siguientes operadores de comparación:
`EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN`
A continuación se indican las descripciones de cada operador de comparación.
+ `EQ`: igual. `EQ` se admite para todos los tipos de datos, incluyendo las listas y los mapas.
`AttributeValueList` puede contener una sola entrada `AttributeValue` de tipo String (cadena), Number (número), Binary (binario), String Set (conjunto de cadenas), Number Set (conjunto de números) o Binary Set (conjunto de binarios). Si un elemento contiene una entrada `AttributeValue` de un tipo distinto del proporcionado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco es igual que `{"NS":["6", "2", "1"]}`.
+ `NE`: distinto. `NE` se admite para todos los tipos de datos, incluyendo las listas y los mapas.
`AttributeValueList` puede contener un solo `AttributeValue` de tipo String (cadena), Number (número), Binary (binario), String Set (conjunto de cadenas), Number Set (conjunto de números) o Binary Set (conjunto de binarios). Si un elemento contiene un `AttributeValue` de un tipo distinto del proporcionado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco es igual que `{"NS":["6", "2", "1"]}`.
+ `LE`: menor o igual que.
`AttributeValueList` puede contener una sola entrada `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no de tipo Set [conjunto]). Si un elemento contiene una entrada `AttributeValue` de un tipo distinto del proporcionado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco se compara con `{"NS":["6", "2", "1"]}`.
+ `LT` : Menor que.
`AttributeValueList` puede contener un solo `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no de tipo Set [conjunto]). Si un elemento contiene una entrada `AttributeValue` de un tipo distinto del proporcionado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco se compara con `{"NS":["6", "2", "1"]}`.
+ `GE`: mayor o igual que.
`AttributeValueList` puede contener una sola entrada `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no de tipo Set [conjunto]). Si un elemento contiene una entrada `AttributeValue` de un tipo distinto del proporcionado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco se compara con `{"NS":["6", "2", "1"]}`.
+ `GT` : Mayor que.
`AttributeValueList` puede contener una sola entrada `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no de tipo Set [conjunto]). Si un elemento contiene una entrada `AttributeValue` de un tipo distinto del proporcionado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco se compara con `{"NS":["6", "2", "1"]}`.
+ `NOT_NULL`: el atributo existe. `NOT_NULL` se admite para todos los tipos de datos, incluyendo las listas y los mapas.
**nota**
Este operador comprueba si existe un atributo, no su tipo de datos. Si el tipo de datos del atributo “`a`” es null y se evalúa mediante `NOT_NULL`, el resultado es un valor `true` booleano. Este resultado se debe a que el atributo "`a`" existe; su tipo de datos no es pertinente para el operador de comparación `NOT_NULL`.
+ `NULL`: el atributo no existe. `NULL` se admite para todos los tipos de datos, incluyendo las listas y los mapas.
**nota**
Este operador comprueba la inexistencia de un atributo, no su tipo de datos. Si el tipo de datos del atributo “`a`” es null y se evalúa mediante `NULL`, el resultado es un valor `false` booleano. Esto se debe a que el atributo "`a`" existe; su tipo de datos no es pertinente para el operador de comparación `NULL`.
+ `CONTAINS`: comprueba si hay una subsecuencia, o un valor en un conjunto.
`AttributeValueList` puede contener una sola entrada `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no de tipo Set [conjunto]). Si el atributo de destino de la comparación es de tipo String (cadena), entonces el operador comprueba si hay una subcadena coincidente. Si el atributo de destino de la comparación es de tipo Binary (binario), entonces el operador busca una subsecuencia del destino que coincida con la entrada. Si el atributo de destino de la comparación es un conjunto ("`SS`", "`NS`" o "`BS`"), entonces el operador se evalúa en true si encuentra una coincidencia exacta con cualquier miembro del conjunto.
CONTAINS es compatible con listas: al evaluar "`a CONTAINS b`", "`a`" puede ser una lista; sin embargo, "`b`" no puede ser un conjunto, un mapa ni una lista.
+ `NOT_CONTAINS`: comprueba la ausencia de una subsecuencia, o la ausencia de un valor en un conjunto.
`AttributeValueList` puede contener una sola entrada `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no de tipo Set [conjunto]). Si el atributo de destino de la comparación es de tipo String (cadena), entonces el operador comprueba la ausencia de una subcadena coincidente. Si el atributo de destino de la comparación es de tipo Binary (binario), entonces el operador busca la ausencia de una subsecuencia del destino que coincida con la entrada. Si el atributo de destino de la comparación es un conjunto ("`SS`", "`NS`" o "`BS`"), entonces el operador se evalúa en true si no (`does not`) encuentra una coincidencia exacta con cualquier miembro del conjunto.
NOT\$1CONTAINS es compatible con listas: al evaluar "`a NOT CONTAINS b`", "`a`" puede ser una lista; sin embargo, "`b`" no puede ser un conjunto, un mapa ni una lista.
+ `BEGINS_WITH`: comprueba si hay un prefijo.
`AttributeValueList` puede contener un solo `AttributeValue` de tipo String (cadena) o Binary (binario) (no de tipo Number [número] ni Set [conjunto]). El atributo de destino de la comparación debe ser un valor de tipo String o Binary (no de tipo Number ni Set).
+ `IN`: comprueba si hay entradas que coincidan en dos conjuntos.
`AttributeValueList` puede contener una o varias entradas `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no de tipo Set [conjunto]). Estos atributos se comparan con un atributo existente de tipo Set (conjunto) de un elemento. Si cualquier entrada del conjunto de entrada está presente en el atributo del elemento, la expresión se evalúa en true.
+ `BETWEEN`: mayor o igual que el primer valor y menor o igual que el segundo valor.
`AttributeValueList` debe contener dos entradas `AttributeValue` del mismo tipo, que puede ser String (cadena), Number (número) o Binary (binario) (pero no de tipo Set [conjunto]). Un atributo de destino coincide si el valor de destino es mayor o igual que la primer entrada y menor o igual que la segunda entrada. Si un elemento contiene una entrada `AttributeValue` de un tipo distinto del proporcionado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no se compara con `{"N":"6"}`. `{"N":"6"}` tampoco se compara con `{"NS":["6", "2", "1"]}`.
Los parámetros siguientes se pueden utilizar en lugar de `AttributeValueList` y `ComparisonOperator`:
+ `Value`: valor que DynamoDB compara con un atributo.
+ `Exists`: valor de tipo Boolean que hace que DynamoDB evalúe el valor antes de intentar la operación condicional.
+ Si `Exists` es `true`, DynamoDB verificará si el valor del atributo ya existe en la tabla. Si lo encuentra, la condición se evalúa en true; de lo contrario, la condición se evalúa en false.
+ Si `Exists` es `false`, DynamoDB presupone que el valor del atributo `not` (no) existe en la tabla. Si el valor no existe, entonces el supuesto es válido y la condición se evalúa en true (verdadero). Si el valor se encuentra, a pesar del supuesto de que no existía, la condición se evalúa en false.
Tenga en cuenta que el valor predeterminado de `Exists` es `true`.
Los parámetros `Value` y `Exists` son incompatibles con `AttributeValueList` y `ComparisonOperator`. Tenga en cuenta que si utiliza los dos conjuntos de parámetros a la vez, DynamoDB devolverá una excepción `ValidationException`.
**nota**
Este parámetro no es compatible con atributos de tipo List o Map.
## Use *ConditionExpression* en su lugar; ejemplo
Supongamos que desea modificar un elemento de la tabla *Music*, pero solo si se cumple una condición determinada. Podría usar una solicitud `UpdateItem` con un parámetro `Expected` como en este ejemplo de la 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"} ]
}
}'
```
Puede utilizar `ConditionExpression` en su lugar:
```
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 (heredado)
**nota**
Le recomendamos que utilice los nuevos parámetros de expresión en lugar de estos parámetros heredados siempre que sea posible. Para obtener más información, consulte [Uso de expresiones en DynamoDB](Expressions.md). Para obtener información específica sobre el nuevo parámetro que reemplaza a este, [Use *KeyConditionExpression* en su lugar.](#KeyConditionExpression.instead).
El parámetro condicional heredado `KeyConditions` contiene los criterios de selección de una operación `Query`. Para ejecutar una consulta en una tabla, solo puede usar condiciones con los atributos de clave principal de la tabla. Debe proporcionar el nombre y valor de la clave de partición como una condición `EQ`. Si lo desea, puede proporcionar una segunda condición referida a la clave de ordenación.
**nota**
Si no proporciona una condición de clave de ordenación, se recuperarán todos los elementos que coincidan con la clave de partición. Si hay una expresión `FilterExpression` o `QueryFilter` presente, se aplicará después de recuperar los elementos.
Para ejecutar una consulta en un índice, solo puede usar condiciones con los atributos de clave del índice. Debe proporcionar el nombre y valor de la clave de partición del índice como una condición `EQ`. Si lo desea, puede proporcionar una segunda condición referida a la clave de ordenación del índice.
Cada entrada `KeyConditions` consta de un nombre de atributo que se va a comparar, junto con lo siguiente:
+ `AttributeValueList`: uno o más valores que se evaluarán respecto al atributo suministrado. El número de valores de la lista depende del valor de `ComparisonOperator` que se utilice.
Para el tipo Number, las comparaciones de los valores son numéricas.
Las comparaciones de valores String (cadena) de tipo mayor que, igual que o menor que se basan en Unicode con la codificación UTF-8 binaria. Por ejemplo, `a` es mayor que `A` y `a` es mayor que `B`.
Al comparar valores de tipo Binary, DynamoDB trata cada byte de los datos binarios como sin signo.
+ `ComparisonOperator`: comparador que permite evaluar los atributos. Por ejemplo: igual que, mayor que y menor que.
Para `KeyConditions`, solo se admiten los siguientes operadores de comparación:
`EQ | LE | LT | GE | GT | BEGINS_WITH | BETWEEN`
A continuación se indican las descripciones de estos operadores de comparación.
+ `EQ`: igual que.
`AttributeValueList` puede contener un solo `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no de tipo Set [conjunto]). Si un elemento contiene una entrada `AttributeValue` de un tipo distinto del especificado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco es igual que `{"NS":["6", "2", "1"]}`.
+ `LE`: menor o igual que.
`AttributeValueList` puede contener una sola entrada `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no de tipo Set [conjunto]). Si un elemento contiene una entrada `AttributeValue` de un tipo distinto del proporcionado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco se compara con `{"NS":["6", "2", "1"]}`.
+ `LT` : Menor que.
`AttributeValueList` puede contener un solo `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no de tipo Set [conjunto]). Si un elemento contiene una entrada `AttributeValue` de un tipo distinto del proporcionado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco se compara con `{"NS":["6", "2", "1"]}`.
+ `GE`: mayor o igual que.
`AttributeValueList` puede contener una sola entrada `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no de tipo Set [conjunto]). Si un elemento contiene una entrada `AttributeValue` de un tipo distinto del proporcionado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco se compara con `{"NS":["6", "2", "1"]}`.
+ `GT` : Mayor que.
`AttributeValueList` puede contener una sola entrada `AttributeValue` de tipo String (cadena), Number (número) o Binary (binario) (no de tipo Set [conjunto]). Si un elemento contiene una entrada `AttributeValue` de un tipo distinto del proporcionado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no es igual que `{"N":"6"}`. `{"N":"6"}` tampoco se compara con `{"NS":["6", "2", "1"]}`.
+ `BEGINS_WITH`: comprueba si hay un prefijo.
`AttributeValueList` puede contener un solo `AttributeValue` de tipo String (cadena) o Binary (binario) (no de tipo Number [número] ni Set [conjunto]). El atributo de destino de la comparación debe ser un valor de tipo String o Binary (no de tipo Number ni Set).
+ `BETWEEN`: mayor o igual que el primer valor y menor o igual que el segundo valor.
`AttributeValueList` debe contener dos entradas `AttributeValue` del mismo tipo, que puede ser String (cadena), Number (número) o Binary (binario) (pero no de tipo Set [conjunto]). Un atributo de destino coincide si el valor de destino es mayor o igual que la primer entrada y menor o igual que la segunda entrada. Si un elemento contiene una entrada `AttributeValue` de un tipo distinto del proporcionado en la solicitud, el valor no coincide. Por ejemplo, `{"S":"6"}` no se compara con `{"N":"6"}`. `{"N":"6"}` tampoco se compara con `{"NS":["6", "2", "1"]}`.
## Use *KeyConditionExpression* en su lugar; ejemplo
Supongamos que desea recuperar varios elementos con la misma clave de partición de la tabla *Music*. Podría usar una solicitud `Query` con un parámetro `KeyConditions` como en este ejemplo de la 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"} ]
}
}'
```
Puede utilizar `KeyConditionExpression` en su lugar:
```
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 (heredado)
**nota**
Le recomendamos que utilice los nuevos parámetros de expresión en lugar de estos parámetros heredados siempre que sea posible. Para obtener más información, consulte [Uso de expresiones en DynamoDB](Expressions.md). Para obtener información específica sobre el nuevo parámetro que reemplaza a este, [Use *FilterExpression* en su lugar.](#FilterExpression.instead).
En una operación `Query`, el parámetro condicional heredado `QueryFilter` es una condición que evalúa los resultados de la consulta después de que se hayan leído los elementos y devuelve únicamente los valores deseados.
Este parámetro no es compatible con atributos de tipo List o Map.
**nota**
`QueryFilter` se aplica después de haber leído los elementos; el proceso de filtrado no consume ninguna unidad de capacidad de lectura adicional.
Si proporciona más de una condición en el mapa `QueryFilter`, de forma predeterminada todas las condiciones deben evaluarse en true (verdadero). Es decir, las condiciones se combinan con el operador `AND`. (Si lo desea, puede usar el parámetro [ConditionalOperator (heredado)](LegacyConditionalParameters.ConditionalOperator.md) para definir las condiciones en OR (o). En tal caso, deberá evaluarse en true (verdadero) al menos una de las condiciones, en lugar de todas ellas).
Tenga en cuenta que `QueryFilter` no admite atributos de clave. No puede definir una condición de filtro en una clave de partición ni de ordenación.
Cada entrada `QueryFilter` consta de un nombre de atributo que se va a comparar, junto con lo siguiente:
+ `AttributeValueList`: uno o más valores que se evaluarán respecto al atributo suministrado. El número de valores de la lista depende del operador especificado en `ComparisonOperator`.
Para el tipo Number, las comparaciones de los valores son numéricas.
Las comparaciones de valores String (cadena) de tipo mayor que, igual que o menor que se basan en la codificación UTF-8 binaria. Por ejemplo, `a` es mayor que `A` y `a` es mayor que `B`.
Al comparar valores de tipo Binary, DynamoDB trata cada byte de los datos binarios como sin signo.
Para obtener más información sobre cómo especificar los tipos de datos en JSON, consulte [API de bajo nivel de DynamoDB](Programming.LowLevelAPI.md).
+ `ComparisonOperator`: comparador que permite evaluar los atributos. Por ejemplo: igual que, mayor que y menor que.
Están disponibles los siguientes operadores de comparación:
`EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN`
## Use *FilterExpression* en su lugar; ejemplo
Supongamos que quiere consultar la tabla *Music* y aplicar una condición a la coincidencia de elementos. Podría usar una solicitud `Query` con un parámetro `QueryFilter` como en este ejemplo de la 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"} ]
}
}'
```
Puede utilizar `FilterExpression` en su lugar:
```
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 (heredado)
**nota**
Le recomendamos que utilice los nuevos parámetros de expresión en lugar de estos parámetros heredados siempre que sea posible. Para obtener más información, consulte [Uso de expresiones en DynamoDB](Expressions.md). Para obtener información específica sobre el nuevo parámetro que reemplaza a este, [Use *FilterExpression* en su lugar.](#FilterExpression2.instead).
En una operación `Scan`, el parámetro condicional heredado `ScanFilter` es una condición que evalúa los resultados del examen y devuelve únicamente los valores deseados.
**nota**
Este parámetro no es compatible con atributos de tipo List o Map.
Si especifica más de una condición en el mapa `ScanFilter`, de forma predeterminada todas las condiciones deben evaluarse en true (verdadero). Es decir, se utiliza AND como operador para evaluar las condiciones. (Si lo desea, puede usar el parámetro [ConditionalOperator (heredado)](LegacyConditionalParameters.ConditionalOperator.md) para definir las condiciones en OR (o). En tal caso, deberá evaluarse en true (verdadero) al menos una de las condiciones, en lugar de todas ellas).
Cada entrada `ScanFilter` consta de un nombre de atributo que se va a comparar, junto con lo siguiente:
+ `AttributeValueList`: uno o más valores que se evaluarán respecto al atributo suministrado. El número de valores de la lista depende del operador especificado en `ComparisonOperator` .
Para el tipo Number, las comparaciones de los valores son numéricas.
Las comparaciones de valores String (cadena) de tipo mayor que, igual que o menor que se basan en la codificación UTF-8 binaria. Por ejemplo, `a` es mayor que `A` y `a` es mayor que `B`.
Al comparar valores de tipo Binary, DynamoDB trata cada byte de los datos binarios como sin signo.
Para obtener más información sobre cómo especificar los tipos de datos en JSON, consulte [API de bajo nivel de DynamoDB](Programming.LowLevelAPI.md).
+ `ComparisonOperator`: comparador que permite evaluar los atributos. Por ejemplo: igual que, mayor que y menor que.
Están disponibles los siguientes operadores de comparación:
`EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN`
## Use *FilterExpression* en su lugar; ejemplo
Supongamos que quiere examinar la tabla *Music* y aplicar una condición a la coincidencia de elementos. Podría usar una solicitud `Scan` con un parámetro `ScanFilter` como en este ejemplo de la AWS CLI:
```
aws dynamodb scan \
--table-name Music \
--scan-filter '{
"Genre":{
"AttributeValueList":[ {"S":"Rock"} ],
"ComparisonOperator": "EQ"
}
}'
```
Puede utilizar `FilterExpression` en su lugar:
```
aws dynamodb scan \
--table-name Music \
--filter-expression 'Genre = :g' \
--expression-attribute-values '{
":g": {"S":"Rock"}
}'
```
# Escritura de condiciones con parámetros heredados
**nota**
Le recomendamos que utilice los nuevos parámetros de expresión en lugar de estos parámetros heredados siempre que sea posible. Para obtener más información, consulte [Uso de expresiones en DynamoDB](Expressions.md).
En la siguiente sección se describe cómo escribir condiciones para usarlas con parámetros heredados, tales como `Expected`, `QueryFilter` y `ScanFilter`.
**nota**
En las nuevas aplicaciones deben utilizarse parámetros de expresión en su lugar. Para obtener más información, consulte [Uso de expresiones en DynamoDB](Expressions.md).
## Condiciones simples
Con los valores de los atributos, puede escribir condiciones para realizar comparaciones con los atributos de la tabla. Una condición siempre se evalúa en true o false y consta de:
+ `ComparisonOperator`: mayor que, menor que, igual que, etc.
+ `AttributeValueList` (opcional): valor o valores de atributo respecto a los que se va a establecer la comparación. Según cuál esa el operador `ComparisonOperator` utilizado, `AttributeValueList` puede contener uno, dos o más valores; o puede omitirse.
En las siguientes secciones se describen los distintos operadores de comparación, además de ejemplos de cómo utilizarlos en las condiciones.
### Operadores de comparación sin valores de atributos
+ `NOT_NULL`: es true si un atributo existe.
+ `NULL`: es true si un atributo no existe.
Utilice estos operadores para verificar si un atributo existe o no. Dado que no hay ningún valor que comparar, no especifique `AttributeValueList`.
**Ejemplo**
La siguiente expresión se evalúa en true si el atributo *Dimensions* existe.
```
...
"Dimensions": {
ComparisonOperator: "NOT_NULL"
}
...
```
### Operadores de comparación con un valor de atributo
+ `EQ`: es true si un atributo es igual que un valor.
`AttributeValueList` puede contener un solo valor de tipo String (cadena), Number (número), Binary (binario), String Set (conjunto de cadenas), Number Set (conjunto de números) o Binary Set (conjunto de binarios). Si un elemento contiene un valor de un tipo distinto del especificado en la solicitud, el valor no coincide. Por ejemplo, la cadena `"3"` no es igual que el número `3`. Tampoco el número `3` es igual que el conjunto de números `[3, 2, 1]`.
+ `NE`: es true si un atributo no es igual que un valor.
`AttributeValueList` puede contener un solo valor de tipo String (cadena), Number (número), Binary (binario), String Set (conjunto de cadenas), Number Set (conjunto de números) o Binary Set (conjunto de binarios). Si un elemento contiene un valor de un tipo distinto del especificado en la solicitud, el valor no coincide.
+ `LE`: es true si un atributo es menor o igual que un valor.
`AttributeValueList` puede contener un solo valor de tipo String (cadena), Number (número) o Binary (binario) (no un conjunto). Si un elemento contiene un `AttributeValue` de un tipo distinto del especificado en la solicitud, el valor no coincide.
+ `LT`: es true si un atributo es menor que un valor.
`AttributeValueList` puede contener un solo valor de tipo String (cadena), Number (número) o Binary (binario) (no un conjunto). Si un elemento contiene un valor de un tipo distinto del especificado en la solicitud, el valor no coincide.
+ `GE`: es true si un atributo es mayor o igual que un valor.
`AttributeValueList` puede contener un solo valor de tipo String (cadena), Number (número) o Binary (binario) (no un conjunto). Si un elemento contiene un valor de un tipo distinto del especificado en la solicitud, el valor no coincide.
+ `GT`: es true si un atributo es mayor que un valor.
`AttributeValueList` puede contener un solo valor de tipo String (cadena), Number (número) o Binary (binario) (no un conjunto). Si un elemento contiene un valor de un tipo distinto del especificado en la solicitud, el valor no coincide.
+ `CONTAINS`: es true si un valor está presente en un conjunto o si un valor contiene otro valor.
`AttributeValueList` puede contener un solo valor de tipo String (cadena), Number (número) o Binary (binario) (no un conjunto). Si el atributo de destino de la comparación es de tipo String (cadena), entonces el operador comprueba si hay una subcadena coincidente. Si el atributo de destino de la comparación es de tipo Binary (binario), entonces el operador busca una subsecuencia del destino que coincida con la entrada. Si el atributo de destino de la comparación es un conjunto, entonces el operador se evalúa en true si encuentra una coincidencia exacta con cualquier miembro del conjunto.
+ `NOT_CONTAINS`: es true si un valor *no* está presente en un conjunto o si un valor no contiene otro valor.
`AttributeValueList` puede contener un solo valor de tipo String (cadena), Number (número) o Binary (binario) (no un conjunto). Si el atributo de destino de la comparación es de tipo String (cadena), entonces el operador comprueba la ausencia de una subcadena coincidente. Si el atributo de destino de la comparación es de tipo Binary (binario), entonces el operador busca la ausencia de una subsecuencia del destino que coincida con la entrada. Si el atributo de destino de la comparación es un conjunto, entonces el operador se evalúa en true si *no* encuentra una coincidencia exacta con cualquier miembro del conjunto.
+ `BEGINS_WITH`: es true (verdadero) si los primeros caracteres de un atributo coinciden con el valor proporcionado. No use este operador para comparar números.
`AttributeValueList` puede contener un solo valor de tipo String (cadena) o Binary (binario) (no de tipo Number [número] o Set [conjunto]). El atributo de destino de la comparación debe ser un valor de tipo String o Binary (no de tipo Number ni un conjunto).
Use estos operadores para comparar un atributo con un valor. Debe especificar una lista `AttributeValueList` compuesta por un solo valor. Para la mayoría de los operadores, este debe ser un valor escalar; sin embargo, los operadores `EQ` y `NE` también admiten conjuntos.
**Ejemplos**
Las siguientes expresiones se evalúan en true si:
+ El precio de un producto es mayor que 100.
```
...
"Price": {
ComparisonOperator: "GT",
AttributeValueList: [ {"N":"100"} ]
}
...
```
+ La categoría de un producto comienza con "Bo".
```
...
"ProductCategory": {
ComparisonOperator: "BEGINS_WITH",
AttributeValueList: [ {"S":"Bo"} ]
}
...
```
+ Un producto está disponible en rojo, verde o negro:
```
...
"Color": {
ComparisonOperator: "EQ",
AttributeValueList: [
[ {"S":"Black"}, {"S":"Red"}, {"S":"Green"} ]
]
}
...
```
**nota**
Al comparar datos de tipo Set (conjunto), el orden de las entradas carece de relevancia. DynamoDB devolverá solo los elementos con el mismo conjunto de valores, independientemente del orden en que los especifique en la solicitud.
### Operadores de comparación con dos valores de atributos
+ `BETWEEN`: es true si un valor está comprendido entre un límite inferior y un límite superior, ambos incluidos.
`AttributeValueList` debe contener dos entradas del mismo tipo, que puede ser String (cadena), Number (número) o Binary (binario) (pero no un conjunto). Un atributo de destino coincide si el valor de destino es mayor o igual que la primer entrada y menor o igual que la segunda entrada. Si un elemento contiene un valor de un tipo distinto del especificado en la solicitud, el valor no coincide.
Use este operador para determinar si un valor de atributo está dentro de un intervalo. `AttributeValueList` debe contener dos entradas escalares del mismo tipo: String, Number o Binary.
**Ejemplo**
La siguiente expresión se evalúa en true si el precio de un producto está comprendido entre 100 y 200.
```
...
"Price": {
ComparisonOperator: "BETWEEN",
AttributeValueList: [ {"N":"100"}, {"N":"200"} ]
}
...
```
### Operadores de comparación con *n* valores de atributos
+ `IN`: es true (verdadero) si un valor es igual que cualquiera de los valores de una lista. Solo se admiten valores escalares en la lista, no conjuntos. El atributo de destino debe ser del mismo tipo y valor exactos para que se produzca la coincidencia.
`AttributeValueList` puede contener una o varias entradas de tipo String (cadena), Number (número) o Binary (binario) (no un conjunto). Estos atributos se comparan con un atributo existente que no sea de tipo Set (conjunto) de un elemento. Si *cualquier* entrada del conjunto de entrada está presente en el atributo del elemento, la expresión se evalúa en true.
`AttributeValueList` puede contener uno o varios valores de tipo String (cadena), Number (número) o Binary (binario) (no un conjunto). El atributo de destino de la comparación debe ser del mismo tipo y valor exacto para que se produzca la coincidencia. Un valor de tipo String nunca coincide con un valor de tipo String Set.
Use este operador para determinar si el valor suministrado está contenido en una lista. Puede especificar cualquier número de valores escalares en `AttributeValueList`, pero todos ellos deben ser del mismo tipo de datos.
**Ejemplo**
La siguiente expresión se evalúa en true si el valor de *Id* es 201, 203 o 205.
```
...
"Id": {
ComparisonOperator: "IN",
AttributeValueList: [ {"N":"201"}, {"N":"203"}, {"N":"205"} ]
}
...
```
## Uso de varias condiciones
DynamoDB permite combinar varias condiciones para crear expresiones complejas. Para ello, hay que proporcionar al menos dos expresiones, con un opcional [ConditionalOperator (heredado)](LegacyConditionalParameters.ConditionalOperator.md).
De forma predeterminada, cuando se especifica más de una condición, *todas* ellas deben evaluarse en true (verdadero) para que la expresión completa se evalúe en true (verdadero). Es decir, se lleva a cabo una operación *AND* implícita.
**Ejemplo**
La siguiente expresión se evalúa en true si un producto es un libro que tiene al menos 600 páginas. Deben evaluarse en true las dos condiciones, puesto que implícitamente se les aplica el operador *AND*.
```
...
"ProductCategory": {
ComparisonOperator: "EQ",
AttributeValueList: [ {"S":"Book"} ]
},
"PageCount": {
ComparisonOperator: "GE",
AttributeValueList: [ {"N":600"} ]
}
...
```
Puede utilizar [ConditionalOperator (heredado)](LegacyConditionalParameters.ConditionalOperator.md) para aclarar que se llevará a cabo una operación *AND*. En el siguiente ejemplo, el comportamiento es el mismo que en el caso anterior.
```
...
"ConditionalOperator" : "AND",
"ProductCategory": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"N":"Book"} ]
},
"PageCount": {
"ComparisonOperator": "GE",
"AttributeValueList": [ {"N":600"} ]
}
...
```
También puede establecer `ConditionalOperator` en *OR*, en cuyo caso *al menos una* de las condiciones deberá evaluarse en true.
**Ejemplo**
La siguiente expresión se evalúa en true si un producto es una bicicleta de montaña, es de una marca concreta o su precio es mayor 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**
En una expresión compleja, las condiciones se procesan por orden, desde la primera hasta la última.
No se puede utilizar AND y OR en la misma expresión.
## Otros operadores condicionales
En versiones anteriores de DynamoDB, el parámetro `Expected` se comportaba de forma distinta para las escrituras condicionales. Cada elemento del mapa `Expected` representaba un nombre de atributo que DynamoDB debía verificar, además de lo siguiente:
+ `Value`: valor que se va a comparar con el atributo.
+ `Exists`: determina si el valor existe antes de intentar la operación.
DynamoDB continúa admitiendo las opciones `Value` y `Exists`. Sin embargo, solo permiten comprobar una condición de desigualdad o si un atributo existe. Recomendamos usar `ComparisonOperator` y `AttributeValueList` en su lugar, porque estas opciones permiten construir un abanico de condiciones mucho más amplio.
**Example**
`DeleteItem` permite verificar si un libro está descatalogado y eliminarlo únicamente si se cumple esta condición. A continuación se muestra un ejemplo de la AWS CLI en el que se usa una condición heredada:
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{
"Id": {"N":"600"}
}' \
--expected '{
"InPublication": {
"Exists": true,
"Value": {"BOOL":false}
}
}'
```
En el siguiente ejemplo se realiza la misma operación, pero sin la condición heredada:
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{
"Id": {"N":"600"}
}' \
--expected '{
"InPublication": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"BOOL":false} ]
}
}'
```
**Example**
Una operación `PutItem` permite proteger los datos para evitar que se sobrescriba un elemento existente que tenga los mismos atributos de clave principal. A continuación se muestra un ejemplo en el que se usa una condición heredada:
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item '{
"Id": {"N":"500"},
"Title": {"S":"Book 500 Title"}
}' \
--expected '{
"Id": { "Exists": false }
}'
```
En el siguiente ejemplo se realiza la misma operación, pero sin la condición heredada:
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item '{
"Id": {"N":"500"},
"Title": {"S":"Book 500 Title"}
}' \
--expected '{
"Id": { "ComparisonOperator": "NULL" }
}'
```
**nota**
Para las condiciones del mapa `Expected`, no use las opciones `Value` y `Exists` heredadas con `ComparisonOperator` y `AttributeValueList`. Si lo hace, se producirá un error en la escritura condicional.