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

# 使用 aws\$1s3.query\$1export\$1to\$1s3 函數匯出查詢資料
<a name="postgresql-s3-export-examples"></a>

呼叫 [aws\$1s3.query\$1export\$1to\$1s3](postgresql-s3-export-functions.md#aws_s3.export_query_to_s3) 函數來將 PostgreSQL 資料匯出至 Amazon S3。

**Topics**
+ [先決條件](#postgresql-s3-export-examples-prerequisites)
+ [正在呼叫 aws\$1s3.query\$1export\$1to\$1s3](#postgresql-s3-export-examples-basic)
+ [匯出至使用自訂分隔符號的 CSV 檔案](#postgresql-s3-export-examples-custom-delimiter)
+ [利用編碼匯出至二進位檔案](#postgresql-s3-export-examples-encoded)

## 先決條件
<a name="postgresql-s3-export-examples-prerequisites"></a>

使用 `aws_s3.query_export_to_s3` 函數前，請先完成下列必要條件：
+ 安裝需要的 PostgreSQL 延伸，如[將資料匯出至 Amazon S3 的概觀](postgresql-s3-export.md#postgresql-s3-export-overview) 中所述。
+ 決定要將資料匯出至 Amazon S3 的位置，如[指定要匯出的 Amazon S3 檔案路徑](postgresql-s3-export.md#postgresql-s3-export-file)中所述。
+ 確認資料庫執行個體如 [設定對 Amazon S3 儲存貯體的存取權](postgresql-s3-export-access-bucket.md) 中所述，有對 Amazon S3 的匯出存取權。

下列範例會使用稱為 `sample_table` 的資料庫資料表。這些範例會將資料匯出至名為 *amzn-s3-demo-bucket* 的儲存貯體。範例資料表和資料會以下列 psql 形式的 SQL 陳述式建立。

```
psql=> CREATE TABLE sample_table (bid bigint PRIMARY KEY, name varchar(80));
psql=> INSERT INTO sample_table (bid,name) VALUES (1, 'Monday'), (2,'Tuesday'), (3, 'Wednesday');
```

## 正在呼叫 aws\$1s3.query\$1export\$1to\$1s3
<a name="postgresql-s3-export-examples-basic"></a>

以下示範呼叫 [aws\$1s3.query\$1export\$1to\$1s3](postgresql-s3-export-functions.md#aws_s3.export_query_to_s3) 函數的基本方式。

這些範例會使用變數 `s3_uri_1` 來識別包含識別 Amazon S3 檔案資訊的結構。使用 [aws\$1commons.create\$1s3\$1uri](postgresql-s3-export-functions.md#aws_commons.create_s3_uri) 函數來建立結構。

```
psql=> SELECT aws_commons.create_s3_uri(
   'amzn-s3-demo-bucket',
   'sample-filepath',
   'us-west-2'
) AS s3_uri_1 \gset
```

雖然下列兩個 `aws_s3.query_export_to_s3` 函數呼叫的參數有所不同，但這些範例的結果是相同的。`sample_table` 資料表的所有列都會匯出至名為 *amzn-s3-demo-bucket* 的儲存貯體。

```
psql=> SELECT * FROM aws_s3.query_export_to_s3('SELECT * FROM sample_table', :'s3_uri_1');

psql=> SELECT * FROM aws_s3.query_export_to_s3('SELECT * FROM sample_table', :'s3_uri_1', options :='format text');
```

參數說明如下：
+ `'SELECT * FROM sample_table'` – 第一個字串是包含 SQL 查詢的文字字串。PostgreSQL 引擎會執行此查詢。查詢結果會複製到其他參數中識別的 S3 儲存貯體。
+ `:'s3_uri_1'` – 此參數是識別 Amazon S3 檔案的結構。此範例使用變數來識別先前建立的結構。您可以改為透過在 `aws_commons.create_s3_uri` 函數呼叫中包含內嵌 `aws_s3.query_export_to_s3` 函數呼叫來建立結構，如下所示。

  ```
  SELECT * from aws_s3.query_export_to_s3('select * from sample_table', 
     aws_commons.create_s3_uri('amzn-s3-demo-bucket', 'sample-filepath', 'us-west-2') 
  );
  ```
+ `options :='format text'` – `options` 是包含 PostgreSQL `COPY` 引數的選用文字字串。複製程序使用 [PostgreSQL COPY](https://www.postgresql.org/docs/current/sql-copy.html) 命令的引數及格式。

如果指定的檔案不存在於 Amazon S3 儲存貯體內，就會建立。如果檔案已存在，即會遭到覆寫。以下是存取 Amazon S3 中已匯出資料的語法。

```
s3-region://bucket-name[/path-prefix]/file-prefix
```

較大的匯出項目會儲存在多個檔案中，每個檔案的大小上限約為 6 GB。其他檔案名稱具有相同的檔案字首，但會加上 `_partXX`。`XX` 代表 2，接著是 3，以此類推 舉例來說，假設您要指定儲存資料檔案的路徑，如下所示。

```
s3-us-west-2://amzn-s3-demo-bucket/my-prefix
```

如果匯出必須建立三個資料檔案，則 Amazon S3 儲存貯體會包含下列資料檔案。

```
s3-us-west-2://amzn-s3-demo-bucket/my-prefix
s3-us-west-2://amzn-s3-demo-bucket/my-prefix_part2
s3-us-west-2://amzn-s3-demo-bucket/my-prefix_part3
```

如需此函數的完整參考以及其他呼叫方式，請參閱 [aws\$1s3.query\$1export\$1to\$1s3](postgresql-s3-export-functions.md#aws_s3.export_query_to_s3)。如需存取 Amazon S3 中檔案的詳細資訊，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[檢視物件](https://docs.aws.amazon.com/AmazonS3/latest/userguide/OpeningAnObject.html)。

## 匯出至使用自訂分隔符號的 CSV 檔案
<a name="postgresql-s3-export-examples-custom-delimiter"></a>

下列範例示範如何呼叫使用自訂分隔符號來將資料匯入檔案的 [aws\$1s3.query\$1export\$1to\$1s3](postgresql-s3-export-functions.md#aws_s3.export_query_to_s3) 函數。範例使用了 [PostgreSQL COPY](https://www.postgresql.org/docs/current/sql-copy.html) 命令的引數，來指定逗號分隔值 (CSV) 格式和冒號 (:) 分隔符號。

```
SELECT * from aws_s3.query_export_to_s3('select * from basic_test', :'s3_uri_1', options :='format csv, delimiter $$:$$');
```

## 利用編碼匯出至二進位檔案
<a name="postgresql-s3-export-examples-encoded"></a>

下列範例示範如何呼叫 [aws\$1s3.query\$1export\$1to\$1s3](postgresql-s3-export-functions.md#aws_s3.export_query_to_s3) 函數來將資料匯出至使用 Windows-1253 編碼的二進位檔案。

```
SELECT * from aws_s3.query_export_to_s3('select * from basic_test', :'s3_uri_1', options :='format binary, encoding WIN1253');
```