# Uso de expresiones en DynamoDB
En Amazon DynamoDB, puede usar *expresiones* para especificar qué atributos leer de un elemento, escribir datos cuando se cumple una condición, especificar cómo actualizar un elemento, definir consultas y filtrar los resultados de una consulta.
En esta tabla se describen los aspectos gramaticales básicos de las expresiones y los tipos de expresiones disponibles.
| Tipo de expresión | Descripción |
| --- | --- |
| Expresión de proyección | Una expresión de proyección identifica los atributos que se desean recuperar de un elemento cuando se utilizan operaciones como GetItem, Query o Scan. |
| Expresión de condición | Una expresión de condición determina qué elementos deben modificarse al utilizar las operaciones PutItem, UpdateItem y DeleteItem. |
| Expresión de actualización | Una expresión de actualización especifica cómo UpdateItem modificará los atributos de un elemento; por ejemplo, estableciendo un valor escalar o eliminando elementos de una lista o un mapa. |
| Expresión de condición de clave | Una expresión de condición clave determina qué elementos leerá una consulta de una tabla o índice. |
| Expresión de filtro | Una expresión de filtro determina qué elementos entre los resultados de consulta se deben devolver al usuario. Todos los demás resultados se descartan. |
Para obtener información sobre la sintaxis de expresión e información más detallada sobre cada tipo de expresión, consulte las secciones siguientes.
**Topics**
+ [Referencia a atributos de elementos mediante expresiones en DynamoDB](Expressions.Attributes.md)
+ [Nombres de atributos de expresión (Alias) en DynamoDB](Expressions.ExpressionAttributeNames.md)
+ [Uso de valores de atributos de expresión en DynamoDB](Expressions.ExpressionAttributeValues.md)
+ [Uso de expresiones de proyección en DynamoDB](Expressions.ProjectionExpressions.md)
+ [Uso de expresiones de actualización en DynamoDB](Expressions.UpdateExpressions.md)
+ [Expresiones, operadores y funciones de condición y filtro en DynamoDB](Expressions.OperatorsAndFunctions.md)
+ [Ejemplo de la CLI de expresión de condición de DynamoDB](Expressions.ConditionExpressions.md)
**nota**
Con el fin de ofrecer compatibilidad retroactiva, DynamoDB también admite parámetros condicionales que no utilizan expresiones. Para obtener más información, consulte [Parámetros condicionales de DynamoDB heredados](LegacyConditionalParameters.md).
Las nuevas aplicaciones deben utilizar expresiones en lugar de los parámetros heredados.
# Referencia a atributos de elementos mediante expresiones en DynamoDB
En esta sección se describe cómo consultar los atributos de los elementos en una expresión en Amazon DynamoDB. Puede utilizar cualquier atributo, aunque se encuentre anidado profundamente en varias listas y mapas.
**Topics**
+ [Atributos de nivel superior](#Expressions.Attributes.TopLevelAttributes)
+ [Atributos anidados](#Expressions.Attributes.NestedAttributes)
+ [Rutas de documento](#Expressions.Attributes.NestedElements.DocumentPathExamples)
**Ejemplo de elemento: ProductCatalog**
Los ejemplos de esta página utilizan el siguiente elemento de muestra de la tabla de `ProductCatalog`. Esta tabla se describe en . [Tablas y datos de ejemplo para usar en DynamoDB](AppendixSampleTables.md).)
```
{
"Id": 123,
"Title": "Bicycle 123",
"Description": "123 description",
"BicycleType": "Hybrid",
"Brand": "Brand-Company C",
"Price": 500,
"Color": ["Red", "Black"],
"ProductCategory": "Bicycle",
"InStock": true,
"QuantityOnHand": null,
"RelatedItems": [
341,
472,
649
],
"Pictures": {
"FrontView": "http://example.com/products/123_front.jpg",
"RearView": "http://example.com/products/123_rear.jpg",
"SideView": "http://example.com/products/123_left_side.jpg"
},
"ProductReviews": {
"FiveStar": [
"Excellent! Can't recommend it highly enough! Buy it!",
"Do yourself a favor and buy this."
],
"OneStar": [
"Terrible product! Do not buy this."
]
},
"Comment": "This product sells out quickly during the summer",
"Safety.Warning": "Always wear a helmet"
}
```
Tenga en cuenta lo siguiente:
+ El valor de la clave de partición (`Id`) es `123`. No hay clave de ordenación.
+ Los tipos de datos de la mayoría de los atributos son escalares, tales como `String`, `Number`, `Boolean` y `Null`.
+ Un atributo (`Color`) es de tipo `String Set`.
+ Los siguientes atributos tienen tipos de datos de documento:
+ Una lista de `RelatedItems`. Cada componente es un `Id` de un producto relacionado.
+ Mapa de imágenes () `Pictures`. Cada componente es una descripción breve de una imagen, junto con una dirección URL del archivo de imagen correspondiente.
+ Mapa de imágenes () `ProductReviews`. Cada componente representa una clasificación y una lista de opiniones correspondientes a esa clasificación. Inicialmente, este mapa se rellena con opiniones de cinco estrellas y una estrella.
## Atributos de nivel superior
Se considera que un atributo es de *nivel superior* si no está integrado en otro atributo. En el elemento `ProductCatalog`, los atributos de nivel superior son:
+ `Id`
+ `Title`
+ `Description`
+ `BicycleType`
+ `Brand`
+ `Price`
+ `Color`
+ `ProductCategory`
+ `InStock`
+ `QuantityOnHand`
+ `RelatedItems`
+ `Pictures`
+ `ProductReviews`
+ `Comment`
+ `Safety.Warning`
Todos estos atributos de nivel superior son escalares, con la salvedad de `Color` (lista), `RelatedItems` (lista), `Pictures` (mapa) y `ProductReviews` (mapa).
## Atributos anidados
Se considera que un atributo es *anidado* si está integrado en otro atributo. Para obtener acceso a un atributo anidado, se utilizan los *operadores de desreferenciación*:
+ `[n]`: para elementos de lista
+ `.` (punto): para elementos de mapa
### Acceso a los elementos de la lista
El operador de desreferencia de un elemento de la lista es **[*N*]**, donde *n* es el número del elemento. Las entradas de lista están basadas en cero; es decir, [0] representa la primera entrada de la lista, [1] representa la segunda, y así sucesivamente. Estos son algunos ejemplos:
+ `MyList[0]`
+ `AnotherList[12]`
+ `ThisList[5][11]`
La entrada `ThisList[5]` es una lista anidada en sí misma. Por consiguiente, `ThisList[5][11]` se refiere al duodécimo componente de esa lista.
El número contenido entre corchetes debe ser un entero no negativo. Por lo tanto, las siguientes expresiones no son válidas:
+ `MyList[-1]`
+ `MyList[0.4]`
### Acceso a los elementos de un mapa
El operador de desreferenciación de una entrada de un mapa es **. ** (un punto). Utilice el punto como separador entre las entradas de un mapa:
+ `MyMap.nestedField`
+ `MyMap.nestedField.deeplyNestedField`
## Rutas de documento
En una expresión, se utiliza una *ruta de documento* para indicar a DynamoDB dónde se encuentra un atributo. En el caso de un atributo de nivel superior, la ruta de documento es el nombre de atributo. En el caso de un atributo anidado, se utilizan operadores de desreferenciación para construir la ruta de documento.
A continuación se indican algunos ejemplos de rutas de documentos. Consulte el elemento mostrado en . [Referencia a atributos de elementos mediante expresiones en DynamoDB](#Expressions.Attributes).)
+ Atributo escalar de nivel superior.
`Description`
+ Atributo de lista de nivel superior. (Devuelve la lista completa, no solo algunos de los componentes).
`RelatedItems`
+ Tercera entrada de la lista `RelatedItems`. Recuerde que las entradas de lista se basan en cero.
`RelatedItems[2]`
+ Imagen frontal del producto.
`Pictures.FrontView`
+ Todas las opiniones de cinco estrellas.
`ProductReviews.FiveStar`
+ Primera de las opiniones de cinco estrellas.
`ProductReviews.FiveStar[0]`
**nota**
La profundidad máxima de una ruta de documento es 32. Por lo tanto, el número de operadores de desreferenciación de una ruta no puede superar este límite.
Puede utilizar cualquier nombre de atributo en la ruta de un documento siempre que cumpla estos requisitos:
+ El primer carácter es `a-z`, `A-Z` o `0-9`
+ El segundo carácter (si está presente) es `a-z` o `A-Z`
**nota**
Si un nombre de atributo no cumple este requisito, tendrá que definir un nombre de atributo de expresión como marcador de posición.
Para obtener más información, consulte [Nombres de atributos de expresión (Alias) en DynamoDB](Expressions.ExpressionAttributeNames.md).
# Nombres de atributos de expresión (Alias) en DynamoDB
Un *nombre de atributo de expresión* es un alias (o marcador de posición) que se utiliza en una expresión de Amazon DynamoDB en lugar del nombre de atributo real. Un nombre de atributo de expresión debe comenzar por un signo de almohadilla (`#`) y debe ir seguido de uno o más caracteres alfanuméricos. También se permite el carácter de subrayado (`_`).
En esta sección se describen varias situaciones en las que debe utilizar nombres de atributos de expresión.
**nota**
En los ejemplos de esta sección se utiliza la AWS Command Line Interface (AWS CLI).
**Topics**
+ [Palabras reservadas](#Expressions.ExpressionAttributeNames.ReservedWords)
+ [Nombres de atributo que contienen caracteres especiales](#Expressions.ExpressionAttributeNames.AttributeNamesContainingSpecialCharacters)
+ [Atributos anidados](#Expressions.ExpressionAttributeNames.NestedAttributes)
+ [Hacer referencia repetidamente a nombres de atributos](#Expressions.ExpressionAttributeNames.RepeatingAttributeNames)
## Palabras reservadas
En algunas ocasiones, es posible que necesite escribir una expresión que contenga un nombre de atributo que entre en conflicto con una palabra reservada de DynamoDB. Para obtener una lista completa de palabras reservadas, consulte . [Palabras reservadas en DynamoDB](ReservedWords.md).)
Por ejemplo, el siguiente ejemplo de la AWS CLI no funcionaría correctamente porque `COMMENT` es una palabra reservada,
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "Comment"
```
Para solucionar este problema, puede sustituir `Comment` por un nombre de atributo de expresión; por ejemplo, `#c`. El símbolo de almohadilla (`#`) es obligatorio e indica que se trata de un marcador de posición del nombre de un atributo. Ahora, el ejemplo de la AWS CLI tendría el siguiente aspecto.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "#c" \
--expression-attribute-names '{"#c":"Comment"}'
```
**nota**
Si un nombre de atributo comienza por un número, contiene un espacio o contiene una palabra reservada, *debe* utilizar un nombre de atributo de expresión para reemplazar el nombre de ese atributo en la expresión.
## Nombres de atributo que contienen caracteres especiales
En una expresión, un punto (".") se interpreta como un carácter separador en una ruta de documento. No obstante, DynamoDB también le permite utilizar un carácter de punto y otros caracteres especiales, como un guion ("-") como parte de un nombre de atributo. En algunos casos, esto puede dar lugar a ambigüedades. A modo de ejemplo, supongamos que desea recuperar el atributo `Safety.Warning` de un elemento `ProductCatalog` (consulte [Referencia a atributos de elementos mediante expresiones en DynamoDB](Expressions.Attributes.md)).
Supongamos que desea obtener acceso a `Safety.Warning` mediante una expresión de proyección.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "Safety.Warning"
```
DynamoDB podría devolver un resultado vacío, en lugar de la cadena prevista ("`Always wear a helmet`"). El motivo es que DynamoDB interpreta el punto en una expresión como un separador de ruta de documento. En este caso, tiene que definir un nombre de atributo de expresión (por ejemplo, `#sw`) como sustituto de `Safety.Warning`. A continuación, podría utilizar la siguiente expresión de proyección.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "#sw" \
--expression-attribute-names '{"#sw":"Safety.Warning"}'
```
Ahora, DynamoDB devolvería el resultado correcto.
**nota**
Si un nombre de atributo contiene un punto (".") o un guion ("-"), *debe* utilizar un nombre de atributo de expresión para reemplazar el nombre de ese atributo en la expresión.
## Atributos anidados
Suponga que desea acceder al atributo anidado `ProductReviews.OneStar`. En el nombre de un atributo de expresión, DynamoDB trata el punto (".") como un carácter del nombre del atributo. Para hacer referencia al atributo anidado, defina un nombre de atributo de expresión para cada elemento de la ruta del documento:
+ `#pr — ProductReviews`
+ `#1star — OneStar`
A continuación, habría que usar `#pr.#1star` para la expresión de proyección.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "#pr.#1star" \
--expression-attribute-names '{"#pr":"ProductReviews", "#1star":"OneStar"}'
```
Ahora, DynamoDB devolvería el resultado correcto.
## Hacer referencia repetidamente a nombres de atributos
Expresión los nombres de atributos de expresión resultan útiles cuando es preciso consultar repetidamente el mismo nombre de atributo. Por ejemplo, tomemos la siguiente expresión para recuperar algunas de las opiniones de un elemento de `ProductCatalog`.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "ProductReviews.FiveStar, ProductReviews.ThreeStar, ProductReviews.OneStar"
```
Para que resulte más concisa, puede sustituir `ProductReviews` por un nombre de atributo de expresión, como `#pr`. Ahora, la expresión revisada tendría el siguiente aspecto.
+ `#pr.FiveStar, #pr.ThreeStar, #pr.OneStar`
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"123"}}' \
--projection-expression "#pr.FiveStar, #pr.ThreeStar, #pr.OneStar" \
--expression-attribute-names '{"#pr":"ProductReviews"}'
```
Si define un nombre de atributo de expresión, debe usarlo de forma coherente en toda la expresión. Además, es importante no omitir el signo `#`.
# Uso de valores de atributos de expresión en DynamoDB
*Los valores de los atributos de expresión* de Amazon DynamoDB actúan como variables. Reemplazan a los valores reales que se desea comparar, que podrían no conocerse hasta el tiempo de ejecución. Un valor de atributo de expresión debe comenzar por un signo de dos puntos (`:`) y debe ir seguido de uno o más caracteres alfanuméricos.
Por ejemplo, supongamos que desea devolver todos los elementos de `ProductCatalog`que estén disponibles en el color `Black` y tengan un precio de `500` o menos. Podría utilizar una operación `Scan` con una expresión de filtro, como en este ejemplo de la AWS Command Line Interface (AWS CLI).
```
aws dynamodb scan \
--table-name ProductCatalog \
--filter-expression "contains(Color, :c) and Price <= :p" \
--expression-attribute-values file://values.json
```
Los argumentos de `--expression-attribute-values` se almacenan en el archivo `values.json`.
```
{
":c": { "S": "Black" },
":p": { "N": "500" }
}
```
Si define un valor de atributo de expresión, debe usarlo de forma coherente en toda la expresión. Además, es importante no omitir el signo `:`.
Los valores de atributos de expresión se usan con expresiones de condición de clave, expresiones de condición, expresiones de actualización y expresiones de filtro.
# Uso de expresiones de proyección en DynamoDB
Para leer datos de una tabla, se utilizan operaciones tales como `GetItem`, `Query` o `Scan`. De forma predeterminada, Amazon DynamoDB devuelve todos los atributos de los elementos. Si desea obtener solo uno en lugar de todos ellos, debe usar una expresión de proyección.
Una *expresión de proyección* es una cadena que identifica los atributos que se desea. Para recuperar un solo atributo, especifique su nombre. Si desea obtener varios atributos, separe sus nombres mediante comas.
A continuación se muestran ejemplos de expresiones de proyección basadas en el elemento `ProductCatalog` de [Referencia a atributos de elementos mediante expresiones en DynamoDB](Expressions.Attributes.md):
+ Un solo atributo de nivel superior.
`Title `
+ Tres atributos de nivel superior. DynamoDB recupera todo el conjunto `Color`.
`Title, Price, Color`
+ Cuatro atributos de nivel superior. DynamoDB devolverá todo el contenido de `RelatedItems` y `ProductReviews`.
`Title, Description, RelatedItems, ProductReviews`
**nota**
La expresión de proyección no modifica el consumo de rendimiento aprovisionado. DynamoDB determina las unidades de capacidad consumidas según el tamaño de los elementos y no según la cantidad de datos que se devuelven a una aplicación.
**Palabras reservadas y caracteres especiales**
DynamoDB tiene palabras reservadas y caracteres especiales. DynamoDB le permite utilizar estas palabras reservadas y caracteres especiales para nombres, pero le recomendamos que evite hacerlo, porque tendría que usar alias para ellos cada vez que utilizase estos nombres en una expresión. Para ver una lista completa, consulte [Palabras reservadas en DynamoDB](ReservedWords.md).
Deberá usar los nombres de los atributos de la expresión en lugar del nombre real si:
+ El nombre del atributo está en la lista de palabras reservadas en DynamoDB.
+ El nombre del atributo no cumple el requisito de que el primer carácter sea `a-z` o `A-Z` y que el segundo carácter (si lo hay) sea `a-Z`, `A-Z` o `0-9`.
+ El nombre del atributo contiene un signo **\$1** (hash) o **:** (dos puntos).
En el ejemplo de la AWS CLI siguiente se muestra cómo usar una expresión de proyección con una operación `GetItem`. La expresión de proyección recupera un atributo escalar de nivel superior (`Description`), la primera entrada de una lista (`RelatedItems[0]`) y una lista anidada en un mapa (`ProductReviews.FiveStar`).
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '"Id": { "N": "123" } \
--projection-expression "Description, RelatedItems[0], ProductReviews.FiveStar"
```
Para este ejemplo, se devolvería el siguiente código JSON.
```
{
"Item": {
"Description": {
"S": "123 description"
},
"ProductReviews": {
"M": {
"FiveStar": {
"L": [
{
"S": "Excellent! Can't recommend it highly enough! Buy it!"
},
{
"S": "Do yourself a favor and buy this."
}
]
}
}
},
"RelatedItems": {
"L": [
{
"N": "341"
}
]
}
}
}
```
# Uso de expresiones de actualización en DynamoDB
La acción `UpdateItem` actualiza un elemento existente o agrega uno nuevo a la tabla, si no existe ya. Es preciso proporcionar la clave del elemento que se desea actualizar. Asimismo, debe proporcionar una expresión de actualización que indique los atributos que se van a modificar y los valores que se les asignarán.
Una *expresión de actualización* especifica cómo `UpdateItem` modificará los atributos de un elemento; por ejemplo, estableciendo un valor escalar o eliminando elementos de una lista o un mapa.
A continuación se muestra un resumen de la sintaxis de las expresiones de actualización.
```
update-expression ::=
[ SET action [, action] ... ]
[ REMOVE action [, action] ...]
[ ADD action [, action] ... ]
[ DELETE action [, action] ...]
```
Una expresión de actualización consta de una o varias cláusulas. Cada cláusula comienza con una palabra clave `SET`, `REMOVE`, `ADD` o `DELETE`. Puede incluir cualquiera de estas cláusulas en una expresión de actualización, en cualquier orden. Sin embargo, cada palabra clave de acción solo puede aparecer una vez.
Cada cláusula contiene una o más acciones, separadas por comas. Cada acción representa una modificación de datos.
Los ejemplos que aparecen en esta sección se basan en el elemento `ProductCatalog` que se muestra en [Uso de expresiones de proyección en DynamoDB](Expressions.ProjectionExpressions.md).
En los temas siguientes se describen algunos casos de uso diferentes de la acción `SET`.
**Topics**
+ [SET: modificación o adición de atributos de elemento](#Expressions.UpdateExpressions.SET)
+ [REMOVE: eliminación de atributos de un elemento](#Expressions.UpdateExpressions.REMOVE)
+ [ADD: actualización de números y conjuntos](#Expressions.UpdateExpressions.ADD)
+ [DELETE: eliminación de elementos de un conjunto](#Expressions.UpdateExpressions.DELETE)
+ [Uso de varias expresiones de actualización](#Expressions.UpdateExpressions.Multiple)
## SET: modificación o adición de atributos de elemento
Utilice la acción `SET` en una expresión de actualización para agregar uno o varios atributos a un elemento. Si cualquiera de estos atributos ya existe, se sobrescribirá con los nuevos valores. Si desea evitar sobrescribir un atributo existente, puede utilizar `SET` con la función `if_not_exists`. La función `if_not_exists` es específica de la acción `SET` y solamente se puede utilizar en una expresión de actualización.
Cuando se utiliza `SET` para actualizar una entrada de lista, el contenido de esa entrada se sustituye por los nuevos datos que ha especificado. Si el componente no existe, `SET` adjunta el nuevo componente al final de la lista.
Si agrega varias entradas en una misma operación `SET`, las entradas se ordenan según su número.
También puede utilizar `SET` para sumar o restar un valor de un atributo de tipo `Number`. Para llevar a cabo varias acciones `SET`, debe separarlas por comas.
En el resumen de sintaxis siguiente:
+ El componente *path* es la ruta de documento del elemento.
+ Un componente **operand** puede ser una ruta de documento a un elemento o una función.
```
set-action ::=
path = value
value ::=
operand
| operand '+' operand
| operand '-' operand
operand ::=
path | function
function ::=
if_not_exists (path, value)
```
Si el elemento no contiene un atributo en la ruta especificada, `if_not_exists` se evalúa en `value`. De lo contrario, se evalúa como `path`.
La siguiente operación `PutItem` crea un elemento de muestra 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.
```
{
"Id": {"N": "789"},
"ProductCategory": {"S": "Home Improvement"},
"Price": {"N": "52"},
"InStock": {"BOOL": true},
"Brand": {"S": "Acme"}
}
```
**Topics**
+ [Modificación de atributos](#Expressions.UpdateExpressions.SET.ModifyingAttributes)
+ [Adición de listas y mapas](#Expressions.UpdateExpressions.SET.AddingListsAndMaps)
+ [Adición de elementos a una lista](#Expressions.UpdateExpressions.SET.AddingListElements)
+ [Adición de atributos de mapa anidados](#Expressions.UpdateExpressions.SET.AddingNestedMapAttributes)
+ [Aumento y reducción de atributos numéricos](#Expressions.UpdateExpressions.SET.IncrementAndDecrement)
+ [Adición de elementos a una lista](#Expressions.UpdateExpressions.SET.UpdatingListElements)
+ [Cómo evitar sobrescribir un atributo existente](#Expressions.UpdateExpressions.SET.PreventingAttributeOverwrites)
### Modificación de atributos
**Example**
Actualice los atributos `ProductCategory` y `Price`.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET ProductCategory = :c, Price = :p" \
--expression-attribute-values file://values.json \
--return-values ALL_NEW
```
Los argumentos de `--expression-attribute-values` se almacenan en el archivo `values.json`.
```
{
":c": { "S": "Hardware" },
":p": { "N": "60" }
}
```
**nota**
En la operación `UpdateItem`, `--return-values ALL_NEW` hace que DynamoDB devuelva el elemento tal y como aparece después de la actualización.
### Adición de listas y mapas
**Example**
Agregue una lista y un mapa nuevos.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET RelatedItems = :ri, ProductReviews = :pr" \
--expression-attribute-values file://values.json \
--return-values ALL_NEW
```
Los argumentos de `--expression-attribute-values` se almacenan en el archivo `values.json`.
```
{
":ri": {
"L": [
{ "S": "Hammer" }
]
},
":pr": {
"M": {
"FiveStar": {
"L": [
{ "S": "Best product ever!" }
]
}
}
}
}
```
### Adición de elementos a una lista
**Example**
Agregue un nuevo atributo a la lista `RelatedItems`. Recuerde que las entradas de lista están basadas en cero; es decir, [0] representa la primera entrada de la lista, [1] representa la segunda, y así sucesivamente.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET RelatedItems[1] = :ri" \
--expression-attribute-values file://values.json \
--return-values ALL_NEW
```
Los argumentos de `--expression-attribute-values` se almacenan en el archivo `values.json`.
```
{
":ri": { "S": "Nails" }
}
```
**nota**
Cuando se utiliza `SET` para actualizar una entrada de lista, el contenido de esa entrada se sustituye por los nuevos datos que ha especificado. Si el componente no existe, `SET` adjunta el nuevo componente al final de la lista.
Si agrega varias entradas en una misma operación `SET`, las entradas se ordenan según su número.
### Adición de atributos de mapa anidados
**Example**
Agregue algunos atributos de mapa anidados.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET #pr.#5star[1] = :r5, #pr.#3star = :r3" \
--expression-attribute-names file://names.json \
--expression-attribute-values file://values.json \
--return-values ALL_NEW
```
Los argumentos de `--expression-attribute-names` se almacenan en el archivo `names.json`.
```
{
"#pr": "ProductReviews",
"#5star": "FiveStar",
"#3star": "ThreeStar"
}
```
Los argumentos de `--expression-attribute-values` se almacenan en el archivo `values.json`.
```
{
":r5": { "S": "Very happy with my purchase" },
":r3": {
"L": [
{ "S": "Just OK - not that great" }
]
}
}
```
**importante**
No puede actualizar los atributos de mapa anidados si el mapa principal no existe. Si intenta actualizar un atributo anidado (por ejemplo, `ProductReviews.FiveStar`) cuando el mapa principal (`ProductReviews`) no existe, DynamoDB devuelve un elemento `ValidationException` con el mensaje *«The document path provided in the update expression is invalid for update»*.
Al crear elementos cuyos atributos de mapa anidados se vayan a actualizar más adelante, inicialice los mapas vacíos para los atributos principales. Por ejemplo:
```
{
"Id": {"N": "789"},
"ProductReviews": {"M": {}},
"Metadata": {"M": {}}
}
```
Esto le permite actualizar los atributos anidados como `ProductReviews.FiveStar` sin errores.
### Aumento y reducción de atributos numéricos
Puede sumar o restar un valor a un atributo numérico. Para ello, se utilizan los operadores `+` (más) y `-` (menos).
**Example**
Reduzca el `Price` de un elemento.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET Price = Price - :p" \
--expression-attribute-values '{":p": {"N":"15"}}' \
--return-values ALL_NEW
```
Para aumentar el valor de `Price`, se utiliza el operador `+` en la expresión de actualización.
### Adición de elementos a una lista
Puede agregar componentes al final de una lista. Para ello, se utiliza `SET` con la función `list_append`. (El nombre de la función distingue entre mayúsculas y minúsculas). La función `list_append` es específica de la acción `SET` y solamente se puede utilizar en una expresión de actualización. La sintaxis es la siguiente.
+ `list_append (list1, list2)`
La función toma dos listas como entrada y anexa todos los elementos de `list2` a ` list1`.
**Example**
En [Adición de elementos a una lista](#Expressions.UpdateExpressions.SET.AddingListElements), ha creado la lista `RelatedItems` y ha incluido en ella dos componentes: `Hammer` y `Nails`. Ahora, va a agregar dos componentes más al final de `RelatedItems`.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET #ri = list_append(#ri, :vals)" \
--expression-attribute-names '{"#ri": "RelatedItems"}' \
--expression-attribute-values file://values.json \
--return-values ALL_NEW
```
Los argumentos de `--expression-attribute-values` se almacenan en el archivo `values.json`.
```
{
":vals": {
"L": [
{ "S": "Screwdriver" },
{"S": "Hacksaw" }
]
}
}
```
Por último, vamos a agregar un componente más al *principio* de `RelatedItems`. Para ello, invierta el orden de los componentes de `list_append`. (Recuerde que `list_append` toma dos listas como información de entrada y agrega la segunda lista a la primera).
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET #ri = list_append(:vals, #ri)" \
--expression-attribute-names '{"#ri": "RelatedItems"}' \
--expression-attribute-values '{":vals": {"L": [ { "S": "Chisel" }]}}' \
--return-values ALL_NEW
```
Ahora, el atributo `RelatedItems` resultante contiene cinco entradas, el siguiente orden: `Chisel`, `Hammer`, `Nails`, `Screwdriver` y `Hacksaw`.
### Cómo evitar sobrescribir un atributo existente
**Example**
Establezca el valor de `Price` de un elemento, pero solo si este no tiene ya un atributo `Price`. (Si `Price` ya existe, no sucede nada).
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET Price = if_not_exists(Price, :p)" \
--expression-attribute-values '{":p": {"N": "100"}}' \
--return-values ALL_NEW
```
## REMOVE: eliminación de atributos de un elemento
Utilice la acción `REMOVE` en una expresión de actualización para eliminar uno o varios atributos de un elemento en Amazon DynamoDB. Para llevar a cabo varias acciones `REMOVE`, debe separarlas por comas.
A continuación se muestra un resumen de la sintaxis de `REMOVE` en una expresión de actualización. El único operando es la ruta de documento del atributo que se desea eliminar.
```
remove-action ::=
path
```
**Example**
Elimine algunos atributos de un elemento. (Si el atributo no existe, no sucede nada).
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "REMOVE Brand, InStock, QuantityOnHand" \
--return-values ALL_NEW
```
### Eliminación de elementos de una lista
Puede utilizar `REMOVE` para eliminar entradas individuales de una lista.
**Example**
En [Adición de elementos a una lista](#Expressions.UpdateExpressions.SET.UpdatingListElements), ha modificado un atributo de lista (`RelatedItems`) para que contenga cinco componentes:
+ `[0]`—`Chisel`
+ `[1]`—`Hammer`
+ `[2]`—`Nails`
+ `[3]`—`Screwdriver`
+ `[4]`—`Hacksaw`
En el siguiente ejemplo de la AWS Command Line Interface (AWS CLI) se eliminan `Hammer` y `Nails` de la lista.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "REMOVE RelatedItems[1], RelatedItems[2]" \
--return-values ALL_NEW
```
Después de eliminar `Hammer` y `Nails`, los componentes restantes se reordenan. Ahora, la lista contiene lo siguiente:
+ `[0]`—`Chisel`
+ `[1]`—`Screwdriver`
+ `[2]`—`Hacksaw`
## ADD: actualización de números y conjuntos
**nota**
En general, recomendamos usar `SET` en lugar de `ADD` para garantizar operaciones idempotentes.
Utilice la acción `ADD` en una expresión de actualización para agregar un nuevo atributo y sus valores a un elemento.
Si el atributo ya existe, el comportamiento de `ADD` depende del tipo de datos del atributo:
+ Si el atributo es un número y el valor que se agrega también es un número, entonces el valor se suma matemáticamente al atributo existente. (Si el valor es un número negativo, entonces se resta del atributo existente).
+ Si el atributo es un conjunto y el valor que se agrega también es un conjunto, entonces el valor se agrega al conjunto existente.
**nota**
La acción `ADD` solo es compatible con los tipos de datos Number y Set.
Para llevar a cabo varias acciones `ADD`, debe separarlas por comas.
En el resumen de sintaxis siguiente:
+ El componente *path* es la ruta de documento de un atributo. El tipo de datos del atributo debe ser `Number` o Set.
+ El componente *value* es un número que se desea agregar al atributo (si el tipo de datos es `Number`) o un conjunto que se desea agregar al atributo (si el tipo de datos es Set).
```
add-action ::=
path value
```
En los temas siguientes se describen algunos casos de uso diferentes de la acción `ADD`.
**Topics**
+ [Adición de un número](#Expressions.UpdateExpressions.ADD.Number)
+ [Adición de elementos a un conjunto](#Expressions.UpdateExpressions.ADD.Set)
### Adición de un número
Supongamos que el atributo `QuantityOnHand` no existe. En el siguiente ejemplo de la AWS CLI, `QuantityOnHand` se establece en 5.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "ADD QuantityOnHand :q" \
--expression-attribute-values '{":q": {"N": "5"}}' \
--return-values ALL_NEW
```
Ahora que `QuantityOnHand` ya existe, puede volver a ejecutar el ejemplo para incrementar `QuantityOnHand` en 5 cada vez.
### Adición de elementos a un conjunto
Supongamos que el atributo `Color` no existe. En el siguiente ejemplo de la AWS CLI, `Color` se establece en un conjunto de cadenas que contiene dos componentes.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "ADD Color :c" \
--expression-attribute-values '{":c": {"SS":["Orange", "Purple"]}}' \
--return-values ALL_NEW
```
Ahora que `Color` ya existe, podemos agregarle más componentes.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "ADD Color :c" \
--expression-attribute-values '{":c": {"SS":["Yellow", "Green", "Blue"]}}' \
--return-values ALL_NEW
```
## DELETE: eliminación de elementos de un conjunto
**importante**
La acción `DELETE` solo es compatible con tipos de datos `Set`.
Utilice la acción `DELETE` en una expresión de actualización para eliminar una o varias entradas de un conjunto. Para llevar a cabo varias acciones `DELETE`, debe separarlas por comas.
En el resumen de sintaxis siguiente:
+ El componente *path* es la ruta de documento de un atributo. El tipo de datos del atributo debe ser Set.
+ *Subset* representa uno o varios componentes que se van a eliminar de *path*. Para *subset* debe especificar un tipo de datos Set.
```
delete-action ::=
path subset
```
**Example**
En [Adición de elementos a un conjunto](#Expressions.UpdateExpressions.ADD.Set), crea el conjunto de cadenas `Color`. En este ejemplo se eliminan algunos de los componentes de ese conjunto.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "DELETE Color :p" \
--expression-attribute-values '{":p": {"SS": ["Yellow", "Purple"]}}' \
--return-values ALL_NEW
```
## Uso de varias expresiones de actualización
Puede utilizar varias acciones en una sola expresión de actualización. Todas las referencias de atributos se resuelven en función del estado del elemento antes de aplicar cualquiera de las acciones.
**Example**
Dado un elemento `{"id": "1", "a": 1, "b": 2, "c": 3}`, la siguiente expresión elimina `a` y desplaza los valores de `b` y `c`:
```
aws dynamodb update-item \
--table-name test \
--key '{"id":{"S":"1"}}' \
--update-expression "REMOVE a SET b = a, c = b" \
--return-values ALL_NEW
```
El resultado es `{"id": "1", "b": 1, "c": 2}`. Aunque `a` se elimina y `b` se reasigna en la misma expresión, ambas referencias se resuelven con sus valores originales.
**Example**
Si desea modificar el valor de un atributo y eliminar por completo otro, podría utilizar una acción SET y otra REMOVE en una sola instrucción. Esta operación reduciría el valor de `Price` a 15 a la vez que eliminaría el atributo `InStock` del elemento.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET Price = Price - :p REMOVE InStock" \
--expression-attribute-values '{":p": {"N":"15"}}' \
--return-values ALL_NEW
```
**Example**
Si desea agregar un elemento a una lista al mismo tiempo que cambia el valor de otro atributo, podría utilizar dos acciones SET en una sola instrucción. Esta operación agregaría "Nails" al atributo de la lista `RelatedItems` y también establecería el valor de `Price` a 21.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "SET RelatedItems[1] = :newValue, Price = :newPrice" \
--expression-attribute-values '{":newValue": {"S":"Nails"}, ":newPrice": {"N":"21"}}' \
--return-values ALL_NEW
```
# Expresiones, operadores y funciones de condición y filtro en DynamoDB
Para manipular datos en una tabla de DynamoDB, se usan las operaciones `PutItem`, `UpdateItem` y `DeleteItem`. Para estas operaciones de manipulación de datos, puede especificar una expresión de condición con el fin de determinar qué elementos deben modificarse. Si la expresión de condición se evalúa en true, entonces la operación se realiza correctamente. De lo contrario, la operación no se llevará a cabo correctamente.
En esta sección se describen las funciones y las palabras clave integradas para escribir expresiones de filtro y condición en Amazon DynamoDB. Para obtener más información sobre las funciones y la programación con DynamoDB, consulte [Programación con DynamoDB y los SDK de AWS](Programming.md) y la [Referencia de la API de DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/).
**Topics**
+ [Sintaxis de las expresiones de filtro y condición](#Expressions.OperatorsAndFunctions.Syntax)
+ [Realización de comparaciones](#Expressions.OperatorsAndFunctions.Comparators)
+ [Funciones](#Expressions.OperatorsAndFunctions.Functions)
+ [Evaluaciones lógicas](#Expressions.OperatorsAndFunctions.LogicalEvaluations)
+ [Paréntesis](#Expressions.OperatorsAndFunctions.Parentheses)
+ [Precedencia en las condiciones](#Expressions.OperatorsAndFunctions.Precedence)
## Sintaxis de las expresiones de filtro y condición
En el siguiente resumen de sintaxis, el componente *operand* puede ser uno de los siguientes:
+ Un nombre de atributo de nivel superior, como por ejemplo `Id`, `Title`, `Description` o `ProductCategory`
+ Una ruta de documento que hace referencia a un atributo anidado
```
condition-expression ::=
operand comparator operand
| operand BETWEEN operand AND operand
| operand IN ( operand (',' operand (, ...) ))
| function
| condition AND condition
| condition OR condition
| NOT condition
| ( condition )
comparator ::=
=
| <>
| <
| <=
| >
| >=
function ::=
attribute_exists (path)
| attribute_not_exists (path)
| attribute_type (path, type)
| begins_with (path, substr)
| contains (path, operand)
| size (path)
```
## Realización de comparaciones
Utilice estos comparadores para comparar un operando con un solo valor:
+ `a = b`: es true si *a* es igual que *b*.
+ `a <> b`: es true si *a* es distinto de *b*.
+ `a < b`: es true si *a* es menor que *b*.
+ `a <= b`: es true si *a* es menor o igual que *b*.
+ `a > b`: es true si *a* es mayor que *b*.
+ `a >= b`: es true si *a* es mayor o igual que *b*.
Use las palabras clave `BETWEEN` e `IN` para comparar un operando con un rango o una lista de valores:
+ `a BETWEEN b AND c`: es true si *a* es mayor o igual que *b* y menor o igual que *c*.
+ `a IN (b, c, d) `: es true si *a* es igual a cualquiera de los valores de la lista; por ejemplo, en este caso, a *b*, *c* o *d*. La lista puede contener hasta 100 valores separadas por comas.
## Funciones
Utilice las siguientes funciones para determinar si un atributo existe en un elemento o evaluar el valor de un atributo. Los nombres de estas funciones distinguen entre mayúsculas y minúsculas. En el caso de los atributos anidados, debe proporcionar su ruta de documento completa.
****
| Función | Descripción |
| --- | --- |
| `attribute_exists (path)` | Es true si el elemento contiene el atributo especificado por `path`. Ejemplo: Comprobación de si un elemento de la tabla `Product` tiene una imagen de vista lateral. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) |
| `attribute_not_exists (path)` | Es true si el atributo especificado en `path` no está presente en el elemento. Ejemplo: Comprobación de si un elemento tiene el atributo `Manufacturer`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) |
| `attribute_type (path, type)` | Es true si el atributo de la ruta especificada es de un tipo de datos determinado. El parámetro `type` debe ser uno de los siguientes: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Debe utilizar un valor de atributo de expresión para el parámetro `type`. Ejemplo: Comprobación de si el atributo `QuantityOnHand` es del tipo List. En este ejemplo, `:v_sub` es un marcador de posición para la `L`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Debe utilizar un valor de atributo de expresión para el parámetro `type`. |
| `begins_with (path, substr)` | Es true si el atributo especificado por `path` comienza por una subcadena determinada. Ejemplo: Comprobación de si los primeros caracteres de la URL de la imagen de vista frontal son `http://`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) El valor de atributo de expresión `:v_sub` es un marcador de posición para `http://`. |
| `contains (path, operand)` | Es true si el atributo especificado por `path` es uno de los siguientes: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Si el atributo especificado por `path` es un `String`, el `operand` debe ser un `String`. Si el atributo especificado por `path` es un `Set`, el `operand` debe ser el tipo de elemento del conjunto. La ruta y el operando deben ser distintos. Es decir, `contains (a, a)` devuelve un error. Ejemplo: Comprobación de si el atributo `Brand` contiene la subcadena `Company`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) El valor de atributo de expresión `:v_sub` es un marcador de posición para `Company`. Ejemplo: Comprobación de si el producto está disponible en color rojo. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) El valor de atributo de expresión `:v_sub` es un marcador de posición para `Red`. |
| `size (path)` | Devuelve un número que representa el tamaño de un atributo. A continuación se muestran los tipos de datos válidos para usarlos con `size`. Si el atributo es de tipo `String`, `size` devuelve la longitud de la cadena. Ejemplo: Comprobación de si la cadena `Brand` es menor o igual que 20 caracteres. El valor de atributo de expresión `:v_sub` es un marcador de posición para `20`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Si el atributo es de tipo `Binary`, `size` devuelve el número de bytes del valor del atributo. Ejemplo: supongamos que el elemento `ProductCatalog` tiene un atributo binario denominado `VideoClip` que contiene vídeo breve sobre el uso del producto. En la siguiente expresión se comprueba si `VideoClip` supera los 64 000 bytes. El valor de atributo de expresión `:v_sub` es un marcador de posición para `64000`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Si el tipo de datos del atributo es `Set`, `size` devuelve el número de componentes del conjunto. Ejemplo: Comprobación de si el producto está disponible en más de un color. El valor de atributo de expresión `:v_sub` es un marcador de posición para `1`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) Si el atributo es de tipo `List` o `Map`, `size` devuelve el número de componentes secundarios. Ejemplo: Comprobación de si el número de opiniones `OneStar` ha superado un umbral determinado. El valor de atributo de expresión `:v_sub` es un marcador de posición para `3`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) |
## Evaluaciones lógicas
Utilice las palabras clave `AND`, `OR` y `NOT` para llevar a cabo evaluaciones lógicas. En la lista siguiente, *a* y *b* representan las condiciones que se van a evaluar.
+ `a AND b`: es true si *a* y *b* son true.
+ `a OR b`: es true si *a* o *b* (o ambas) son true.
+ `NOT a`: es true si *a* es false. False si *a* es true.
A continuación se muestra un ejemplo de código de AND en una operación.
`dynamodb-local (*)> select * from exprtest where a > 3 and a < 5;`
## Paréntesis
Los paréntesis se utilizan para cambiar la preferencia de una evaluación lógica. Por ejemplo, supongamos que las condiciones *a* y *b* son true y que la condición *c* es false. La siguiente expresión se evalúa en true:
+ `a OR b AND c`
Sin embargo, si se incluye una condición entre paréntesis, esta se evalúa antes. Por ejemplo, lo siguiente se evalúa en false:
+ `(a OR b) AND c`
**nota**
En una expresión se pueden utilizar paréntesis anidados. En este caso, se evalúan primero los más internos.
A continuación se muestra un ejemplo de código con paréntesis en una evaluación lógica.
`dynamodb-local (*)> select * from exprtest where attribute_type(b, string) or ( a = 5 and c = “coffee”);`
## Precedencia en las condiciones
DynamoDB evalúa las condiciones de izquierda a derecha aplicando las siguientes normas de prioridad:
+ `= <> < <= > >=`
+ `IN`
+ `BETWEEN`
+ `attribute_exists attribute_not_exists begins_with contains`
+ Paréntesis
+ `NOT`
+ `AND`
+ `OR`
# 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.
```
{
"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
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 la clave principal existe en la tabla antes de intentar la operación de escritura.
**nota**
Si la clave principal consta de una clave de partición (pk) y una clave de clasificación (sk), el parámetro comprobará si `attribute_not_exists(pk)` Y `attribute_not_exists(sk)` se evalúan como verdadero o falso como una instrucción completa antes de intentar la operación de escritura.
```
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
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`.
```
{
":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
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`.
```
{
":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
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
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
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.
```
{
":v_sub":{"S":"SS"}
}
```
### Comprobación del valor inicial de cadena
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.
```
{
":v_sub":{"S":"http://"}
}
```
### Comprobación de un elemento en un conjunto
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.
```
{
":v_sub":{"S":"Red"}
}
```
### Comprobación del tamaño de un valor de atributo
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.
```
{
":v_sub":{"N":"64000"}
}
```