# Instrucciones PartiQL para DynamoDB
<a name="ql-reference.statements"></a>

Amazon DynamoDB admite las siguientes instrucciones PartiQL.

**nota**  
DynamoDB no es compatible con todas las instrucciones PartiQL.  
Esta referencia proporciona sintaxis básica y ejemplos de uso de instrucciones PartiQL que se ejecutan manualmente mediante la AWS CLI o API.

*Lenguaje de manipulación de datos*(DML) es el conjunto de instrucciones PartiQL que se utiliza para administrar datos en tablas de DynamoDB. Puede usar instrucciones DML para agregar, modificar o eliminar datos de una tabla.

Se admiten las siguientes instrucciones DML y lenguaje de consulta:
+ [Instrucciones de selección de PartiQL para DynamoDB](ql-reference.select.md)
+ [Instrucciones de actualización de PartiQL para DynamoDB](ql-reference.update.md)
+ [Instrucciones de inserción de PartiQL para DynamoDB](ql-reference.insert.md)
+ [Instrucciones de eliminación de PartiQL para DynamoDB](ql-reference.delete.md)

[Realización de transacciones con PartiQL para DynamoDB](ql-reference.multiplestatements.transactions.md) y [Ejecución de operaciones por lote con PartiQL para DynamoDB](ql-reference.multiplestatements.batching.md) también son compatibles con PartiQL para DynamoDB.

# Instrucciones de selección de PartiQL para DynamoDB
<a name="ql-reference.select"></a>

Se utiliza la instrucción `SELECT` para recuperar datos de una tabla de Amazon DynamoDB.

Si se usa la instrucción `SELECT` se puede generar un análisis completo de la tabla si no se proporciona una condición de igualdad o IN con una clave de partición en la cláusula WHERE. La operación de análisis examina cada elemento para comprobar si presenta los valores solicitados y permite utilizar el rendimiento aprovisionado para una tabla o un índice grandes en una sola operación. 

Si desea evitar el análisis completo de la tabla en PartiQL, puede:
+ Cree su instrucción `SELECT` para que no resulten en análisis completos de la tabla asegurándose de que su [condición de la cláusula WHERE](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.select.html#ql-reference.select.parameters) se configura en consecuencia.
+ Desactive los análisis completos de tablas mediante la política de IAM especificada en [Ejemplo: permitir instrucciones Select y denegar instrucciones de análisis de tabla completa en PartiQL para DynamoDB](ql-iam.md#access-policy-ql-iam-example6), en la guía para desarrolladores de DynamoDB.

Para obtener más información, consulte [Prácticas recomendadas para consultar y examinar datos](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-query-scan.html), en la guía para desarrolladores de DynamoDB.

**Topics**
+ [Sintaxis](#ql-reference.select.syntax)
+ [Parameters](#ql-reference.select.parameters)
+ [Ejemplos](#ql-reference.select.examples)

## Sintaxis
<a name="ql-reference.select.syntax"></a>

```
SELECT expression  [, ...] 
FROM table[.index]
[ WHERE condition ] [ [ORDER BY key [DESC|ASC] , ...]
```

## Parameters
<a name="ql-reference.select.parameters"></a>

***expression***  
(Requerido) Una proyección formada a partir del comodín `*` o una lista de proyección de uno o más nombres de atributos o rutas de documentos del conjunto de resultados. Una expresión puede consistir en llamadas a [Uso de funciones de PartiQL con DynamoDB](ql-functions.md) o campos modificados por [Operadores aritméticos, comparativos y lógicos de PartiQL para DynamoDB](ql-operators.md).

***table***  
(Necesario) Nombre de la tabla que se va a consultar.

***Índice de***  
(Opcional) El nombre del índice que se consultará.  
Debe agregar comillas dobles al nombre de la tabla y al nombre del índice al consultar uno.  

```
SELECT * 
FROM "TableName"."IndexName"
```

***condition***  
(Opcional) Criterios de selección para la consulta.  
Para asegurarse de que una instrucción `SELECT` no da como resultado un análisis completo de la tabla, la condición de cláusula `WHERE` debe especificar una clave de partición. Utilice el operador de igualdad o IN.  
Por ejemplo, si tiene una tabla `Orders` con una clave de partición `OrderID`y otros atributos que no son clave, incluido una `Address`, las siguientes instrucciones no resultarían en un análisis completo de la tabla:  

```
SELECT * 
FROM "Orders" 
WHERE OrderID = 100

SELECT * 
FROM "Orders" 
WHERE OrderID = 100 and Address='some address'

SELECT * 
FROM "Orders" 
WHERE OrderID = 100 or OrderID = 200

SELECT * 
FROM "Orders" 
WHERE OrderID IN [100, 300, 234]
```
Las siguientes instrucciones de `SELECT`, sin embargo, resultarán en un análisis completo de la tabla:  

```
SELECT * 
FROM "Orders" 
WHERE OrderID > 1

SELECT * 
FROM "Orders" 
WHERE Address='some address'

SELECT * 
FROM "Orders" 
WHERE OrderID = 100 OR Address='some address'
```

***clave***  
(Opcional) Una clave hash o una clave de ordenación que se va a utilizar para ordenar los resultados devueltos. El orden predeterminado es ascendente (`ASC`) especifique `DESC` si desea que los resultados se vuelvan a ejecutar en orden descendente.

**nota**  
Si omite la cláusula `WHERE`, se recuperarán todos los elementos de la tabla.

## Ejemplos
<a name="ql-reference.select.examples"></a>

La siguiente consulta devuelve un elemento, si existe, de la tabla `Orders` especificando la clave de partición, `OrderID` y utilizando el operador de igualdad.

```
SELECT OrderID, Total
FROM "Orders"
WHERE OrderID = 1
```

La siguiente consulta devuelve todos los elementos de la tabla `Orders` que tiene una clave de partición determinada, `OrderID`, valores utilizando el operador OR.

```
SELECT OrderID, Total
FROM "Orders"
WHERE OrderID = 1 OR OrderID = 2
```

La siguiente consulta devuelve todos los elementos de la tabla `Orders` que tiene una clave de partición determinada, `OrderID`, valores utilizando el operador IN. Los resultados devueltos están en orden descendente, basados en el valor del atributo clave `OrderID`.

```
SELECT OrderID, Total
FROM "Orders"
WHERE OrderID IN [1, 2, 3] ORDER BY OrderID DESC
```

La siguiente consulta muestra un análisis de tabla completo que devuelve todos los elementos de la tabla `Orders` que tienen un `Total` mayor que 500, donde `Total` es un atributo que no es clave.

```
SELECT OrderID, Total 
FROM "Orders"
WHERE Total > 500
```

La siguiente consulta muestra un análisis de tabla completo que devuelve todos los elementos de la tabla `Orders` con un rango de orden `Total`, utilizando el operador IN y un atributo que no es clave `Total`.

```
SELECT OrderID, Total 
FROM "Orders"
WHERE Total IN [500, 600]
```

La siguiente consulta muestra un análisis de tabla completo que devuelve todos los elementos de la tabla `Orders` dentro de un rango de orden `Total` específico, utilizando el operador BETWEEN y un atributo que no es clave `Total`.

```
SELECT OrderID, Total 
FROM "Orders" 
WHERE Total BETWEEN 500 AND 600
```

La siguiente consulta devuelve la primera fecha en que se utilizó un dispositivo firestick para ver especificando la clave de partición `CustomerID` y la clave de ordenación `MovieID` en la condición de cláusula WHERE y utilizando rutas de documento en la cláusula SELECT.

```
SELECT Devices.FireStick.DateWatched[0] 
FROM WatchList 
WHERE CustomerID= 'C1' AND MovieID= 'M1'
```

La siguiente consulta muestra un análisis de tabla completo que devuelve la lista de elementos en los que un dispositivo de firestick se utilizó por primera vez después del 24/12/19 mediante rutas de documento en la condición de cláusula WHERE.

```
SELECT Devices 
FROM WatchList 
WHERE Devices.FireStick.DateWatched[0] >= '12/24/19'
```

# Instrucciones de actualización de PartiQL para DynamoDB
<a name="ql-reference.update"></a>

Use la instrucción `UPDATE` para modificar el valor de uno o más atributos dentro de un elemento de una tabla de Amazon DynamoDB. 

**nota**  
Sólo puede actualizar un elemento a la vez; no puede emitir una sola instrucción de DynamoDB PartiQL que actualice varios elementos. Para obtener información sobre cómo actualizar varios elementos, consulte [Realización de transacciones con PartiQL para DynamoDB](ql-reference.multiplestatements.transactions.md) or [Ejecución de operaciones por lote con PartiQL para DynamoDB](ql-reference.multiplestatements.batching.md).

**Topics**
+ [Sintaxis](#ql-reference.update.syntax)
+ [Parameters](#ql-reference.update.parameters)
+ [Valor devuelto](#ql-reference.update.return)
+ [Ejemplos](#ql-reference.update.examples)

## Sintaxis
<a name="ql-reference.update.syntax"></a>

```
UPDATE  table  
[SET | REMOVE]  path  [=  data] […]
WHERE condition [RETURNING returnvalues]
<returnvalues>  ::= [ALL OLD | MODIFIED OLD | ALL NEW | MODIFIED NEW] *
```

## Parameters
<a name="ql-reference.update.parameters"></a>

***table***  
(Necesario) Tabla que contiene los datos que se van a modificar.

***path***  
(Necesario) Nombre de atributo o ruta de documento que se va a crear o modificar.

***data***  
(Necesario) Valor de atributo o resultado de una operación.  
Las operaciones admitidas para usar con SET:  
+ LIST\$1APPEND: agrega un valor a un tipo de lista.
+ SET\$1ADD: agrega un valor a un número o conjunto de cadenas.
+ SET\$1DELETE: elimina un valor de un número o conjunto de cadenas.

***condition***  
(Necesario) Criterios de selección para el elemento que se va a modificar. Esta condición debe resolverse con un único valor de clave principal.

***returnvalues***  
(Opcional) Utilizar `returnvalues` si desea obtener los atributos del elemento tal como aparecen antes o después de que se actualicen. Los valores válidos son:   
+ `ALL OLD *`: devuelve todos los atributos del elemento, tal y como aparecían antes de la operación de actualización.
+ `MODIFIED OLD *`: devuelve sólo los atributos actualizados, tal y como aparecían antes de la operación de actualización.
+ `ALL NEW *`: devuelve todos los atributos del elemento, tal como aparecen después de la operación de actualización.
+ `MODIFIED NEW *`: devuelve solamente los atributos actualizados, tal y como aparecen después de la operación `UpdateItem`.

## Valor devuelto
<a name="ql-reference.update.return"></a>

Esta instrucción no devuelve un valor a menos que se especifique el parámetro `returnvalues`.

**nota**  
Si la cláusula WHERE de la instrucción UPDATE no se evalúa como true (verdadero) para ningún elemento de la tabla DynamoDB, se devuelve `ConditionalCheckFailedException`.

## Ejemplos
<a name="ql-reference.update.examples"></a>

Actualiza el valor del atributo de un elemento existente en. Si el atributo no existe, se crea.

En la siguiente consulta se actualiza un elemento de la tabla `"Music"` agregando un atributo de tipo number (`AwardsWon`) y un atributo de tipo map (`AwardDetail`).

```
UPDATE "Music" 
SET AwardsWon=1 
SET AwardDetail={'Grammys':[2020, 2018]}  
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```

Puede agregar `RETURNING ALL OLD *` para devolver los atributos tal y como aparecían antes de la operación `Update`.

```
UPDATE "Music" 
SET AwardsWon=1 
SET AwardDetail={'Grammys':[2020, 2018]}  
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
RETURNING ALL OLD *
```

Devuelve lo siguiente:

```
{
    "Items": [
        {
            "Artist": {
                "S": "Acme Band"
            },
            "SongTitle": {
                "S": "PartiQL Rocks"
            }
        }
    ]
}
```

Puede agregar `RETURNING ALL NEW *` para devolver los atributos tal y como aparecían después de la operación `Update`.

```
UPDATE "Music" 
SET AwardsWon=1 
SET AwardDetail={'Grammys':[2020, 2018]}  
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
RETURNING ALL NEW *
```

Devuelve lo siguiente:

```
{
    "Items": [
        {
            "AwardDetail": {
                "M": {
                    "Grammys": {
                        "L": [
                            {
                                "N": "2020"
                            },
                            {
                                "N": "2018"
                            }
                        ]
                    }
                }
            },
            "AwardsWon": {
                "N": "1"
            }
        }
    ]
}
```

En la siguiente consulta se actualiza un elemento de la tabla `"Music"` agregando a una lista `AwardDetail.Grammys`.

```
UPDATE "Music" 
SET AwardDetail.Grammys =list_append(AwardDetail.Grammys,[2016])  
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```

En la siguiente consulta se actualiza un elemento de la tabla `"Music"` eliminando de una lista `AwardDetail.Grammys`.

```
UPDATE "Music" 
REMOVE AwardDetail.Grammys[2]   
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```

En la siguiente consulta se actualiza un elemento de la tabla `"Music"` agregando `BillBoard`al mapa`AwardDetail`.

```
UPDATE "Music" 
SET AwardDetail.BillBoard=[2020] 
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```

En la siguiente consulta se actualiza un elemento de la tabla `"Music"` agregando el atributo de conjunto de string `BandMembers`.

```
UPDATE "Music" 
SET BandMembers =<<'member1', 'member2'>> 
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```

En la siguiente consulta se actualiza un elemento de la tabla `"Music"` agregando `newbandmember` al conjunto de string `BandMembers`.

```
UPDATE "Music" 
SET BandMembers =set_add(BandMembers, <<'newbandmember'>>) 
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```

# Instrucciones de eliminación de PartiQL para DynamoDB
<a name="ql-reference.delete"></a>

Usar la instrucción `DELETE` para eliminar un elemento existente de la tabla de Amazon DynamoDB.

**nota**  
Solo puede eliminar de a un elemento a la vez. No puede emitir una sola instrucción de DynamoDB PartiQL que elimine varios elementos. Para obtener información sobre cómo eliminar varios elementos, consulte [Realización de transacciones con PartiQL para DynamoDB](ql-reference.multiplestatements.transactions.md) or [Ejecución de operaciones por lote con PartiQL para DynamoDB](ql-reference.multiplestatements.batching.md).

**Topics**
+ [Sintaxis](#ql-reference.delete.syntax)
+ [Parameters](#ql-reference.delete.parameters)
+ [Valor devuelto](#ql-reference.delete.return)
+ [Ejemplos](#ql-reference.delete.examples)

## Sintaxis
<a name="ql-reference.delete.syntax"></a>

```
DELETE FROM table 
 WHERE condition [RETURNING returnvalues]
 <returnvalues>  ::= ALL OLD *
```

## Parameters
<a name="ql-reference.delete.parameters"></a>

***table***  
(Necesario) Tabla de DynamoDB que contiene el elemento que se va a eliminar.

***condition***  
(Necesario) Criterios de selección para el elemento que se va a eliminar; esta condición debe resolverse en un único valor de clave principal.

***returnvalues***  
(Opcional) Utilizar `returnvalues` si desea obtener los atributos del elemento tal y como aparecían antes de eliminarlos. Los valores válidos son:   
+ `ALL OLD *`: se devuelve el contenido del elemento anterior.

## Valor devuelto
<a name="ql-reference.delete.return"></a>

Esta instrucción no devuelve un valor a menos que se especifique el parámetro `returnvalues`.

**nota**  
Si la tabla de DynamoDB no tiene ningún elemento con la misma clave principal que la del elemento para el que se emite DELETE, se devuelve SUCCESS con 0 elementos eliminados. Si la tabla tiene un elemento con la misma clave principal, pero la condición de la cláusula WHERE de la instrucción DELETE se evalúa como false (falso), se devuelve `ConditionalCheckFailedException`.

## Ejemplos
<a name="ql-reference.delete.examples"></a>

La siguiente consulta elimina un elemento de la tabla `"Music"`.

```
DELETE FROM "Music" WHERE "Artist" = 'Acme Band' AND "SongTitle" = 'PartiQL Rocks'
```

Puede agregar el parámetro `RETURNING ALL OLD *` para devolver los datos eliminados.

```
DELETE FROM "Music" WHERE "Artist" = 'Acme Band' AND "SongTitle" = 'PartiQL Rocks' RETURNING ALL OLD *
```

La instrucción `Delete` devuelve ahora lo siguiente:

```
{
    "Items": [
        {
            "Artist": {
                "S": "Acme Band"
            },
            "SongTitle": {
                "S": "PartiQL Rocks"
            }
        }
    ]
}
```

# Instrucciones de inserción de PartiQL para DynamoDB
<a name="ql-reference.insert"></a>

Usar la instrucción `INSERT` para agregar un elemento a una tabla de Amazon DynamoDB.

**nota**  
Sólo puede insertar un elemento a la vez; no puede emitir una sola instrucción de DynamoDB PartiQL que inserte varios elementos. Para obtener información sobre cómo insertar varios elementos, consulte [Realización de transacciones con PartiQL para DynamoDB](ql-reference.multiplestatements.transactions.md) or [Ejecución de operaciones por lote con PartiQL para DynamoDB](ql-reference.multiplestatements.batching.md).

**Topics**
+ [Sintaxis](#ql-reference.insert.syntax)
+ [Parameters](#ql-reference.insert.parameters)
+ [Valor devuelto](#ql-reference.insert.return)
+ [Ejemplos](#ql-reference.insert.examples)

## Sintaxis
<a name="ql-reference.insert.syntax"></a>

Inserte un único elemento.

```
INSERT INTO table VALUE item
```

## Parameters
<a name="ql-reference.insert.parameters"></a>

***table***  
(Necesario) La tabla en la que desea insertar los datos. La tabla debe existir previamente.

***elemento***  
(Necesario) Un elemento válido de DynamoDB representado como [tupla PartiQL](https://partiql.org/docs.html). Debe especificar *un solo* elemento y cada nombre de atributo en el elemento distingue entre mayúsculas y minúsculas y se puede denotar con comillas *simples* (`'...'`) en PartiQL.  
Los valores string también se denotan con comillas *simples* (`'...'`) en PartiQL.

## Valor devuelto
<a name="ql-reference.insert.return"></a>

Esta instrucción no devuelve ningún valor.

**nota**  
Si la tabla DynamoDB ya tiene un elemento con la misma clave principal que la clave principal del elemento que se va a insertar, se devuelve `DuplicateItemException`.

## Ejemplos
<a name="ql-reference.insert.examples"></a>

```
INSERT INTO "Music" value {'Artist' : 'Acme Band','SongTitle' : 'PartiQL Rocks'}
```