# PartiQL: un lenguaje de consulta compatible con SQL para Amazon DynamoDB Compatibilidad con Amazon DynamoDB [PartiQL](https://partiql.org/), un lenguaje de consulta compatible con SQL, para seleccionar, insertar, actualizar y eliminar datos en Amazon DynamoDB. Utilizando PartiQL, puede interactuar fácilmente con tablas de DynamoDB y ejecutar consultas ad hoc utilizando la Consola de administración de AWS, NoSQL Workbench, AWS Command Line Interface y las API de DynamoDB para PartiQL. Las operaciones PartiQL proporcionan la misma disponibilidad, latencia y rendimiento que las demás operaciones del plano de datos de DynamoDB. En las siguientes secciones se describe la implementación DynamoDB de PartiQL. **Topics** + [¿Qué es PartiQL?](#ql-reference.what-is) + [PartiQL en Amazon DynamoDB](#ql-reference.what-is) + [Introducción](ql-gettingstarted.md) + [Tipos de datos](ql-reference.data-types.md) + [Instrucciones](ql-reference.statements.md) + [Funciones](ql-functions.md) + [Operadores](ql-operators.md) + [Transacciones](ql-reference.multiplestatements.transactions.md) + [Operaciones por lotes](ql-reference.multiplestatements.batching.md) + [Políticas de IAM](ql-iam.md) ## ¿Qué es PartiQL? *PartiQL* proporciona acceso a consultas compatible con SQL en múltiples almacenes de datos que contienen datos estructurados, datos semiestructurados y datos anidados. Es ampliamente utilizado en Amazon y ahora está disponible como parte de muchos servicios de AWS, incluido DynamoDB. Para obtener la especificación PartiQL y un tutorial sobre el lenguaje de consulta principal, consulte la [Documentación de PartiQL](https://partiql.org/docs.html). **nota** Amazon DynamoDB admite *subconjunto* del lenguaje de consulta de [PartiQL](https://partiql.org/). Amazon DynamoDB no admite el formato de datos [Amazon Ion](http://amzn.github.io/ion-docs/) o literales de Amazon Ion. ## PartiQL en Amazon DynamoDB Para ejecutar consultas PartiQL en DynamoDB, puede utilizar: + La consola de DynamoDB + Uso de NoSQL Workbench + La AWS Command Line Interface (AWS CLI) + Las API de DynamoDB Para obtener información sobre el uso de estos métodos para acceder a DynamoDB, consulte [Acceso a DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/AccessingDynamoDB.html). # Introducción a PartiQL para DynamoDB En esta sección se describe cómo utilizar PartiQL para DynamoDB desde la consola de Amazon DynamoDB, la AWS Command Line Interface (AWS CLI) y las API de DynamoDB. En los ejemplos siguientes, se usa la tabla de DynamoDB que se define en el tutorial [Introducción a DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html) como requisito previo. Para obtener información sobre cómo usar la consola de DynamoDB, AWS Command Line Interface o las API de DynamoDB para acceder a DynamoDB, consulte [Acceso a DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/AccessingDynamoDB.html). Para [descargar](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.settingup.html) y usar el [NoSQL Workbench](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.html) para crear instrucciones [PartiQL para DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.html) elija **PartiQL operations (Operaciones de PartiQL)** en la esquina superior derecha del NoSQL Workbench para DynamoDB [Operation Builder (Creador de operaciones)](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.querybuilder.operationbuilder.html). ------ #### [ Console ] ![\[Interfaz de editor PartiQL que muestra el resultado de ejecutar la operación de consulta en la tabla Música.\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/images/partiqlgettingstarted.png) 1. Inicie sesión en la Consola de administración de AWS y abra la consola de DynamoDB en [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/). 1. En el panel de navegación del lado izquierdo de la consola, elija **Editor PartiQL**. 1. Elija la tabla **Música**. 1. Ellija **Tabla de consulta**. Esta acción genera una consulta que no dará como resultado un análisis de tabla completo. 1. Reemplazar `partitionKeyValue` con el valor de la cadena `Acme Band`. Reemplazar `sortKeyValue` con el valor de la cadena `Happy Day`. 1. Seleccione el botón **Run** (Ejecutar). 1. Puede ver los resultados de la consulta seleccionando los botones **Table view (Vista de tabla)** o **JSON view (Vista JSON)**. ------ #### [ NoSQL workbench ] ![\[Interfaz de NoSQL Workbench. Muestra una instrucción SELECT de PartiQL que puede ejecutar en la tabla Música.\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/images/workbench/partiql.single.png) 1. Seleccionar **Instrucción PartiQL**. 1. Ingrese la siguiente PartiQL [Instrucción SELECT](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.select.html) ``` SELECT * FROM Music WHERE Artist=? and SongTitle=? ``` 1. Para especificar un valor para los parámetros `Artist` y `SongTitle`: 1. Elija **Parámetros de solicitudes opcionales**. 1. Elija **Agregar nuevos parámetros**. 1. Elija el tipo de atributo **string** y valor `Acme Band`. 1. Repita los pasos b y c y elija el tipo **string** y valor `PartiQL Rocks`. 1. Si desea generar código, seleccione **Generate code (Generar código)**. Seleccione el idioma que desee en las pestañas mostradas. Ahora puede copiar este código y utilizarlo en su aplicación. 1. Si desea que la operación se ejecute inmediatamente, elija **Ejecutar**. ------ #### [ AWS CLI ] 1. Cree un elemento en la tabla `Music` utilizando la instrucción INSERT PartiQL. ``` aws dynamodb execute-statement --statement "INSERT INTO Music \ VALUE \ {'Artist':'Acme Band','SongTitle':'PartiQL Rocks'}" ``` 1. Recuperar un elemento de la tabla Música mediante la instrucción SELECT PartiQL. ``` aws dynamodb execute-statement --statement "SELECT * FROM Music \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` 1. Actualice un elemento en la tabla `Music` usando la instrucción UPDATE PartiQL. ``` aws dynamodb execute-statement --statement "UPDATE Music \ SET AwardsWon=1 \ SET AwardDetail={'Grammys':[2020, 2018]} \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` Agregue un valor de lista para un elemento en la tabla `Music`. ``` aws dynamodb execute-statement --statement "UPDATE Music \ SET AwardDetail.Grammys =list_append(AwardDetail.Grammys,[2016]) \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` Quitar un valor de lista para un elemento en la tabla `Music`. ``` aws dynamodb execute-statement --statement "UPDATE Music \ REMOVE AwardDetail.Grammys[2] \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` Agregue un nuevo miembro de mapa para un elemento la tabla `Music`. ``` aws dynamodb execute-statement --statement "UPDATE Music \ SET AwardDetail.BillBoard=[2020] \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` Agregue un nuevo atributo de conjunto de cadenas para un elemento en la tabla `Music`. ``` aws dynamodb execute-statement --statement "UPDATE Music \ SET BandMembers =<<'member1', 'member2'>> \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` Actualice un atributo de conjunto de cadenas para un elemento en la tabla `Music`. ``` aws dynamodb execute-statement --statement "UPDATE Music \ SET BandMembers =set_add(BandMembers, <<'newmember'>>) \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` 1. Elimine un elemento de la tabla `Music` mediante la instrucción DELETE PartiQL. ``` aws dynamodb execute-statement --statement "DELETE FROM Music \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` ------ #### [ Java ] ``` import java.util.ArrayList; import java.util.List; import com.amazonaws.AmazonClientException; import com.amazonaws.AmazonServiceException; import software.amazon.dynamodb.AmazonDynamoDB; import software.amazon.dynamodb.AmazonDynamoDBClientBuilder; import software.amazon.dynamodb.model.AttributeValue; import software.amazon.dynamodb.model.ConditionalCheckFailedException; import software.amazon.dynamodb.model.ExecuteStatementRequest; import software.amazon.dynamodb.model.ExecuteStatementResult; import software.amazon.dynamodb.model.InternalServerErrorException; import software.amazon.dynamodb.model.ItemCollectionSizeLimitExceededException; import software.amazon.dynamodb.model.ProvisionedThroughputExceededException; import software.amazon.dynamodb.model.RequestLimitExceededException; import software.amazon.dynamodb.model.ResourceNotFoundException; import software.amazon.dynamodb.model.TransactionConflictException; public class DynamoDBPartiQGettingStarted { public static void main(String[] args) { // Create the DynamoDB Client with the region you want AmazonDynamoDB dynamoDB = createDynamoDbClient("us-west-1"); try { // Create ExecuteStatementRequest ExecuteStatementRequest executeStatementRequest = new ExecuteStatementRequest(); List parameters= getPartiQLParameters(); //Create an item in the Music table using the INSERT PartiQL statement processResults(executeStatementRequest(dynamoDB, "INSERT INTO Music value {'Artist':?,'SongTitle':?}", parameters)); //Retrieve an item from the Music table using the SELECT PartiQL statement. processResults(executeStatementRequest(dynamoDB, "SELECT * FROM Music where Artist=? and SongTitle=?", parameters)); //Update an item in the Music table using the UPDATE PartiQL statement. processResults(executeStatementRequest(dynamoDB, "UPDATE Music SET AwardsWon=1 SET AwardDetail={'Grammys':[2020, 2018]} where Artist=? and SongTitle=?", parameters)); //Add a list value for an item in the Music table. processResults(executeStatementRequest(dynamoDB, "UPDATE Music SET AwardDetail.Grammys =list_append(AwardDetail.Grammys,[2016]) where Artist=? and SongTitle=?", parameters)); //Remove a list value for an item in the Music table. processResults(executeStatementRequest(dynamoDB, "UPDATE Music REMOVE AwardDetail.Grammys[2] where Artist=? and SongTitle=?", parameters)); //Add a new map member for an item in the Music table. processResults(executeStatementRequest(dynamoDB, "UPDATE Music set AwardDetail.BillBoard=[2020] where Artist=? and SongTitle=?", parameters)); //Add a new string set attribute for an item in the Music table. processResults(executeStatementRequest(dynamoDB, "UPDATE Music SET BandMembers =<<'member1', 'member2'>> where Artist=? and SongTitle=?", parameters)); //update a string set attribute for an item in the Music table. processResults(executeStatementRequest(dynamoDB, "UPDATE Music SET BandMembers =set_add(BandMembers, <<'newmember'>>) where Artist=? and SongTitle=?", parameters)); //Retrieve an item from the Music table using the SELECT PartiQL statement. processResults(executeStatementRequest(dynamoDB, "SELECT * FROM Music where Artist=? and SongTitle=?", parameters)); //delete an item from the Music Table processResults(executeStatementRequest(dynamoDB, "DELETE FROM Music where Artist=? and SongTitle=?", parameters)); } catch (Exception e) { handleExecuteStatementErrors(e); } } private static AmazonDynamoDB createDynamoDbClient(String region) { return AmazonDynamoDBClientBuilder.standard().withRegion(region).build(); } private static List getPartiQLParameters() { List parameters = new ArrayList(); parameters.add(new AttributeValue("Acme Band")); parameters.add(new AttributeValue("PartiQL Rocks")); return parameters; } private static ExecuteStatementResult executeStatementRequest(AmazonDynamoDB client, String statement, List parameters ) { ExecuteStatementRequest request = new ExecuteStatementRequest(); request.setStatement(statement); request.setParameters(parameters); return client.executeStatement(request); } private static void processResults(ExecuteStatementResult executeStatementResult) { System.out.println("ExecuteStatement successful: "+ executeStatementResult.toString()); } // Handles errors during ExecuteStatement execution. Use recommendations in error messages below to add error handling specific to // your application use-case. private static void handleExecuteStatementErrors(Exception exception) { try { throw exception; } catch (ConditionalCheckFailedException ccfe) { System.out.println("Condition check specified in the operation failed, review and update the condition " + "check before retrying. Error: " + ccfe.getErrorMessage()); } catch (TransactionConflictException tce) { System.out.println("Operation was rejected because there is an ongoing transaction for the item, generally " + "safe to retry with exponential back-off. Error: " + tce.getErrorMessage()); } catch (ItemCollectionSizeLimitExceededException icslee) { System.out.println("An item collection is too large, you\'re using Local Secondary Index and exceeded " + "size limit of items per partition key. Consider using Global Secondary Index instead. Error: " + icslee.getErrorMessage()); } catch (Exception e) { handleCommonErrors(e); } } private static void handleCommonErrors(Exception exception) { try { throw exception; } catch (InternalServerErrorException isee) { System.out.println("Internal Server Error, generally safe to retry with exponential back-off. Error: " + isee.getErrorMessage()); } catch (RequestLimitExceededException rlee) { System.out.println("Throughput exceeds the current throughput limit for your account, increase account level throughput before " + "retrying. Error: " + rlee.getErrorMessage()); } catch (ProvisionedThroughputExceededException ptee) { System.out.println("Request rate is too high. If you're using a custom retry strategy make sure to retry with exponential back-off. " + "Otherwise consider reducing frequency of requests or increasing provisioned capacity for your table or secondary index. Error: " + ptee.getErrorMessage()); } catch (ResourceNotFoundException rnfe) { System.out.println("One of the tables was not found, verify table exists before retrying. Error: " + rnfe.getErrorMessage()); } catch (AmazonServiceException ase) { System.out.println("An AmazonServiceException occurred, indicates that the request was correctly transmitted to the DynamoDB " + "service, but for some reason, the service was not able to process it, and returned an error response instead. Investigate and " + "configure retry strategy. Error type: " + ase.getErrorType() + ". Error message: " + ase.getErrorMessage()); } catch (AmazonClientException ace) { System.out.println("An AmazonClientException occurred, indicates that the client was unable to get a response from DynamoDB " + "service, or the client was unable to parse the response from the service. Investigate and configure retry strategy. "+ "Error: " + ace.getMessage()); } catch (Exception e) { System.out.println("An exception occurred, investigate and configure retry strategy. Error: " + e.getMessage()); } } } ``` ------ ## Uso de instrucciones parametrizadas En lugar de incrustar valores directamente en una cadena de instrucciones PartiQL, puede utilizar marcadores de posición con signos de interrogación (`?`) y suministrar los valores de forma independiente en el campo `Parameters`. Cada `?` se sustituye por el valor del parámetro correspondiente, en el orden en que se proporcionan. El uso de instrucciones parametrizadas es una práctica recomendada porque separa la estructura de las instrucciones de los valores de los datos, lo que facilita su lectura y reutilización. También evita la necesidad de formatear y escapar manualmente de los valores de los atributos de la cadena de la instrucción. Las instrucciones parametrizadas se admiten en las operaciones `ExecuteStatement`, `BatchExecuteStatement` y `ExecuteTransaction`. En los siguientes ejemplos, se recupera un elemento de la tabla `Music` mediante valores parametrizados para la clave de partición y la clave de clasificación. ------ #### [ AWS CLI parameterized ] ``` aws dynamodb execute-statement \ --statement "SELECT * FROM \"Music\" WHERE Artist=? AND SongTitle=?" \ --parameters '[{"S": "Acme Band"}, {"S": "PartiQL Rocks"}]' ``` ------ #### [ Java parameterized ] ``` List parameters = new ArrayList<>(); parameters.add(new AttributeValue("Acme Band")); parameters.add(new AttributeValue("PartiQL Rocks")); ExecuteStatementRequest request = new ExecuteStatementRequest() .withStatement("SELECT * FROM Music WHERE Artist=? AND SongTitle=?") .withParameters(parameters); ExecuteStatementResult result = dynamoDB.executeStatement(request); ``` ------ #### [ Python parameterized ] ``` response = dynamodb_client.execute_statement( Statement="SELECT * FROM Music WHERE Artist=? AND SongTitle=?", Parameters=[ {'S': 'Acme Band'}, {'S': 'PartiQL Rocks'} ] ) ``` ------ **nota** El ejemplo de Java de la sección de introducción anterior utiliza en todo momento sentencias parametrizadas. El método `getPartiQLParameters()` crea la lista de parámetros y cada instrucción utiliza marcadores de posición `?` en lugar de valores insertados. # Tipos de datos de PartiQL para DynamoDB En la tabla siguiente se enumeran los tipos de datos que puede usar con PartiQL para DynamoDB. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/amazondynamodb/latest/developerguide/ql-reference.data-types.html) ## Ejemplos La instrucción siguiente muestra cómo insertar los siguientes tipos de datos: `String`, `Number`, `Map`, `List`, `Number Set` y `String Set`. ``` INSERT INTO TypesTable value {'primarykey':'1', 'NumberType':1, 'MapType' : {'entryname1': 'value', 'entryname2': 4}, 'ListType': [1,'stringval'], 'NumberSetType':<<1,34,32,4.5>>, 'StringSetType':<<'stringval','stringval2'>> } ``` La siguiente instrucción muestra cómo insertar nuevos elementos en los tipos `Map`, `List`, `Number Set` y `String Set` y cambiar el valor de un tipo `Number`. ``` UPDATE TypesTable SET NumberType=NumberType + 100 SET MapType.NewMapEntry=[2020, 'stringvalue', 2.4] SET ListType = LIST_APPEND(ListType, [4, <<'string1', 'string2'>>]) SET NumberSetType= SET_ADD(NumberSetType, <<345, 48.4>>) SET StringSetType = SET_ADD(StringSetType, <<'stringsetvalue1', 'stringsetvalue2'>>) WHERE primarykey='1' ``` La siguiente instrucción muestra cómo eliminar elementos de los tipos `Map`, `List`, `Number Set` y `String Set` y cambiar el valor de un tipo `Number`. ``` UPDATE TypesTable SET NumberType=NumberType - 1 REMOVE ListType[1] REMOVE MapType.NewMapEntry SET NumberSetType = SET_DELETE( NumberSetType, <<345>>) SET StringSetType = SET_DELETE( StringSetType, <<'stringsetvalue1'>>) WHERE primarykey='1' ``` Para obtener más información, consulte [Tipos de datos de DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes). # Instrucciones PartiQL para DynamoDB 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 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 ``` SELECT expression [, ...] FROM table[.index] [ WHERE condition ] [ [ORDER BY key [DESC|ASC] , ...] ``` ## Parameters ***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 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 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 ``` UPDATE table [SET | REMOVE] path [= data] […] WHERE condition [RETURNING returnvalues] ::= [ALL OLD | MODIFIED OLD | ALL NEW | MODIFIED NEW] * ``` ## Parameters ***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 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 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 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 ``` DELETE FROM table WHERE condition [RETURNING returnvalues] ::= ALL OLD * ``` ## Parameters ***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 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 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 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 Inserte un único elemento. ``` INSERT INTO table VALUE item ``` ## Parameters ***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 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 ``` INSERT INTO "Music" value {'Artist' : 'Acme Band','SongTitle' : 'PartiQL Rocks'} ``` # Uso de funciones de PartiQL con DynamoDB PartiQL en Amazon DynamoDB admite las siguientes variantes integradas de funciones estándar de SQL. **nota** DynamoDB no admite actualmente ninguna función SQL que no se incluya en esta lista. ## Funciones de agregación + [Uso de la función SIZE con PartiQL para Amazon DynamoDB](ql-functions.size.md) ## Funciones condicionales + [Uso de la función EXISTS con PartiQL para DynamoDB](ql-functions.exists.md) + [Uso de la función ATTRIBUTE\$1TYPE con PartiQL para DynamoDB](ql-functions.attribute_type.md) + [Uso de la función BEGINS\$1WITH con PartiQL para DynamoDB](ql-functions.beginswith.md) + [Uso de la función CONTAINS con PartiQL para DynamoDB](ql-functions.contains.md) + [Uso de la función MISSING con PartiQL para DynamoDB](ql-functions.missing.md) # Uso de la función EXISTS con PartiQL para DynamoDB Puede usar EXISTS para realizar la misma función que`ConditionCheck` hace en la API [TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html#transaction-apis-txwriteitems). La función EXISTS sólo se puede utilizar en transacciones. Dado un valor, devuelve `TRUE` si el valor es una colección no vacía. De lo contrario, devuelve `FALSE`. **nota** Esta función sólo se puede utilizar en operaciones transaccionales. ## Sintaxis ``` EXISTS ( statement ) ``` ## Argumentos *statement * (Requerido) La instrucción SELECT que la función evalúa. La instrucción SELECT debe especificar una clave principal completa y otra condición. ## Tipo de retorno `bool` ## Ejemplos ``` EXISTS( SELECT * FROM "Music" WHERE "Artist" = 'Acme Band' AND "SongTitle" = 'PartiQL Rocks') ``` # Uso de la función BEGINS\$1WITH con PartiQL para DynamoDB Devuelve `TRUE` si el atributo especificado comienza por una subcadena determinada. ## Sintaxis ``` begins_with(path, value ) ``` ## Argumentos *path* (Necesario) Nombre del atributo o ruta del documento que se va a utilizar. *value* (Necesario) La cadena que se va a buscar. ## Tipo de retorno `bool` ## Ejemplos ``` SELECT * FROM "Orders" WHERE "OrderID"=1 AND begins_with("Address", '7834 24th') ``` # Uso de la función MISSING con PartiQL para DynamoDB Devuelve `TRUE` si el elemento no contiene el atributo especificado. Sólo los operadores de igualdad y desigualdad pueden ser utilizados con esta función. ## Sintaxis ``` attributename IS | IS NOT MISSING ``` ## Argumentos *attributename* (Necesario) Nombre del atributo que se va a buscar. ## Tipo de retorno `bool` ## Ejemplos ``` SELECT * FROM Music WHERE "Awards" is MISSING ``` # Uso de la función ATTRIBUTE\$1TYPE con PartiQL para DynamoDB Devuelve `TRUE` si el atributo de la ruta especificada es de un tipo de datos determinado. ## Sintaxis ``` attribute_type( attributename, type ) ``` ## Argumentos *attributename* (Necesario) Nombre del atributo que se va a utilizar. *type* (Necesario) Tipo de atributo que se va a comprobar. Para obtener una lista de valores válidos, consulte [attribute\$1type](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions) de DynamoDB. ## Tipo de retorno `bool` ## Ejemplos ``` SELECT * FROM "Music" WHERE attribute_type("Artist", 'S') ``` # Uso de la función CONTAINS con PartiQL para DynamoDB Devuelve `TRUE` si el atributo especificado por la ruta es uno de los siguientes: + Un valor de tipo String que contiene una determinada subcadena. + Un valor de tipo Set que contiene una entrada determinada perteneciente al conjunto. Para obtener más información, consulte la función [contains (contiene)](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions) de DynamoDB. ## Sintaxis ``` contains( path, substring ) ``` ## Argumentos *path* (Necesario) Nombre del atributo o ruta del documento que se va a utilizar. *subcadena* (Necesario) La subcadena de atributo o miembro de conjunto que se va a comprobar. Para obtener más información, consulte la función [contains (contiene)](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions) de DynamoDB. ## Tipo de retorno `bool` ## Ejemplos ``` SELECT * FROM "Orders" WHERE "OrderID"=1 AND contains("Address", 'Kirkland') ``` # Uso de la función SIZE con PartiQL para Amazon DynamoDB Devuelve un número que representa el tamaño de un atributo en bytes. A continuación se muestran los tipos de datos válidos para usarlos con size. Para obtener más información, consulte la función [size (dimensión)](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions) de DynamoDB. ## Sintaxis ``` size( path) ``` ## Argumentos *path* (Necesario) Nombre del atributo o ruta del documento. Para conocer los tipos admitidos, consulte la función [size (dimensión)](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions) de DynamoDB. ## Tipo de retorno `int` ## Ejemplos ``` SELECT * FROM "Orders" WHERE "OrderID"=1 AND size("Image") >300 ``` # Operadores aritméticos, comparativos y lógicos de PartiQL para DynamoDB PartiQL en Amazon DynamoDB admite los siguiente [Operadores estándares de SQL](https://www.w3schools.com/sql/sql_operators.asp). **nota** DynamoDB no admite ningún operador SQL que no se incluya en esta lista. ## Operadores aritméticos **** | Operador | Descripción | | --- | --- | | \$1 | Add (Suma) | | - | Subtract (Sustracción) | ## Operadores de comparación **** | Operador | Descripción | | --- | --- | | = | Igual que | | <> | No igual que | | \$1= | No igual que | | > | Mayor que | | < | Menor que | | >= | Mayor o igual que | | <= | Menor o igual que | ## Operadores lógicos **** | Operador | Descripción | | --- | --- | | AND | TRUE si todas las condiciones separadas por AND son TRUE | | BETWEEN | `TRUE` si el operando está en el rango de las comparaciones Este operador incluye los límites inferior y superior de los operandos a los que se aplica. | | IN | `TRUE` si el operando es igual a uno de una lista de expresiones (con un máximo de 50 valores de atributo hash o un máximo de 100 valores de atributo no clave). Los resultados se devuelven en páginas de hasta 10 elementos. Si la lista `IN` contiene más valores, debe utilizar los valores `NextToken` devueltos en la respuesta para recuperar las páginas siguientes. | | IS | TRUE si el operando es un tipo de datos PartiQL dado, incluyendo NULL o MISSING | | NOT | Invierte el valor de una expresión booleana dada | | OR | TRUE si alguna de las condiciones está separada por OR son TRUE | Consulte [Realización de comparaciones](Expressions.OperatorsAndFunctions.md#Expressions.OperatorsAndFunctions.Comparators) y [Evaluaciones lógicas](Expressions.OperatorsAndFunctions.md#Expressions.OperatorsAndFunctions.LogicalEvaluations) para obtener más información sobre operadores lógicos. # Realización de transacciones con PartiQL para DynamoDB En esta sección se describe cómo utilizar transacciones con PartiQL para DynamoDB. Las transacciones PartiQL están limitadas a un total de 100 instrucciones (acciones). Para obtener más información acerca de las transacciones de DynamoDB, consulte [Administración de flujos de trabajo complejos con transacciones de DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transactions.html). **nota** Toda la transacción debe constar de instrucciones de lectura o de escritura. No puede mezclar ambos en una sola transacción. La función EXISTS es una excepción. Se puede utilizar para verificar la condición de atributos específicos del elemento de una manera similar a `ConditionCheck` en la operación de la API [TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html#transaction-apis-txwriteitems). **Topics** + [Sintaxis](#ql-reference.multiplestatements.transactions.syntax) + [Parameters](#ql-reference.multiplestatements.transactions.parameters) + [Valores devueltos](#ql-reference.multiplestatements.transactions.return) + [Ejemplos](#ql-reference.multiplestatements.transactions.examples) ## Sintaxis ``` [ { "Statement":" statement ", "Parameters":[ { " parametertype " : " parametervalue " }, ...] } , ... ] ``` ## Parameters ***statement*** (Necesario) Una instrucción compatible con PartiQL para DynamoDB. Toda la transacción debe constar de instrucciones de lectura o de escritura. No puede mezclar ambos en una sola transacción. ***parametertype*** (Opcional) Tipo DynamoDB, si se utilizaron parámetros al especificar la instrucción PartiQL. ***parametervalue*** (Opcional) Valor de parámetro si se utilizaron parámetros al especificar la instrucción PartiQL. ## Valores devueltos Esta instrucción no devuelve ningún valor para las operaciones de escritura (INSERT, UPDATE o DELETE). Sin embargo, devuelve valores diferentes para las operaciones de lectura (SELECT) en función de las condiciones especificadas en la cláusula WHERE. **nota** Si alguna de las operaciones singleton INSERT, UPDATE o DELETE devuelve un error, las transacciones se cancelan con la excepción `TransactionCanceledException`, y el código de motivo de cancelación incluye los errores de las operaciones singleton individuales. ## Ejemplos En el ejemplo siguiente, se ejecutan varias instrucciones como transacción. ------ #### [ AWS CLI ] 1. Guarde el siguiente código JSON en un archivo llamado partiql.json. ``` [ { "Statement": "EXISTS(SELECT * FROM \"Music\" where Artist='No One You Know' and SongTitle='Call Me Today' and Awards is MISSING)" }, { "Statement": "INSERT INTO Music value {'Artist':?,'SongTitle':'?'}", "Parameters": [{\"S\": \"Acme Band\"}, {\"S\": \"Best Song\"}] }, { "Statement": "UPDATE \"Music\" SET AwardsWon=1 SET AwardDetail={'Grammys':[2020, 2018]} where Artist='Acme Band' and SongTitle='PartiQL Rocks'" } ] ``` 1. Ejecute el comando siguiente en un símbolo del sistema. ``` aws dynamodb execute-transaction --transact-statements file://partiql.json ``` ------ #### [ Java ] ``` public class DynamoDBPartiqlTransaction { public static void main(String[] args) { // Create the DynamoDB Client with the region you want AmazonDynamoDB dynamoDB = createDynamoDbClient("us-west-2"); try { // Create ExecuteTransactionRequest ExecuteTransactionRequest executeTransactionRequest = createExecuteTransactionRequest(); ExecuteTransactionResult executeTransactionResult = dynamoDB.executeTransaction(executeTransactionRequest); System.out.println("ExecuteTransaction successful."); // Handle executeTransactionResult } catch (Exception e) { handleExecuteTransactionErrors(e); } } private static AmazonDynamoDB createDynamoDbClient(String region) { return AmazonDynamoDBClientBuilder.standard().withRegion(region).build(); } private static ExecuteTransactionRequest createExecuteTransactionRequest() { ExecuteTransactionRequest request = new ExecuteTransactionRequest(); // Create statements List statements = getPartiQLTransactionStatements(); request.setTransactStatements(statements); return request; } private static List getPartiQLTransactionStatements() { List statements = new ArrayList(); statements.add(new ParameterizedStatement() .withStatement("EXISTS(SELECT * FROM "Music" where Artist='No One You Know' and SongTitle='Call Me Today' and Awards is MISSING)")); statements.add(new ParameterizedStatement() .withStatement("INSERT INTO "Music" value {'Artist':'?','SongTitle':'?'}") .withParameters(new AttributeValue("Acme Band"),new AttributeValue("Best Song"))); statements.add(new ParameterizedStatement() .withStatement("UPDATE "Music" SET AwardsWon=1 SET AwardDetail={'Grammys':[2020, 2018]} where Artist='Acme Band' and SongTitle='PartiQL Rocks'")); return statements; } // Handles errors during ExecuteTransaction execution. Use recommendations in error messages below to add error handling specific to // your application use-case. private static void handleExecuteTransactionErrors(Exception exception) { try { throw exception; } catch (TransactionCanceledException tce) { System.out.println("Transaction Cancelled, implies a client issue, fix before retrying. Error: " + tce.getErrorMessage()); } catch (TransactionInProgressException tipe) { System.out.println("The transaction with the given request token is already in progress, consider changing " + "retry strategy for this type of error. Error: " + tipe.getErrorMessage()); } catch (IdempotentParameterMismatchException ipme) { System.out.println("Request rejected because it was retried with a different payload but with a request token that was already used, " + "change request token for this payload to be accepted. Error: " + ipme.getErrorMessage()); } catch (Exception e) { handleCommonErrors(e); } } private static void handleCommonErrors(Exception exception) { try { throw exception; } catch (InternalServerErrorException isee) { System.out.println("Internal Server Error, generally safe to retry with exponential back-off. Error: " + isee.getErrorMessage()); } catch (RequestLimitExceededException rlee) { System.out.println("Throughput exceeds the current throughput limit for your account, increase account level throughput before " + "retrying. Error: " + rlee.getErrorMessage()); } catch (ProvisionedThroughputExceededException ptee) { System.out.println("Request rate is too high. If you're using a custom retry strategy make sure to retry with exponential back-off. " + "Otherwise consider reducing frequency of requests or increasing provisioned capacity for your table or secondary index. Error: " + ptee.getErrorMessage()); } catch (ResourceNotFoundException rnfe) { System.out.println("One of the tables was not found, verify table exists before retrying. Error: " + rnfe.getErrorMessage()); } catch (AmazonServiceException ase) { System.out.println("An AmazonServiceException occurred, indicates that the request was correctly transmitted to the DynamoDB " + "service, but for some reason, the service was not able to process it, and returned an error response instead. Investigate and " + "configure retry strategy. Error type: " + ase.getErrorType() + ". Error message: " + ase.getErrorMessage()); } catch (AmazonClientException ace) { System.out.println("An AmazonClientException occurred, indicates that the client was unable to get a response from DynamoDB " + "service, or the client was unable to parse the response from the service. Investigate and configure retry strategy. "+ "Error: " + ace.getMessage()); } catch (Exception e) { System.out.println("An exception occurred, investigate and configure retry strategy. Error: " + e.getMessage()); } } } ``` ------ En el ejemplo siguiente se muestran los distintos valores de retorno cuando DynamoDB lee elementos con condiciones diferentes especificadas en la cláusula WHERE. ------ #### [ AWS CLI ] 1. Guarde el siguiente código JSON en un archivo llamado partiql.json. ``` [ // Item exists and projected attribute exists { "Statement": "SELECT * FROM "Music" WHERE Artist='No One You Know' and SongTitle='Call Me Today'" }, // Item exists but projected attributes do not exist { "Statement": "SELECT non_existent_projected_attribute FROM "Music" WHERE Artist='No One You Know' and SongTitle='Call Me Today'" }, // Item does not exist { "Statement": "SELECT * FROM "Music" WHERE Artist='No One I Know' and SongTitle='Call You Today'" } ] ``` 1. Ejecute el comando siguiente en un símbolo del sistema. ``` aws dynamodb execute-transaction --transact-statements file://partiql.json ``` 1. Se devuelve la siguiente respuesta: ``` { "Responses": [ // Item exists and projected attribute exists { "Item": { "Artist":{ "S": "No One You Know" }, "SongTitle":{ "S": "Call Me Today" } } }, // Item exists but projected attributes do not exist { "Item": {} }, // Item does not exist {} ] } ``` ------ # Ejecución de operaciones por lote con PartiQL para DynamoDB En esta sección se describe cómo utilizar instrucciones por lote con PartiQL para DynamoDB. **nota** Todo el lote debe constar de instrucciones de lectura o de escritura; no se pueden mezclar ambas en un solo lote. `BatchExecuteStatement` y `BatchWriteItem` no pueden realizar más de 25 instrucciones por lote. `BatchExecuteStatement` hace uso de `BatchGetItem` que toma una lista de claves principales en instrucciones independientes. **Topics** + [Sintaxis](#ql-reference.multiplestatements.batching.syntax) + [Parameters](#ql-reference.multiplestatements.batching.parameters) + [Ejemplos](#ql-reference.multiplestatements.batching.examples) ## Sintaxis ``` [ { "Statement": "SELECT pk FROM ProblemSet WHERE pk = 'p#9StkWHYTxm7x2AqSXcrfu7' AND sk = 'info'" }, { "Statement": "SELECT pk FROM ProblemSet WHERE pk = 'p#isC2ChceGbxHgESc4szoTE' AND sk = 'info'" } ] ``` ``` [ { "Statement":" statement ", "Parameters":[ { " parametertype " : " parametervalue " }, ...] } , ... ] ``` ## Parameters ***statement*** (Necesario) Una instrucción compatible con PartiQL para DynamoDB. + Todo el lote debe constar de instrucciones de lectura o de escritura; no se pueden mezclar ambas en un solo lote. + `BatchExecuteStatement` y `BatchWriteItem` no pueden realizar más de 25 instrucciones por lote. ***parametertype*** (Opcional) Tipo DynamoDB, si se utilizaron parámetros al especificar la instrucción PartiQL. ***parametervalue*** (Opcional) Valor de parámetro si se utilizaron parámetros al especificar la instrucción PartiQL. ## Ejemplos ------ #### [ AWS CLI ] 1. Guarde el siguiente json en un archivo llamado partiql.json ``` [ { "Statement": "INSERT INTO Music VALUE {'Artist':?,'SongTitle':?}", "Parameters": [{"S": "Acme Band"}, {"S": "Best Song"}] }, { "Statement": "UPDATE Music SET AwardsWon=1, AwardDetail={'Grammys':[2020, 2018]} WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" } ] ``` 1. Ejecute el comando siguiente en un símbolo del sistema. ``` aws dynamodb batch-execute-statement --statements file://partiql.json ``` ------ #### [ Java ] ``` public class DynamoDBPartiqlBatch { public static void main(String[] args) { // Create the DynamoDB Client with the region you want AmazonDynamoDB dynamoDB = createDynamoDbClient("us-west-2"); try { // Create BatchExecuteStatementRequest BatchExecuteStatementRequest batchExecuteStatementRequest = createBatchExecuteStatementRequest(); BatchExecuteStatementResult batchExecuteStatementResult = dynamoDB.batchExecuteStatement(batchExecuteStatementRequest); System.out.println("BatchExecuteStatement successful."); // Handle batchExecuteStatementResult } catch (Exception e) { handleBatchExecuteStatementErrors(e); } } private static AmazonDynamoDB createDynamoDbClient(String region) { return AmazonDynamoDBClientBuilder.standard().withRegion(region).build(); } private static BatchExecuteStatementRequest createBatchExecuteStatementRequest() { BatchExecuteStatementRequest request = new BatchExecuteStatementRequest(); // Create statements List statements = getPartiQLBatchStatements(); request.setStatements(statements); return request; } private static List getPartiQLBatchStatements() { List statements = new ArrayList(); statements.add(new BatchStatementRequest() .withStatement("INSERT INTO Music value {'Artist':'Acme Band','SongTitle':'PartiQL Rocks'}")); statements.add(new BatchStatementRequest() .withStatement("UPDATE Music set AwardDetail.BillBoard=[2020] where Artist='Acme Band' and SongTitle='PartiQL Rocks'")); return statements; } // Handles errors during BatchExecuteStatement execution. Use recommendations in error messages below to add error handling specific to // your application use-case. private static void handleBatchExecuteStatementErrors(Exception exception) { try { throw exception; } catch (Exception e) { // There are no API specific errors to handle for BatchExecuteStatement, common DynamoDB API errors are handled below handleCommonErrors(e); } } private static void handleCommonErrors(Exception exception) { try { throw exception; } catch (InternalServerErrorException isee) { System.out.println("Internal Server Error, generally safe to retry with exponential back-off. Error: " + isee.getErrorMessage()); } catch (RequestLimitExceededException rlee) { System.out.println("Throughput exceeds the current throughput limit for your account, increase account level throughput before " + "retrying. Error: " + rlee.getErrorMessage()); } catch (ProvisionedThroughputExceededException ptee) { System.out.println("Request rate is too high. If you're using a custom retry strategy make sure to retry with exponential back-off. " + "Otherwise consider reducing frequency of requests or increasing provisioned capacity for your table or secondary index. Error: " + ptee.getErrorMessage()); } catch (ResourceNotFoundException rnfe) { System.out.println("One of the tables was not found, verify table exists before retrying. Error: " + rnfe.getErrorMessage()); } catch (AmazonServiceException ase) { System.out.println("An AmazonServiceException occurred, indicates that the request was correctly transmitted to the DynamoDB " + "service, but for some reason, the service was not able to process it, and returned an error response instead. Investigate and " + "configure retry strategy. Error type: " + ase.getErrorType() + ". Error message: " + ase.getErrorMessage()); } catch (AmazonClientException ace) { System.out.println("An AmazonClientException occurred, indicates that the client was unable to get a response from DynamoDB " + "service, or the client was unable to parse the response from the service. Investigate and configure retry strategy. "+ "Error: " + ace.getMessage()); } catch (Exception e) { System.out.println("An exception occurred, investigate and configure retry strategy. Error: " + e.getMessage()); } } } ``` ------ # Políticas de seguridad de IAM con PartiQL para DynamoDB Los siguientes permisos son necesarios: + Para leer elementos que utilizan PartiQL para DynamoDB, debe tener el permiso `dynamodb:PartiQLSelect` en la tabla o índice. + Para insertar elementos utilizando PartiQL para DynamoDB, debe tener el permiso `dynamodb:PartiQLInsert` en la tabla o índice. + Para actualizar elementos con PartiQL para DynamoDB, debe tener el permiso `dynamodb:PartiQLUpdate` en la tabla o índice. + Para eliminar elementos que utilizan PartiQL para DynamoDB, debe tener el permiso `dynamodb:PartiQLDelete` en la tabla o índice. ## Ejemplo: Permitir todas las instrucciones PartiQL para DynamoDB (Select/Insert/Update/Delete) en una tabla La siguiente política de IAM concede permisos para ejecutar todas las instrucciones PartiQL para DynamoDB en una tabla. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "dynamodb:PartiQLInsert", "dynamodb:PartiQLUpdate", "dynamodb:PartiQLDelete", "dynamodb:PartiQLSelect" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/Music" ] } ] } ``` ------ ## Ejemplo: Permitir que PartiQL para DynamoDB seleccione las instrucciones en una tabla La siguiente política de IAM concede permisos para ejecutar la instrucción `select`sobre una tabla específica. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "dynamodb:PartiQLSelect" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/Music" ] } ] } ``` ------ ## Ejemplo: Permitir instrucciones de inserción de PartiQL para DynamoDB en un índice La siguiente política de IAM concede permisos para ejecutar la instrucción `insert` en un índice específico. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "dynamodb:PartiQLInsert" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/Music/index/index1" ] } ] } ``` ------ ## Ejemplo: Permitir las instrucciones transaccionales de PartiQL para DynamoDB sólo en una tabla La siguiente política de IAM concede permisos para ejecutar solamente instrucciones transaccionales en una tabla determinada. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "dynamodb:PartiQLInsert", "dynamodb:PartiQLUpdate", "dynamodb:PartiQLDelete", "dynamodb:PartiQLSelect" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/Music" ], "Condition":{ "StringEquals":{ "dynamodb:EnclosingOperation":[ "ExecuteTransaction" ] } } } ] } ``` ------ ## Ejemplo: Permitir lecturas y escrituras no transaccionales de PartiQL para DynamoDB y bloquear lecturas y escrituras transaccionales de PartiQL en una tabla. La siguiente directiva de IAM otorga permisos para ejecutar lecturas y escrituras no transaccionales de PartiQL para DynamoDB a la vez que bloquea lecturas y escrituras transaccionales de PartiQL para DynamoDB. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Deny", "Action":[ "dynamodb:PartiQLInsert", "dynamodb:PartiQLUpdate", "dynamodb:PartiQLDelete", "dynamodb:PartiQLSelect" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/Music" ], "Condition":{ "StringEquals":{ "dynamodb:EnclosingOperation":[ "ExecuteTransaction" ] } } }, { "Effect":"Allow", "Action":[ "dynamodb:PartiQLInsert", "dynamodb:PartiQLUpdate", "dynamodb:PartiQLDelete", "dynamodb:PartiQLSelect" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/Music" ] } ] } ``` ------ ## Ejemplo: permitir instrucciones Select y denegar instrucciones de análisis de tabla completa en PartiQL para DynamoDB La siguiente política de IAM concede permisos para ejecutar la instrucción `select` en una tabla específica mientras se bloquean las instrucciones `select` que dan como resultado un examen completo de toda la tabla. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Deny", "Action":[ "dynamodb:PartiQLSelect" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/WatchList" ], "Condition":{ "Bool":{ "dynamodb:FullTableScan":[ "true" ] } } }, { "Effect":"Allow", "Action":[ "dynamodb:PartiQLSelect" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/WatchList" ] } ] } ``` ------