本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用預備陳述式
<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
```

下表描述了這些參數。


****  

| 參數 | Description | 
| --- | --- | 
| 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\$1statement* 執行現有的預備陳述式，則 Athena 會開啟 **Enter parameters** (輸入參數) 對話方塊，以便您輸入通常會進入 `EXECUTE ... USING` 陳述式 `USING` 子句的值。

**若要使用 **Enter parameters** (輸入參數) 對話方塊執行預備陳述式**

1. 在查詢編輯器中，使用語法 `EXECUTE` *prepared\$1statement*，而不是使用語法 `EXECUTE prepared_statement USING` *value1*`,` *value2* ` ...`。

1. 選擇**執行**。出現 **Enter parameters** (輸入參數) 對話方塊。  
![\[在 Athena 主控台中輸入預備陳述式的參數值。\]](http://docs.aws.amazon.com/zh_tw/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` 命令。將 `PREPARE` 陳述式放置在 `query-string` 引數中，如以下範例所示：

```
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 語法。

## 使用執行參數引數
<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
```