# 使用预准备语句
<a name="querying-with-prepared-statements-querying"></a>

您可以使用预编译语句重复执行具有不同查询参数的同一查询。预准备语句包含参数占位符，其值在执行时提供。

**注意**  
工作组中的最大预处理语句数为 1000。

**Topics**
+ [SQL 语法](querying-with-prepared-statements-sql-statements.md)
+ [使用 Athena 控制台](querying-with-prepared-statements-executing-prepared-statements-without-the-using-clause-athena-console.md)
+ [使用 AWS CLI](querying-with-prepared-statements-cli-section.md)

# 预准备语句的 SQL 语法
<a name="querying-with-prepared-statements-sql-statements"></a>

您可以使用 `PREPARE`、`EXECUTE` 和 `DEALLOCATE PREPARE` SQL 语句在 Athena 控制台查询编辑器中运行参数化查询。

 
+ 要指定通常会使用文字值的参数，请在 `PREPARE` 语句中使用问号。
+ 若要在运行查询时将参数替换为值，请在 `EXECUTE` 语句中使用 `USING` 子句。
+ 要从工作组中的预准备语句中删除预准备语句，请使用 `DEALLOCATE PREPARE` 语句。

以下各部分提供了有关这些语句的其他详细信息。

**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>

准备要在之后运行的语句。预准备语句将以您指定的名称保存在当前工作组中。语句可以包含参数来代替要在查询运行时替换的文字。要替换为值的参数用问号表示。

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

```
PREPARE statement_name FROM statement
```

下表介绍了这些参数。


****  

| 参数 | 说明 | 
| --- | --- | 
| statement\$1name | 要执行的预准备语句的名称。此名称在工作组范围内必须唯一。 | 
| 语句 | SELECT、CTAS 或 INSERT INTO 查询。 | 

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

以下示例将演示如何使用 `PREPARE` 语句。问号表示在运行查询时由 `EXECUTE` 语句提供的值。

```
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>

运行预准备语句。参数的值在 `USING` 子句中指定。

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

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

*statement\$1name* 是预准备语句的名称。*value1* 和 *value2* 是要为语句中的参数指定的值。

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

以下示例将运行 `my_select1` 预准备语句，该语句不包含任何参数。

```
EXECUTE my_select1
```

以下示例将运行 `my_select2` 预准备语句，其中包含一个参数。

```
EXECUTE my_select2 USING 2012
```

以下示例将运行 `my_select3` 预准备语句，它使用两个参数。

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

以下示例为预准备语句 `my_insert` 中的参数提供字符串值。

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

以下示例为预准备语句 `my_unload` 中的 `productid` 参数提供数字值。

```
EXECUTE my_unload USING 12
```

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

从当前工作组中的预准备语句列表中删除具有指定名称的预准备语句。

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

```
DEALLOCATE PREPARE statement_name
```

*statement\$1name* 是要删除的预准备语句的名称。

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

以下示例从当前工作组中删除 `my_select1` 预准备语句。

```
DEALLOCATE PREPARE my_select1
```

# 在 Athena 控制台中运行交互式预准备语句
<a name="querying-with-prepared-statements-executing-prepared-statements-without-the-using-clause-athena-console"></a>

如果在查询编辑器中使用语法 `EXECUTE` *prepared\$1stament* 运行现有预准备语句，Athena 会打开 **Enter parameters（输入参数）**对话框，这样您就可以输入通常出现在 `EXECUTE ... USING` 语句的 `USING` 子句中的值。

**使用 **Enter parameters（输入参数）**对话框运行预准备语句**

1. 在查询编辑器中，使用语法 `EXECUTE` *prepared\$1stament* 而不是 `EXECUTE prepared_statement USING` *Value1* `,` *Value2* ` ...`。

1. 选择**运行**。将显示 **Enter parameters（输入参数）**对话框。  
![\[在 Athena 控制台中输入预准备语句的参数值。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/querying-with-prepared-statements-2.png)

1. 按照 **Execution parameters（执行参数）**对话框中的顺序输入值。由于查询的原始文本不可见，因此必须记住每个位置参数的含义或使预准备语句可供参考。

1. 选择**运行**。

# 使用 AWS CLI 创建、执行和列出预准备语句
<a name="querying-with-prepared-statements-cli-section"></a>

您可以使用 AWS CLI 创建、执行和列出预准备语句。

**Topics**
+ [创建](querying-with-prepared-statements-creating-prepared-statements-using-the-aws-cli.md)
+ [Execute](querying-with-prepared-statements-cli-executing-prepared-statements.md)
+ [列表](querying-with-prepared-statements-listing.md)

# 使用 AWS CLI 创建预准备语句
<a name="querying-with-prepared-statements-creating-prepared-statements-using-the-aws-cli"></a>

要使用 AWS CLI 创建预准备语句，您可以使用以下 `athena` 命令中的一个：
+ 使用 `create-prepared-statement` 命令并提供包含执行参数的查询语句。
+ 使用 `start-query-execution` 命令并提供使用 `PREPARE` 语法的查询字符串。

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

在 `create-prepared-statement` 命令中，定义 `query-statement` 参数中的查询文本，如以下示例所示。

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

## 使用 start-query-execution 和 PREPARE 语法
<a name="querying-with-prepared-statements-cli-using-start-query-execution-and-the-prepare-syntax"></a>

使用 `start-query-execution` 命令。在 `query-string` 参数中放置 `PREPARE` 语句，如以下示例所示：

```
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/..."}'
```

# 使用 AWS CLI 执行预准备语句
<a name="querying-with-prepared-statements-cli-executing-prepared-statements"></a>

要使用 AWS CLI 执行预准备语句，您可以使用以下方法之一为参数提供值：
+ 使用 `execution-parameters` 参数。
+ 使用 `query-string` 参数中的 `EXECUTE ... USING` SQL 语法。

## 使用 execution-parameters 参数
<a name="querying-with-prepared-statements-cli-using-the-execution-parameters-argument"></a>

在此方法中，您可以使用 `start-query-execution` 命令并提供 `query-string` 参数现有预准备语句的名称。然后，在 `execution-parameters` 参数中，提供执行参数的值。以下示例说明了这一方法：

```
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"
```

## 使用 EXECUTE ... 使用 SQL 语法
<a name="querying-with-prepared-statements-cli-using-the-execute-using-sql-syntax"></a>

要使用 `EXECUTE ... USING` 语法运行现有的预准备语句，您可以使用 `start-query-execution` 命令并将预准备语句的名称和参数值都放在 `query-string` 参数中，如以下示例所示：

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

# 使用 AWS CLI 列出预准备语句
<a name="querying-with-prepared-statements-listing"></a>

要列出特定工作组的预准备语句，可以使用 Athena [list-prepared-statements](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/athena/list-prepared-statements.html) AWS CLI 命令或 [ListPreparedStatements](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListPreparedStatements.html) Athena API 操作。`--work-group` 参数是必需的。

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