# 使用 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* 的存储桶中。使用以下 SQL 语句在 psql 中创建示例表和数据。

```
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');
```