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

# 教學課程：查詢 Amazon S3 資料
<a name="aurora-analytics-tutorial"></a>

本教學課程將逐步引導您從頭開始設定分析功能，並針對 Amazon S3 中的 Parquet 資料執行您的第一個分析查詢。最後，您將有一個 Aurora PostgreSQL 資料庫叢集，透過標準 SQL 查詢 Amazon S3 資料。

**Topics**
+ [先決條件](#aurora-analytics-tutorial-prerequisites)
+ [步驟 1：建立 IAM 政策和角色](#aurora-analytics-tutorial-step-1)
+ [步驟 2：建立 Aurora PostgreSQL 資料庫叢集](#aurora-analytics-tutorial-step-2)
+ [步驟 3：將 IAM 角色連接至資料庫叢集](#aurora-analytics-tutorial-step-3)
+ [步驟 4：設定 Amazon S3 閘道 VPC 端點](#aurora-analytics-tutorial-step-4)
+ [步驟 5：連接並安裝擴充功能](#aurora-analytics-tutorial-step-5)
+ [步驟 6：建立外部資料表](#aurora-analytics-tutorial-step-6)
+ [步驟 7：執行您的第一個查詢](#aurora-analytics-tutorial-step-7)
+ [步驟 8：使用本機 PostgreSQL 資料表加入](#aurora-analytics-tutorial-step-8)
+ [步驟 9：將結果具體化為 PostgreSQL](#aurora-analytics-tutorial-step-9)
+ [步驟 10：檢查快取和效能](#aurora-analytics-tutorial-step-10)
+ [清除](#aurora-analytics-tutorial-cleanup)
+ [後續步驟](#aurora-analytics-tutorial-next-steps)

## 先決條件
<a name="aurora-analytics-tutorial-prerequisites"></a>

開始前，請確定您具有下列項目：
+ 具有建立 IAM 角色、Amazon RDS 叢集和 VPC 端點許可 AWS 的帳戶。
+ 已安裝並設定 AWS CLI。
+ 在不同可用區域中至少有兩個子網路的 VPC、資料庫子網路群組，以及 Aurora 的安全群組。
+ Amazon S3 儲存貯體中的 Parquet 資料檔案。如果您還沒有資料，則可以上傳範例檔案 （本教學課程使用範例訂單資料集）。

## 步驟 1：建立 IAM 政策和角色
<a name="aurora-analytics-tutorial-step-1"></a>

建立 IAM 政策，授予延伸模組對 Amazon S3 儲存貯體的讀取存取權，然後建立角色並連接政策。

若要建立 IAM 政策：

```
aws iam create-policy \
  --policy-name AuroraAnalyticsReadAccess \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "S3Access",
        "Effect": "Allow",
        "Action": ["s3:ListBucket", "s3:GetObject", "s3:GetBucketLocation"],
        "Resource": ["arn:aws:s3:::your-data-bucket", "arn:aws:s3:::your-data-bucket/*"]
      }
    ]
  }'
```

若要建立 IAM 角色並連接政策：

```
aws iam create-role \
  --role-name AuroraAnalyticsRole \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {"Service": "rds.amazonaws.com"},
        "Action": "sts:AssumeRole"
      }
    ]
  }'

aws iam attach-role-policy \
  --role-name AuroraAnalyticsRole \
  --policy-arn arn:aws:iam::<account-id>:policy/AuroraAnalyticsReadAccess
```

## 步驟 2：建立 Aurora PostgreSQL 資料庫叢集
<a name="aurora-analytics-tutorial-step-2"></a>

建立資料庫叢集參數群組，然後建立資料庫叢集和資料庫執行個體。

若要在啟用 功能的情況下建立參數群組：

```
aws rds create-db-cluster-parameter-group \
  --db-cluster-parameter-group-name my-analytics-params \
  --db-parameter-group-family aurora-postgresql17 \
  --description "Parameter group with aurora_analytics enabled"

aws rds modify-db-cluster-parameter-group \
  --db-cluster-parameter-group-name my-analytics-params \
  --parameters "ParameterName=aurora_analytics.enabled,ParameterValue=true,ApplyMethod=immediate"
```

若要建立資料庫叢集：

```
aws rds create-db-cluster \
  --db-cluster-identifier my-analytics-cluster \
  --engine aurora-postgresql \
  --engine-version 17.11 \
  --master-username postgres \
  --master-user-password <password> \
  --db-cluster-parameter-group-name my-analytics-params \
  --db-subnet-group-name <subnet-group> \
  --vpc-security-group-ids <security-group-id>
```

若要建立資料庫執行個體：

```
aws rds create-db-instance \
  --db-instance-identifier my-analytics-instance-1 \
  --db-cluster-identifier my-analytics-cluster \
  --db-instance-class db.r8gd.xlarge \
  --engine aurora-postgresql
```

等待資料庫執行個體變成可用：

```
aws rds wait db-instance-available \
  --db-instance-identifier my-analytics-instance-1
```

## 步驟 3：將 IAM 角色連接至資料庫叢集
<a name="aurora-analytics-tutorial-step-3"></a>

```
aws rds add-role-to-db-cluster \
  --db-cluster-identifier my-analytics-cluster \
  --role-arn arn:aws:iam::<account-id>:role/AuroraAnalyticsRole \
  --feature-name AuroraAnalytics
```

## 步驟 4：設定 Amazon S3 閘道 VPC 端點
<a name="aurora-analytics-tutorial-step-4"></a>

如果您的 Aurora 資料庫叢集位於私有子網路中，請建立 Amazon S3 閘道端點：

```
aws ec2 create-vpc-endpoint \
  --vpc-id <vpc-id> \
  --service-name com.amazonaws.<region>.s3 \
  --route-table-ids <route-table-id>
```

## 步驟 5：連接並安裝擴充功能
<a name="aurora-analytics-tutorial-step-5"></a>

使用 psql 連線至 Aurora PostgreSQL 資料庫叢集：

```
psql --host=my-analytics-cluster.<region>.rds.amazonaws.com \
     --port=5432 --username=postgres --password
```

安裝 `aurora_analytics` 擴充功能：

```
CREATE EXTENSION aurora_analytics;
```

驗證安裝：

```
SELECT extname, extversion FROM pg_extension WHERE extname = 'aurora_analytics';
```

預期的輸出結果：

```
     extname      | extversion
------------------+------------
 aurora_analytics | 1.0
```

驗證是否已建立外部伺服器：

```
SELECT srvname FROM pg_foreign_server WHERE srvname = 'aurora_analytics_server';
```

## 步驟 6：建立外部資料表
<a name="aurora-analytics-tutorial-step-6"></a>

在 Amazon S3 中建立指向 Parquet 資料的外部資料表。使用空白括號 () 可讓 Aurora PostgreSQL 從 Parquet 中繼資料自動推斷結構描述：

```
CREATE FOREIGN TABLE ft_orders ()
SERVER aurora_analytics_server
OPTIONS (
    location 's3://your-data-bucket/data/orders/',
    format 'parquet',
    region 'us-east-1'
);
```

檢查推斷的結構描述：

```
\d ft_orders
```

## 步驟 7：執行您的第一個查詢
<a name="aurora-analytics-tutorial-step-7"></a>

```
-- Count all rows
SELECT COUNT(*) FROM ft_orders;

-- Aggregation with filter
SELECT
    status,
    COUNT(*) AS order_count,
    SUM(total_amount) AS total_revenue,
    AVG(total_amount) AS avg_order_value
FROM ft_orders
WHERE order_date >= '2024-01-01'
GROUP BY status
ORDER BY total_revenue DESC;
```

## 步驟 8：使用本機 PostgreSQL 資料表加入
<a name="aurora-analytics-tutorial-step-8"></a>

建立本機資料表並將其與您的外部資料表聯結：

```
-- Create a local dimension table
CREATE TABLE customer_segments (
    customer_id BIGINT PRIMARY KEY,
    segment TEXT,
    region TEXT
);

INSERT INTO customer_segments VALUES
    (1, 'VIP', 'US-West'),
    (2, 'Premium', 'US-East'),
    (3, 'Regular', 'EU-West');

-- Join local table with S3 data
SELECT
    cs.segment,
    cs.region,
    COUNT(*) AS order_count,
    SUM(o.total_amount) AS total_revenue
FROM ft_orders o
JOIN customer_segments cs ON o.customer_id = cs.customer_id
WHERE o.order_date >= '2024-01-01'
GROUP BY cs.segment, cs.region
ORDER BY total_revenue DESC;
```

## 步驟 9：將結果具體化為 PostgreSQL
<a name="aurora-analytics-tutorial-step-9"></a>

將 Amazon S3 的查詢結果儲存為本機 PostgreSQL 資料表，以便快速重複存取：

```
CREATE TABLE monthly_revenue AS
SELECT
    DATE_TRUNC('month', order_date) AS month,
    COUNT(*) AS order_count,
    SUM(total_amount) AS total_revenue,
    AVG(total_amount) AS avg_order_value
FROM ft_orders
WHERE order_date >= '2024-01-01'
GROUP BY DATE_TRUNC('month', order_date)
ORDER BY month;

-- Query the materialized result (fast, local PostgreSQL)
SELECT * FROM monthly_revenue;
```

## 步驟 10：檢查快取和效能
<a name="aurora-analytics-tutorial-step-10"></a>

執行查詢後，請確認快取是否正常運作：

```
-- Check cache size (should be non-zero after queries)
SELECT pg_size_pretty(aurora_analytics_cache_size()) AS cache_size;

-- Check per-query statistics
SELECT query,
       pg_size_pretty(analytics_cache_hit_bytes) AS cache_hits,
       pg_size_pretty(analytics_remote_read_bytes) AS s3_reads
FROM aurora_analytics_stat_statements()
WHERE analytics_cache_hit_bytes > 0 OR analytics_remote_read_bytes > 0;
```

再次執行相同的查詢並注意到改進：第二個執行會從快取讀取，而不是 Amazon S3。

## 清除
<a name="aurora-analytics-tutorial-cleanup"></a>

若要避免持續收費，請刪除您建立的資源：

```
-- Drop the foreign table
DROP FOREIGN TABLE ft_orders;
DROP TABLE customer_segments;
DROP TABLE monthly_revenue;
```

```
aws rds delete-db-instance --db-instance-identifier my-analytics-instance-1 --skip-final-snapshot
aws rds delete-db-cluster --db-cluster-identifier my-analytics-cluster --skip-final-snapshot
aws iam detach-role-policy --role-name AuroraAnalyticsRole --policy-arn arn:aws:iam::<account-id>:policy/AuroraAnalyticsReadAccess
aws iam delete-role --role-name AuroraAnalyticsRole
aws iam delete-policy --policy-arn arn:aws:iam::<account-id>:policy/AuroraAnalyticsReadAccess
```

## 後續步驟
<a name="aurora-analytics-tutorial-next-steps"></a>

現在您已完成教學課程，請探索下列主題：
+ [使用外部資料表](aurora-analytics-foreign-tables.md)：了解 Iceberg 資料表、具有快照和時間戳記的時間歷程，以及結構描述管理。
+ [組態參數](aurora-analytics-configuration-parameters.md)：`query_mem`調整工作負載。
+ [最佳實務](aurora-analytics-best-practices.md)：最佳化資料配置、執行個體大小和並行。
+ [監控和故障診斷](aurora-analytics-monitoring-troubleshooting.md)：指標、等待事件和診斷問題。