

# Ejemplo de la CLI de expresión de condición de DynamoDB

A continuación se muestran algunos ejemplos de uso de expresiones de condición en la AWS Command Line Interface (AWS CLI). Estos ejemplos se basan en la tabla `ProductCatalog`, especificada en [Referencia a atributos de elementos mediante expresiones en DynamoDB](Expressions.Attributes.md). La clave de partición de esta tabla es `Id` y no tiene clave de ordenación. La siguiente operación `PutItem` crea un elemento de muestra `ProductCatalog` al que se refieren los ejemplos.

```
aws dynamodb put-item \
    --table-name ProductCatalog \
    --item file://item.json
```

Los argumentos de `--item` se almacenan en el archivo `item.json`. Para simplificar, se utilizan tan solo algunos de los atributos de elementos.

```json
{
    "Id": {"N": "456" },
    "ProductCategory": {"S": "Sporting Goods" },
    "Price": {"N": "650" }
}
```

**Topics**
+ [PUT condicional](#Expressions.ConditionExpressions.PreventingOverwrites)
+ [Eliminaciones condicionales](#Expressions.ConditionExpressions.AdvancedComparisons)
+ [Actualizaciones condicionales](#Expressions.ConditionExpressions.SimpleComparisons)
+ [Ejemplos de expresiones condicionales](#Expressions.ConditionExpressions.ConditionalExamples)

## PUT condicional
<a name="Expressions.ConditionExpressions.PreventingOverwrites"></a>

La operación `PutItem` sobrescribe un elemento que tenga la misma clave principal (si existe). Si desea evitar que esto suceda, utilice una expresión de condición. Esto permite que la escritura se lleve a cabo solo si el elemento en cuestión ya no tiene la misma clave principal.

En el siguiente ejemplo, se utiliza `attribute_not_exists()` para comprobar si ya existe un elemento con la misma clave principal antes de intentar la operación de escritura. DynamoDB evalúa una expresión de condición en una operación de escritura comparándola con el elemento identificado por la clave de la solicitud, por lo que `attribute_not_exists(Id)` solo es verdadero cuando no existe ningún elemento con ese valor de `Id`. Si es verdadera, la escritura continúa; cuando ya existe un elemento con esa clave, la condición es falsa y DynamoDB rechaza la escritura, lo que impide que se sobrescriba.

**nota**  
En el caso de una tabla con una clave primaria compuesta (una clave de partición y una clave de clasificación), DynamoDB sigue evaluando la condición comparándola con el único elemento identificado por ambos valores de claves. Las pruebas de `attribute_not_exists()` en un atributo de clave, por ejemplo `attribute_not_exists(pk)`, solo son verdaderas cuando no existe ningún elemento con esa clave de partición y esa clave de clasificación, por lo que se evita sobrescribir ese elemento.

```
aws dynamodb put-item \
    --table-name ProductCatalog \
    --item file://item.json \
    --condition-expression "attribute_not_exists(Id)"
```

Si la expresión de condición se evalúa en false (falso), DynamoDB devuelve el siguiente mensaje de error: `The conditional request failed (Se produjo un error en la consulta condicional)`.

**nota**  
Para obtener más información sobre `attribute_not_exists` y otras funciones, consulte [Expresiones, operadores y funciones de condición y filtro en DynamoDB](Expressions.OperatorsAndFunctions.md).

## Eliminaciones condicionales
<a name="Expressions.ConditionExpressions.AdvancedComparisons"></a>

Para realizar una eliminación condicional, se usa una operación `DeleteItem` con una expresión de condición. La expresión de condición debe evaluarse en true para que la operación se lleve a cabo correctamente; de lo contrario, se produce un error.

Tenga en cuenta el elemento definido anteriormente.

Suponga que desea eliminar el elemento, pero solo en las siguientes condiciones:
+  El valor de `ProductCategory` es "Sporting Goods" o "Gardening Supplies".
+  El valor de `Price` está comprendido entre 500 y 600.

En el siguiente ejemplo se intenta eliminar el elemento.

```
aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"456"}}' \
    --condition-expression "(ProductCategory IN (:cat1, :cat2)) and (Price between :lo and :hi)" \
    --expression-attribute-values file://values.json
```

Los argumentos de `--expression-attribute-values` se almacenan en el archivo `values.json`.

```json
{
    ":cat1": {"S": "Sporting Goods"},
    ":cat2": {"S": "Gardening Supplies"},
    ":lo": {"N": "500"},
    ":hi": {"N": "600"}
}
```

**nota**  
En la expresión de condición, `:` (signo de dos puntos) indica un *valor de atributo de expresión* (un marcador de posición del valor real). Para obtener más información, consulte [Uso de valores de atributos de expresión en DynamoDB](Expressions.ExpressionAttributeValues.md).  
Para obtener más información sobre `IN`, `AND` y otras palabras clave, consulte [Expresiones, operadores y funciones de condición y filtro en DynamoDB](Expressions.OperatorsAndFunctions.md).

En este ejemplo, la comparación de `ProductCategory` se evalúa en true, pero la comparación de `Price` se evalúa en false. Esto hace que la expresión de condición se evalúe en false y, por consiguiente, la operación `DeleteItem` no se lleva a cabo.

## Actualizaciones condicionales
<a name="Expressions.ConditionExpressions.SimpleComparisons"></a>

Para realizar una actualización condicional, se usa una operación `UpdateItem` con una expresión de condición. La expresión de condición debe evaluarse en true para que la operación se lleve a cabo correctamente; de lo contrario, se produce un error.

**nota**  
`UpdateItem` también admite las *expresiones de actualización*, donde especifica las modificaciones que se desea aplicar a un elemento. Para obtener más información, consulte [Uso de expresiones de actualización en DynamoDB](Expressions.UpdateExpressions.md).

Supongamos que ha comenzado por el elemento definido anteriormente.

En el ejemplo siguiente se realiza una operación `UpdateItem`. Se intenta reducir el valor de `Price` de un producto en 75, pero la expresión de condición impide la actualización si el valor de `Price` actual es menor o igual que 500.

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id": {"N": "456"}}' \
    --update-expression "SET Price = Price - :discount" \
    --condition-expression "Price > :limit" \
    --expression-attribute-values file://values.json
```

Los argumentos de `--expression-attribute-values` se almacenan en el archivo `values.json`.

```json
{
    ":discount": { "N": "75"},
    ":limit": {"N": "500"}
}
```

Si el valor inicial de `Price` es 650, la operación `UpdateItem` reduce el `Price` a 575. Si ejecuta la operación `UpdateItem` de nuevo, el valor de `Price` se reduce a 500. Si se ejecuta una tercera vez, la expresión de condición se evalúa en false y la actualización no se lleva a cabo.

**nota**  
En la expresión de condición, `:` (signo de dos puntos) indica un *valor de atributo de expresión* (un marcador de posición del valor real). Para obtener más información, consulte [Uso de valores de atributos de expresión en DynamoDB](Expressions.ExpressionAttributeValues.md).  
Para obtener más información sobre "*>*" y otros operadores, consulte [Expresiones, operadores y funciones de condición y filtro en DynamoDB](Expressions.OperatorsAndFunctions.md).

## Ejemplos de expresiones condicionales
<a name="Expressions.ConditionExpressions.ConditionalExamples"></a>

Para obtener más información acerca de las funciones utilizadas en los ejemplos siguientes, consulte [Expresiones, operadores y funciones de condición y filtro en DynamoDB](Expressions.OperatorsAndFunctions.md). Si desea obtener más información sobre cómo especificar distintos tipos de atributo en una expresión, consulte [Referencia a atributos de elementos mediante expresiones en DynamoDB](Expressions.Attributes.md). 

### Comprobación de los atributos de un elemento
<a name="Expressions.ConditionExpressions.CheckingForAttributes"></a>

Puede comprobar la existencia (o inexistencia) de cualquier atributo. Si la expresión de condición se evalúa en true, entonces la operación se realiza correctamente; de lo contrario, produce un error.

En el siguiente ejemplo se utiliza `attribute_not_exists` para eliminar un producto únicamente si no tiene el atributo `Price`.

```
aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{"Id": {"N": "456"}}' \
    --condition-expression "attribute_not_exists(Price)"
```

DynamoDB también proporciona un función `attribute_exists`. En el siguiente ejemplo se elimina un producto únicamente si ha recibido opiniones negativas.

```
aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{"Id": {"N": "456"}}' \
    --condition-expression "attribute_exists(ProductReviews.OneStar)"
```

### Comprobación del tipo de atributo
<a name="Expressions.ConditionExpressions.CheckingForAttributeType"></a>

Puede comprobar el tipo de datos de un valor de atributo mediante la función `attribute_type`. Si la expresión de condición se evalúa en true, entonces la operación se realiza correctamente; de lo contrario, produce un error.

En el ejemplo siguiente se utiliza `attribute_type` para eliminar un producto sólo si tiene un atributo `Color` de tipo String Set. 

```
aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{"Id": {"N": "456"}}' \
    --condition-expression "attribute_type(Color, :v_sub)" \
    --expression-attribute-values file://expression-attribute-values.json
```

Los argumentos de `--expression-attribute-values` se almacenan en el archivo expression-attribute-values.json.

```json
{
    ":v_sub":{"S":"SS"}
}
```

### Comprobación del valor inicial de cadena
<a name="Expressions.ConditionExpressions.CheckingBeginsWith"></a>

Puede comprobar si un valor de atributo String comienza con una subcadena determinada mediante la función `begins_with`. Si la expresión de condición se evalúa en true, entonces la operación se realiza correctamente; de lo contrario, produce un error. 

En el ejemplo siguiente se utiliza `begins_with` para eliminar un producto solo si el elemento `FrontView` del mapa `Pictures` comienza con un valor específico.

```
aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{"Id": {"N": "456"}}' \
    --condition-expression "begins_with(Pictures.FrontView, :v_sub)" \
    --expression-attribute-values file://expression-attribute-values.json
```

Los argumentos de `--expression-attribute-values` se almacenan en el archivo expression-attribute-values.json.

```json
{
    ":v_sub":{"S":"http://"}
}
```

### Comprobación de un elemento en un conjunto
<a name="Expressions.ConditionExpressions.CheckingForContains"></a>

Puede buscar un elemento en un conjunto o buscar una subcadena dentro de una cadena mediante el uso de la función `contains`. Si la expresión de condición se evalúa en true, entonces la operación se realiza correctamente; de lo contrario, produce un error. 

En el ejemplo siguiente se utiliza `contains` para eliminar un producto sólo si el conjunto de cadenas `Color` tiene un elemento con un valor específico. 

```
aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{"Id": {"N": "456"}}' \
    --condition-expression "contains(Color, :v_sub)" \
    --expression-attribute-values file://expression-attribute-values.json
```

Los argumentos de `--expression-attribute-values` se almacenan en el archivo expression-attribute-values.json.

```json
{
    ":v_sub":{"S":"Red"}
}
```

### Comprobación del tamaño de un valor de atributo
<a name="Expressions.ConditionExpressions.CheckingForSize"></a>

Puede comprobar el tamaño de un valor de atributo mediante la función `size`. Si la expresión de condición se evalúa en true, entonces la operación se realiza correctamente; de lo contrario, produce un error. 

En el ejemplo siguiente se utiliza `size` para eliminar un producto sólo si el tamaño del atributo Binary `VideoClip` es mayor de `64000` bytes. 

```
aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{"Id": {"N": "456"}}' \
    --condition-expression "size(VideoClip) > :v_sub" \
    --expression-attribute-values file://expression-attribute-values.json
```

Los argumentos de `--expression-attribute-values` se almacenan en el archivo expression-attribute-values.json.

```json
{
    ":v_sub":{"N":"64000"}
}
```