# Uso de instrucciones preparadas
<a name="querying-with-prepared-statements-querying"></a>

Puede utilizar una instrucción preparada para la ejecución repetida de la misma consulta con parámetros de consulta diferentes. Una instrucción preparada contiene marcadores de posición de parámetros cuyos valores se proporcionan en el momento de la ejecución.

**nota**  
El número máximo de instrucciones preparadas en un grupo de trabajo es 1000.

**Topics**
+ [Sintaxis SQL](querying-with-prepared-statements-sql-statements.md)
+ [Uso de la consola de Athena](querying-with-prepared-statements-executing-prepared-statements-without-the-using-clause-athena-console.md)
+ [Utilizar AWS CLI](querying-with-prepared-statements-cli-section.md)

# Sintaxis SQL para instrucciones preparadas
<a name="querying-with-prepared-statements-sql-statements"></a>

Puede utilizar las instrucciones SQL `PREPARE`, `EXECUTE` y `DEALLOCATE PREPARE` para ejecutar consultas parametrizadas en el editor de consultas de la consola de Athena. 

 
+ Para especificar parámetros en los que normalmente usaría valores literales, utilice signos de interrogación en la instrucción `PREPARE`.
+ Para reemplazar los parámetros con valores al ejecutar la consulta, utilice la cláusula `USING` en la instrucción `EXECUTE`.
+ Para eliminar una instrucción preparada de las instrucciones preparadas en un grupo de trabajo, utilice la instrucción `DEALLOCATE PREPARE`.

En las siguientes secciones, se proporciona información adicional acerca de cada una de estas instrucciones.

**Topics**
+ [PREPARE](querying-with-prepared-statements-prepare.md)
+ [EXECUTE](querying-with-prepared-statements-execute.md)
+ [DEALLOCATE PREPARE](querying-with-prepared-statements-deallocate-prepare.md)

# PREPARE
<a name="querying-with-prepared-statements-prepare"></a>

Prepara una instrucción que se ejecutará en un momento posterior. Las instrucciones preparadas se guardan en el grupo de trabajo actual con el nombre que especifique. La instrucción puede incluir parámetros en lugar de literales que se reemplazan cuando se ejecuta la consulta. Los parámetros que se van a reemplazar por valores se indican con signos de interrogación.

## Sintaxis
<a name="querying-with-prepared-statements-prepare-syntax"></a>

```
PREPARE statement_name FROM statement
```

En la siguiente tabla se describen estos parámetros.


****  

| Parámetro | Descripción | 
| --- | --- | 
| statement\$1name | Nombre de la instrucción a preparar. El nombre debe ser único dentro del grupo de trabajo. | 
| statement | Una consulta SELECT, CTAS o INSERT INTO. | 

## Ejemplos de PREPARE
<a name="querying-with-prepared-statements-prepare-examples"></a>

En los siguientes ejemplos se muestra el uso de la instrucción `PREPARE`. Los signos de interrogación indican los valores que debe proporcionar la instrucción `EXECUTE` cuando se ejecuta la consulta.

```
PREPARE my_select1 FROM
SELECT * FROM nation
```

```
PREPARE my_select2 FROM
SELECT * FROM "my_database"."my_table" WHERE year = ?
```

```
PREPARE my_select3 FROM
SELECT order FROM orders WHERE productid = ? and quantity < ?
```

```
PREPARE my_insert FROM
INSERT INTO cities_usa (city, state)
SELECT city, state
FROM cities_world
WHERE country = ?
```

```
PREPARE my_unload FROM
UNLOAD (SELECT * FROM table1 WHERE productid < ?)
TO 's3://amzn-s3-demo-bucket/'
WITH (format='PARQUET')
```

# EXECUTE
<a name="querying-with-prepared-statements-execute"></a>

Ejecuta una instrucción preparada. Los valores de los parámetros se especifican en la cláusula `USING`.

## Sintaxis
<a name="querying-with-prepared-statements-execute-syntax"></a>

```
EXECUTE statement_name [USING value1 [ ,value2, ... ] ]
```

*statement\$1name* es el nombre de la instrucción preparada. *value1* y *value2* son los valores que se especificarán para los parámetros de la instrucción.

## Ejemplos de EXCECUTE
<a name="querying-with-prepared-statements-execute-examples"></a>

En el siguiente ejemplo se ejecuta la instrucción preparada `my_select1`, que no contiene parámetros.

```
EXECUTE my_select1
```

En el siguiente ejemplo se ejecuta la instrucción preparada `my_select2`, que contiene un único parámetro.

```
EXECUTE my_select2 USING 2012
```

En el siguiente ejemplo se ejecuta la instrucción preparada `my_select3`, que contiene dos parámetros.

```
EXECUTE my_select3 USING 346078, 12
```

En el siguiente ejemplo se proporciona un valor de cadena para un parámetro de la instrucción preparada `my_insert`.

```
EXECUTE my_insert USING 'usa'
```

En el siguiente ejemplo se proporciona un valor numérico para el parámetro `productid` de la instrucción preparada `my_unload`.

```
EXECUTE my_unload USING 12
```

# DEALLOCATE PREPARE
<a name="querying-with-prepared-statements-deallocate-prepare"></a>

Elimina la instrucción preparada con el nombre especificado de la lista de instrucciones preparadas del grupo de trabajo actual.

## Sintaxis
<a name="querying-with-prepared-statements-deallocate-prepare-syntax"></a>

```
DEALLOCATE PREPARE statement_name
```

*statement\$1name* es el nombre de la instrucción preparada que se debe eliminar.

## Ejemplo
<a name="querying-with-prepared-statements-deallocate-prepare-examples"></a>

En el siguiente ejemplo, se elimina la instrucción preparada `my_select1` del grupo de trabajo actual.

```
DEALLOCATE PREPARE my_select1
```

# Ejecución de instrucciones preparadas interactivas en la consola de Athena
<a name="querying-with-prepared-statements-executing-prepared-statements-without-the-using-clause-athena-console"></a>

Si ejecuta una sentencia preparada existente con la sintaxis `EXECUTE` *prepared\$1statement*en el editor de consultas, Athena abre el cuadro de diálogo **Enter parameters** (Ingresar parámetros) para que pueda introducir los valores que normalmente aparecerían en la cláusula `USING` de la instrucción `EXECUTE ... USING`.

**Para ejecutar una sentencia preparada mediante el cuadro de diálogo **Enter parameters** (Ingresar parámetros)**

1. En el editor de consultas, en lugar de utilizar la sintaxis `EXECUTE prepared_statement USING` *Value1*`,` *Value2* ` ...`, utilice la sintaxis `EXECUTE` *prepared\$1statement*.

1. Seleccione **Ejecutar**. Aparece el cuadro de diálogo **Enter parameters** (Ingresar parámetros).  
![\[Ingresar valores de parámetros para una instrucción preparada en la consola de Athena.\]](http://docs.aws.amazon.com/es_es/athena/latest/ug/images/querying-with-prepared-statements-2.png)

1. Ingrese los valores en orden en el cuadro de diálogo **Execution parameters** (Ingresar parámetros). Como el texto original de la consulta no está visible, debe recordar el significado de cada parámetro posicional o tener la declaración preparada disponible como referencia.

1. Seleccione **Ejecutar**.

# Uso de la AWS CLI para crear, ejecutar y enumerar las instrucciones preparadas
<a name="querying-with-prepared-statements-cli-section"></a>

Puede utilizar la AWS CLI para crear, ejecutar y enumerar las instrucciones preparadas.

**Topics**
+ [Creación](querying-with-prepared-statements-creating-prepared-statements-using-the-aws-cli.md)
+ [Execute](querying-with-prepared-statements-cli-executing-prepared-statements.md)
+ [Enumeración](querying-with-prepared-statements-listing.md)

# Creación de instrucciones preparadas mediante la AWS CLI
<a name="querying-with-prepared-statements-creating-prepared-statements-using-the-aws-cli"></a>

Para utilizar la AWS CLI para crear una instrucción preparada, puede utilizar uno de los siguientes comandos de `athena`:
+ Utilice el comando `create-prepared-statement` y proporcione una sentencia de consulta que tenga parámetros de ejecución.
+ Utilice `start-query-execution` y proporcione una cadena de consulta que utilice la sintaxis `PREPARE`.

## Uso de create-prepared-statement
<a name="querying-with-prepared-statements-cli-using-create-prepared-statement"></a>

En un comando `create-prepared-statement`, defina el texto de la consulta en el argumento `query-statement`, como en el siguiente ejemplo.

```
aws athena create-prepared-statement 
--statement-name PreparedStatement1 
--query-statement "SELECT * FROM table WHERE x = ?" 
--work-group athena-engine-v2
```

## Uso de start-query-execution y la sintaxis PREPARE
<a name="querying-with-prepared-statements-cli-using-start-query-execution-and-the-prepare-syntax"></a>

Utilice el comando `start-query-execution`. Coloque la instrucción `PREPARE` en el argumento `query-string`, como en el siguiente ejemplo:

```
aws athena start-query-execution 
--query-string "PREPARE PreparedStatement1 FROM SELECT * FROM table WHERE x = ?" 
--query-execution-context '{"Database": "default"}' 
--result-configuration '{"OutputLocation": "s3://amzn-s3-demo-bucket/..."}'
```

# Ejecución de instrucciones preparadas mediante la AWS CLI
<a name="querying-with-prepared-statements-cli-executing-prepared-statements"></a>

Para ejecutar una declaración preparada con la AWS CLI, puede proporcionar valores para los parámetros mediante uno de los siguientes métodos:
+ Utilice el argumento `execution-parameters`.
+ Utilice la sintaxis SQL `EXECUTE ... USING` en el argumento `query-string`.

## Uso del argumento execution-parameters
<a name="querying-with-prepared-statements-cli-using-the-execution-parameters-argument"></a>

En este enfoque, se utiliza `start-query-execution` y debe proporcionarse el nombre de una sentencia preparada existente en el argumento `query-string`. A continuación, en el argumento `execution-parameters`, proporcione los valores de los parámetros de ejecución. El siguiente ejemplo muestra este método.

```
aws athena start-query-execution 
--query-string "Execute PreparedStatement1" 
--query-execution-context "Database"="default" 
--result-configuration "OutputLocation"="s3://amzn-s3-demo-bucket/..."
--execution-parameters "1" "2"
```

## Uso de EXECUTE… Uso de sintaxis SQL
<a name="querying-with-prepared-statements-cli-using-the-execute-using-sql-syntax"></a>

Para ejecutar una sentencia preparada existente con la sintaxis `EXECUTE ... USING`, se utiliza el comando `start-query-execution` y debe colocarse el nombre de la sentencia preparada y los valores de los parámetros en el argumento `query-string`, como en el siguiente ejemplo:

```
aws athena start-query-execution 
--query-string "EXECUTE PreparedStatement1 USING 1"
--query-execution-context '{"Database": "default"}' 
--result-configuration '{"OutputLocation": "s3://amzn-s3-demo-bucket/..."}'
```

# Enumeración de las instrucciones preparadas mediante la AWS CLI
<a name="querying-with-prepared-statements-listing"></a>

A fin de enumerar las instrucciones preparadas para un grupo de trabajo específico, puede utilizar el comando de la AWS CLI [list-prepared-statements](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/athena/list-prepared-statements.html) o la acción de la API de Athena [ListPreparedStatements](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListPreparedStatements.html). El parámetro `--work-group` es obligatorio.

```
aws athena list-prepared-statements --work-group primary
```