"
]
}
]
}
```
------
# 針對 Athena 使用 CalledVia 內容索引鍵
當[委託](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal)人向 提出[請求](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-request)時 AWS， 會將請求資訊 AWS 收集到評估和授權請求的*請求內容*中。您可以使用 JSON 政策的 `Condition` 元素，來比較請求內容中的鍵和您在政策中指定的鍵值。*全域條件內容索引鍵*為帶有 `aws:` 字首的條件索引鍵。
## 關於 aws:CalledVia 內容索引鍵
您可以使用 [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-calledvia](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-calledvia) 全域條件內容索引鍵，以將政策中的服務與代表 IAM 主體 (使用者或角色) 提出請求的服務進行比較。當委託人向 提出請求時 AWS 服務，該服務可能會使用委託人的登入資料向其他 服務提出後續請求。`aws:CalledVia` 鍵包含代表主體提出請求的鏈結中，每個服務的排序清單。
透過指定`aws:CalledVia`內容金鑰的服務主體名稱，您可以將內容金鑰設為 AWS 服務特定。例如，您可以使用 `aws:CalledVia` 條件索引鍵來限制僅能有從 Athena 進行的請求。若要搭配 Athena 使用政策中的 `aws:CalledVia` 條件索引鍵，您需指定 Athena 服務主體名稱 `athena.amazonaws.com`，如下列範例所示。
```
...
"Condition": {
"ForAnyValue:StringEquals": {
"aws:CalledVia": "athena.amazonaws.com"
}
}
...
```
您可以使用 `aws:CalledVia` 內容索引鍵，以確保如果呼叫者從 Athena 呼叫資源，則其僅能存取一項資源 (如 Lambda 函數)。
**注意**
`aws:CalledVia` 內容索引鍵與受信任的身分傳播功能不相容。
## 新增 CalledVia 內容索引鍵，以存取 Lambda 函式
Athena 要求呼叫者需具有 `lambda:InvokeFunction` 許可，以呼叫與查詢相關聯的 Lambda 函數。下列陳述式指定使用者只能從 Athena 調用 Lambda 函式。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor3",
"Effect": "Allow",
"Action": "lambda:InvokeFunction",
"Resource": "arn:aws:lambda:us-east-1:111122223333:function:OneAthenaLambdaFunction",
"Condition": {
"ForAnyValue:StringEquals": {
"aws:CalledVia": "athena.amazonaws.com"
}
}
}
]
}
```
------
以下範例會說明如何在政策中加入先前的陳述式，以允許使用者執行並讀取聯合查詢。獲准執行這些動作的主體在其執行的查詢中，可以指定與聯合資料來源相關聯的 Athena 目錄。不過，除非透過 Athena 呼叫函數，否則主體無法存取相關聯的 Lambda 函數。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"athena:GetWorkGroup",
"s3:PutObject",
"s3:GetObject",
"athena:StartQueryExecution",
"s3:AbortMultipartUpload",
"athena:StopQueryExecution",
"athena:GetQueryExecution",
"athena:GetQueryResults",
"s3:ListMultipartUploadParts"
],
"Resource": [
"arn:aws:athena:*:111122223333:workgroup/WorkGroupName",
"arn:aws:s3:::MyQueryResultsBucket/*",
"arn:aws:s3:::MyLambdaSpillBucket/MyLambdaSpillPrefix*"
]
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": "athena:ListWorkGroups",
"Resource": "*"
},
{
"Sid": "VisualEditor2",
"Effect": "Allow",
"Action":
[
"s3:ListBucket",
"s3:GetBucketLocation"
],
"Resource": "arn:aws:s3:::MyLambdaSpillBucket"
},
{
"Sid": "VisualEditor3",
"Effect": "Allow",
"Action": "lambda:InvokeFunction",
"Resource": [
"arn:aws:lambda:*:111122223333:function:OneAthenaLambdaFunction",
"arn:aws:lambda:*:111122223333:function:AnotherAthenaLambdaFunction"
],
"Condition": {
"ForAnyValue:StringEquals": {
"aws:CalledVia": "athena.amazonaws.com"
}
}
}
]
}
```
------
如需有關 `CalledVia` 條件索引鍵的詳細資訊，請參閱《IAM 使用者指南》**中的 [AWS 全域條件內容索引鍵](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html)。
# 允許存取外部 Hive 中繼存放區的 Athena 資料連接器
本主題中的許可政策範例示範需要允許的動作，以及允許這些動作的資源。將類似的許可政策連接至 IAM 身分之前，請仔細檢查這些政策，並根據您的需求進行修改。
+ [Example Policy to Allow an IAM Principal to Query Data Using Athena Data Connector for External Hive Metastore](#hive-using-iam)
+ [Example Policy to Allow an IAM Principal to Create an Athena Data Connector for External Hive Metastore](#hive-creating-iam)
**Example - 允許 IAM 主體使用外部 Hive 中繼存放區的 Athena 資料連接器來查詢資料**
除了授權完整存取 Athena 動作的 [AWS 受管政策：AmazonAthenaFullAccess](security-iam-awsmanpol.md#amazonathenafullaccess-managed-policy)，下列政策也會連接至 IAM 委託人。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": [
"lambda:GetFunction",
"lambda:GetLayerVersion",
"lambda:InvokeFunction"
],
"Resource": [
"arn:aws:lambda:*:111122223333:function:MyAthenaLambdaFunction",
"arn:aws:lambda:*:111122223333:function:AnotherAthenaLambdaFunction",
"arn:aws:lambda:*:111122223333:layer:MyAthenaLambdaLayer:*"
]
},
{
"Sid": "VisualEditor2",
"Effect": "Allow",
"Action": [
"s3:GetBucketLocation",
"s3:GetObject",
"s3:ListBucket",
"s3:PutObject",
"s3:ListMultipartUploadParts",
"s3:AbortMultipartUpload"
],
"Resource": "arn:aws:s3:::MyLambdaSpillBucket/MyLambdaSpillLocation"
}
]
}
```
**許可說明**
| 允許的動作 | 說明 |
| --- | --- |
| "s3:GetBucketLocation",
"s3:GetObject",
"s3:ListBucket",
"s3:PutObject",
"s3:ListMultipartUploadParts",
"s3:AbortMultipartUpload"
| `s3` 動作允許讀取和寫入指定為 `"arn:aws:s3:::MyLambdaSpillBucket/MyLambdaSpillLocation"` 的資源，其中 *MyLambdaSpillLocation* 會識別一或多個叫用的 Lambda 函數的組態中所指定的溢出儲存貯體。只有在您使用 Lambda 層建立自訂執行時間相依性，以在部署時間減少函數成品規模時，才需要 *arn:aws:lambda:\$1:*MyAWSAcctId*:layer:*MyAthenaLambdaLayer*:\$1* 資源識別碼。最後面的 `*` 是層版本的萬用字元。 |
| "lambda:GetFunction",
"lambda:GetLayerVersion",
"lambda:InvokeFunction"
| 允許查詢叫用 Resource區塊中指定的 AWS Lambda 函數。例如，arn:aws:lambda:\$1:MyAWSAcctId:function:MyAthenaLambdaFunction，其中 MyAthenaLambdaFunction 會指定要叫用的 Lambda 函數的名稱。如範例所示，可以指定多個函數。 |
**Example - 允許 IAM 主體建立外部 Hive 中繼存放區的 Athena 資料連接器**
除了授權完整存取 Athena 動作的 [AWS 受管政策：AmazonAthenaFullAccess](security-iam-awsmanpol.md#amazonathenafullaccess-managed-policy)，下列政策也會連接至 IAM 委託人。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"lambda:GetFunction",
"lambda:ListFunctions",
"lambda:GetLayerVersion",
"lambda:InvokeFunction",
"lambda:CreateFunction",
"lambda:DeleteFunction",
"lambda:PublishLayerVersion",
"lambda:DeleteLayerVersion",
"lambda:UpdateFunctionConfiguration",
"lambda:PutFunctionConcurrency",
"lambda:DeleteFunctionConcurrency"
],
"Resource": "arn:aws:lambda:*:111122223333: function: MyAthenaLambdaFunctionsPrefix*"
}
]
}
```
**許可說明**
允許查詢叫用 `Resource` 區塊中指定 AWS Lambda 函數的 AWS Lambda 函數。例如，`arn:aws:lambda:*:MyAWSAcctId:function:MyAthenaLambdaFunction`，其中 *MyAthenaLambdaFunction* 會指定要叫用的 Lambda 函數的名稱。如範例所示，可以指定多個函數。
# 允許 Lambda 函數存取外部 Hive 中繼存放區
若要在帳戶中呼叫 Lambda 函數，您必須建立具有下列許可的角色：
+ `AWSLambdaVPCAccessExecutionRole` - [AWS Lambda 執行角色](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html)許可，用於管理將您的函數連接到 VPC 的彈性網路介面。請確定您有足夠數量的網路界面和 IP 地址可用。
+ `AmazonAthenaFullAccess` - [AmazonAthenaFullAccess](security-iam-awsmanpol.md#amazonathenafullaccess-managed-policy) 受管政策會授予 Athena 的完整存取權。
+ 允許 Lambda 函數寫入 S3 並允許 Athena 從 S3 讀取的 Amazon S3 政策。
例如，下列政策定義溢出位置 `s3:\\mybucket\spill` 的許可。
------
#### [ JSON ]
****
```
{ "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [
"s3:GetBucketLocation", "s3:GetObject", "s3:ListBucket", "s3:PutObject" ], "Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/spill" ] } ] }
```
------
每當您使用 IAM 政策時，請務必遵循 IAM 最佳實務。如需詳細資訊，請參閱《IAM 使用者指南》**中的 [IAM 中的安全性最佳實務](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)。
## 建立 Lambda 函式
若要在您的帳戶中建立 Lambda 函數，需具備函數開發許可或 `AWSLambdaFullAccess` 角色。如需詳細資訊，請參閱 [AWS Lambda身分型 IAM 政策](https://docs.aws.amazon.com/lambda/latest/dg/access-control-identity-based.html)。
由於 Athena 使用 AWS Serverless Application Repository 來建立 Lambda 函數，因此建立 Lambda 函數的超級使用者或管理員也應該具有 IAM 政策[，以允許 Athena 聯合查詢](federated-query-iam-access.md)。
## 設定目錄註冊和中繼資料 API 操作的許可
若要 API 存取目錄註冊和中繼資料操作，您可以使用 [AmazonAthenaFullAccess 受管政策](security-iam-awsmanpol.md#amazonathenafullaccess-managed-policy)。如果您不使用 `AmazonAthenaFullAccess` 政策，請將下列 API 操作新增至您的 Athena 政策：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:ListDataCatalogs",
"athena:GetDataCatalog",
"athena:CreateDataCatalog",
"athena:UpdateDataCatalog",
"athena:DeleteDataCatalog",
"athena:GetDatabase",
"athena:ListDatabases",
"athena:GetTableMetadata",
"athena:ListTableMetadata"
],
"Resource": [
"*"
]
}
]
}
```
------
## 跨區域呼叫 Lambda 函式
依預設，Athena 會叫用在相同區域中定義的 Lambda 函數。若要在執行 Athena 查詢的區域 AWS 區域 以外的 中叫用 Lambda 函數，請使用 Lambda 函數的完整 ARN。
下列範例說明了歐洲 (法蘭克福) 區域中的目錄如何在美國東部 (維吉尼亞北部) 區域中指定 Lambda 函式，以從歐洲 (法蘭克福) 區域中的 Hive 中繼存放區擷取資料。
```
arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-new
```
當您以這種方式指定完整的 ARN 時，Athena 可以在 `us-east-1` 呼叫 `external-hms-service-new` Lambda 函數，從 `eu-central-1` 擷取 Hive 中繼存放區資料。
**注意**
目錄應該在您 AWS 區域 用來執行 Athena 查詢的相同 中註冊。
## 跨帳戶呼叫 Lambda 函式
有時您可能需要從不同的帳戶存取 Hive 中繼存放區。例如，若要執行 Hive 中繼存放區，您可以使用與用於 Athena 查詢的帳戶不同的帳戶。不同的群組或團隊可能會在其 VPC 內使用不同的帳戶來執行 Hive 中繼存放區。或者，您可能想要存取來自不同群組或團隊的不同 Hive 中繼存放區的中繼資料。
Athena 會使用 [AWS Lambda 支援進行跨帳戶存取](https://aws.amazon.com/blogs/compute/easy-authorization-of-aws-lambda-functions/)，以啟用 Hive 中繼存放區的跨帳戶存取。
**注意**
請注意，Athena 的跨帳戶存取通常意味著可跨帳戶存取 Amazon S3 中的中繼資料和資料。
想像下列案例：
+ 帳戶 `111122223333` 在 Athena 中的 us-east-1 上設定 Lambda 函數 `external-hms-service-new`，以存取 EMR 叢集上執行的 Hive 中繼存放區。
+ 帳戶 `111122223333` 想要允許帳戶 444455556666 存取 Hive 中繼存放區資料。
若要授予帳戶`444455556666`存取 Lambda 函數 的權限`external-hms-service-new`，帳戶`111122223333`會使用下列 AWS CLI `add-permission`命令。為了方便閱讀，命令已經過格式化處理。
```
$ aws --profile perf-test lambda add-permission
--function-name external-hms-service-new
--region us-east-1
--statement-id Id-ehms-invocation2
--action "lambda:InvokeFunction"
--principal arn:aws:iam::444455556666:user/perf1-test
{
"Statement": "{\"Sid\":\"Id-ehms-invocation2\",
\"Effect\":\"Allow\",
\"Principal\":{\"AWS\":\"arn:aws:iam::444455556666:user/perf1-test\"},
\"Action\":\"lambda:InvokeFunction\",
\"Resource\":\"arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-new\"}"
}
```
若要檢查 Lambda 許可，請使用 `get-policy` 命令，如下列範例所示。為了方便閱讀，命令已經過格式化處理。
```
$ aws --profile perf-test lambda get-policy
--function-name arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-new
--region us-east-1
{
"RevisionId": "711e93ea-9851-44c8-a09f-5f2a2829d40f",
"Policy": "{\"Version\":\"2012-10-17\",
\"Id\":\"default\",
\"Statement\":[{\"Sid\":\"Id-ehms-invocation2\",
\"Effect\":\"Allow\",
\"Principal\":{\"AWS\":\"arn:aws:iam::444455556666:user/perf1-test\"},
\"Action\":\"lambda:InvokeFunction\",
\"Resource\":\"arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-new\"}]}"
}
```
新增許可後，您可以在定義目錄 `ehms` 時，在 `us-east-1` 上使用 Lambda 函數的完整 ARN，如下所示：
```
arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-new
```
如需跨區域呼叫的相關資訊，請參閱本主題稍早的[跨區域呼叫 Lambda 函式](#hive-metastore-iam-access-lambda-cross-region-invocation)。
### 授予資料的跨帳戶存取權
在執行 Athena 查詢之前，您必須授予對 Amazon S3 中資料的跨帳戶存取。您可採用下列其中一種方式來這麼做：
+ 使用[正式使用者 ID](https://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html) 來更新 Amazon S3 儲存貯體的存取控制清單政策。
+ 將跨帳戶存取新增至 Amazon S3 儲存貯體政策。
例如，將下列政策新增至帳戶 `111122223333` 中的 Amazon S3 儲存貯體政策，以允許帳戶 `444455556666` 從指定的 Amazon S3 位置讀取資料。
------
#### [ JSON ]
****
```
{ "Version":"2012-10-17", "Statement": [ { "Sid": "Stmt1234567890123", "Effect":
"Allow", "Principal": { "AWS":
"arn:aws:iam::444455556666:user/perf1-test"
}, "Action": "s3:GetObject", "Resource": "arn:aws:s3:::athena-test/lambda/dataset/*" } ]
}
```
------
**注意**
您可能不只需要將資料的跨帳戶存取授予 Amazon S3，也需要授予 Amazon S3 溢出位置的跨帳戶存取。當回應物件的大小超過指定閾值時，您的 Lambda 函數會將額外的資料溢出到溢出位置。請參閱本主題開頭的範例政策。
在目前的範例中，將跨帳戶存取授予 `444455556666,` 後，`444455556666` 可以在自己的 `ehms` 中使用目錄 `account` 來查詢帳戶 `111122223333` 中定義的資料表。
在下列範例中，SQL Workbench 設定檔 `perf-test-1` 適用於帳戶 `444455556666`。查詢使用目錄 `ehms` 來存取 Hive 中繼存放區和帳戶 `111122223333` 中的 Amazon S3 資料。
![\[在 SQL Workbench 中跨帳戶存取 Hive 中繼存放區和 Amazon S3 資料。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/hive-metastore-iam-access-lambda-1.png)
# 建立連接器和 Athena 目錄所需的許可
若要調用 Athena `CreateDataCatalog`，您必須建立具有下列許可的角色：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ECR",
"Effect": "Allow",
"Action": [
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer"
],
"Resource": "arn:aws:ecr:*:*:repository/*"
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"glue:TagResource",
"glue:GetConnection",
"glue:CreateConnection",
"glue:DeleteConnection",
"glue:UpdateConnection",
"serverlessrepo:CreateCloudFormationTemplate",
"serverlessrepo:GetCloudFormationTemplate",
"cloudformation:CreateStack",
"cloudformation:DeleteStack",
"cloudformation:DescribeStacks",
"cloudformation:CreateChangeSet",
"cloudformation:DescribeAccountLimits",
"cloudformation:CreateStackSet",
"cloudformation:ValidateTemplate",
"cloudformation:CreateUploadBucket",
"cloudformation:DescribeStackDriftDetectionStatus",
"cloudformation:ListExports",
"cloudformation:ListStacks",
"cloudformation:EstimateTemplateCost",
"cloudformation:ListImports",
"lambda:InvokeFunction",
"lambda:GetFunction",
"lambda:DeleteFunction",
"lambda:CreateFunction",
"lambda:TagResource",
"lambda:ListFunctions",
"lambda:GetAccountSettings",
"lambda:ListEventSourceMappings",
"lambda:ListVersionsByFunction",
"lambda:GetFunctionConfiguration",
"lambda:PutFunctionConcurrency",
"lambda:UpdateFunctionConfiguration",
"lambda:UpdateFunctionCode",
"lambda:DeleteFunctionConcurrency",
"lambda:RemovePermission",
"lambda:AddPermission",
"lambda:ListTags",
"lambda:GetAlias",
"lambda:GetPolicy",
"lambda:ListAliases",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"secretsmanager:ListSecrets",
"glue:GetCatalogs"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iam:AttachRolePolicy",
"iam:DetachRolePolicy",
"iam:DeleteRolePolicy",
"iam:PutRolePolicy",
"iam:GetRolePolicy",
"iam:CreateRole",
"iam:TagRole",
"iam:DeleteRole",
"iam:GetRole",
"iam:PassRole",
"iam:ListRoles",
"iam:ListAttachedRolePolicies",
"iam:ListRolePolicies",
"iam:GetPolicy",
"iam:UpdateRole"
],
"Resource": [
"arn:aws:iam::*:role/RoleName",
"arn:aws:iam::111122223333:policy/*"
]
}
]
}
```
------
# 允許存取 Athena 聯合查詢：範例政策
本主題中的許可政策範例示範需要允許的動作，以及允許這些動作的資源。將這些政策連接至 IAM 身分之前，請仔細檢查政策，並根據您的需求進行修改。
如需有關將政策連接至 IAM 身分的資訊，請參閱《[IAM 使用者指南](https://docs.aws.amazon.com/IAM/latest/UserGuide/)》中的[新增和移除 IAM 身分許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。
+ [Example policy to allow an IAM principal to run and return results using Athena Federated Query](#fed-using-iam)
+ [Example Policy to Allow an IAM Principal to Create a Data Source Connector](#fed-creating-iam)
**Example - 允許 IAM 主體使用 Athena 聯合查詢執行並傳回結果**
在下列以身分識別為基礎的許可政策中，允許使用者或其他 IAM 委託人需要的動作，有這些動作才能使用 Athena 聯合查詢。獲准執行這些動作的委託人在其執行的查詢中，可以指定與聯合資料來源相關聯的 Athena 目錄。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Athena",
"Effect": "Allow",
"Action": [
"athena:GetDataCatalog",
"athena:GetQueryExecution",
"athena:GetQueryResults",
"athena:GetWorkGroup",
"athena:StartQueryExecution",
"athena:StopQueryExecution"
],
"Resource": [
"arn:aws:athena:*:111122223333:workgroup/WorkgroupName",
"arn:aws:athena:us-east-1:111122223333:datacatalog/DataCatalogName"
]
},
{
"Sid": "ListAthenaWorkGroups",
"Effect": "Allow",
"Action": "athena:ListWorkGroups",
"Resource": "*"
},
{
"Sid": "Lambda",
"Effect": "Allow",
"Action": "lambda:InvokeFunction",
"Resource": [
"arn:aws:lambda:*:111122223333:function:OneAthenaLambdaFunction",
"arn:aws:lambda:*:111122223333:function:AnotherAthenaLambdaFunction"
]
},
{
"Sid": "S3",
"Effect": "Allow",
"Action": [
"s3:AbortMultipartUpload",
"s3:GetBucketLocation",
"s3:GetObject",
"s3:ListBucket",
"s3:ListMultipartUploadParts",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::MyLambdaSpillBucket",
"arn:aws:s3:::MyLambdaSpillBucket/*",
"arn:aws:s3:::MyQueryResultsBucket",
"arn:aws:s3:::MyQueryResultsBucket/*"
]
}
]
}
```
**許可說明**
| 允許的動作 | 說明 |
| --- | --- |
| "athena:GetQueryExecution",
"athena:GetQueryResults",
"athena:GetWorkGroup",
"athena:StartQueryExecution",
"athena:StopQueryExecution"
| 執行聯合查詢所需的 Athena 許可。 |
| "athena:GetDataCatalog",
"athena:GetQueryExecution,"
"athena:GetQueryResults",
"athena:GetWorkGroup",
"athena:StartQueryExecution",
"athena:StopQueryExecution"
| 執行聯合檢視查詢所需的 Athena 許可。檢視需要 `GetDataCatalog` 動作。 |
| "lambda:InvokeFunction"
| 允許查詢叫用 Resource 區塊中指定 AWS Lambda 函數的 AWS Lambda 函數。例如，arn:aws:lambda:\$1:MyAWSAcctId:function:MyAthenaLambdaFunction，其中 MyAthenaLambdaFunction 會指定要叫用的 Lambda 函數的名稱。如範例所示，可以指定多個函式。 |
| "s3:AbortMultipartUpload",
"s3:GetBucketLocation",
"s3:GetObject",
"s3:ListBucket",
"s3:ListMultipartUploadParts",
"s3:PutObject"
| 需要 `s3:ListBucket` 和 `s3:GetBucketLocation` 許可才能存取執行 `StartQueryExecution` 的 IAM 主體的查詢輸出儲存貯體。 `s3:PutObject`、`s3:ListMultipartUploadParts` 和 `s3:AbortMultipartUpload` 允許將查詢結果寫入 `arn:aws:s3:::MyQueryResultsBucket/*` 資源識別碼指定的查詢結果儲存貯體的所有子資料夾，其中 *MyQueryResultsBucket* 是 Athena 查詢結果儲存貯體。如需詳細資訊，請參閱[使用查詢結果和近期查詢](querying.md)。 `s3:GetObject` 針對指定為 `arn:aws:s3:::MyQueryResultsBucket` 的資源，允許讀取查詢結果和查詢歷史記錄，其中 *MyQueryResultsBucket* 是 Athena 查詢結果儲存貯體。 `s3:GetObject` 還允許從指定為 `"arn:aws:s3:::MyLambdaSpillBucket/MyLambdaSpillPrefix*"` 的資源讀取，其中 *MyLambdaSpillPrefix* 是在一或多個叫用的 Lambda 函數的組態中指定。 |
**Example - 允許 IAM 主體建立資料來源連接器**
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"lambda:CreateFunction",
"lambda:ListVersionsByFunction",
"iam:CreateRole",
"lambda:GetFunctionConfiguration",
"iam:AttachRolePolicy",
"iam:PutRolePolicy",
"lambda:PutFunctionConcurrency",
"iam:PassRole",
"iam:DetachRolePolicy",
"lambda:ListTags",
"iam:ListAttachedRolePolicies",
"iam:DeleteRolePolicy",
"lambda:DeleteFunction",
"lambda:GetAlias",
"iam:ListRolePolicies",
"iam:GetRole",
"iam:GetPolicy",
"lambda:InvokeFunction",
"lambda:GetFunction",
"lambda:ListAliases",
"lambda:UpdateFunctionConfiguration",
"iam:DeleteRole",
"lambda:UpdateFunctionCode",
"s3:GetObject",
"lambda:AddPermission",
"iam:UpdateRole",
"lambda:DeleteFunctionConcurrency",
"lambda:RemovePermission",
"iam:GetRolePolicy",
"lambda:GetPolicy"
],
"Resource": [
"arn:aws:lambda:*:111122223333:function:MyAthenaLambdaFunctionsPrefix*",
"arn:aws:s3:::awsserverlessrepo-changesets-1iiv3xa62ln3m/*",
"arn:aws:iam::*:role/RoleName",
"arn:aws:iam::111122223333:policy/*"
]
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": [
"cloudformation:CreateUploadBucket",
"cloudformation:DescribeStackDriftDetectionStatus",
"cloudformation:ListExports",
"cloudformation:ListStacks",
"cloudformation:ListImports",
"lambda:ListFunctions",
"iam:ListRoles",
"lambda:GetAccountSettings",
"ec2:DescribeSecurityGroups",
"cloudformation:EstimateTemplateCost",
"ec2:DescribeVpcs",
"lambda:ListEventSourceMappings",
"cloudformation:DescribeAccountLimits",
"ec2:DescribeSubnets",
"cloudformation:CreateStackSet",
"cloudformation:ValidateTemplate"
],
"Resource": "*"
},
{
"Sid": "VisualEditor2",
"Effect": "Allow",
"Action": "cloudformation:*",
"Resource": [
"arn:aws:cloudformation:*:111122223333:stack/aws-serverless-repository-MyCFStackPrefix*/*",
"arn:aws:cloudformation:*:111122223333:stack/serverlessrepo-MyCFStackPrefix*/*",
"arn:aws:cloudformation:*:*:transform/Serverless-*",
"arn:aws:cloudformation:*:111122223333:stackset/aws-serverless-repository-MyCFStackPrefix*:*",
"arn:aws:cloudformation:*:111122223333:stackset/serverlessrepo-MyCFStackPrefix*:*"
]
},
{
"Sid": "VisualEditor3",
"Effect": "Allow",
"Action": "serverlessrepo:*",
"Resource": "arn:aws:serverlessrepo:*:*:applications/*"
},
{
"Sid": "ECR",
"Effect": "Allow",
"Action": [
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer"
],
"Resource": "arn:aws:ecr:*:*:repository/*"
}
]
}
```
**許可說明**
| 允許的動作 | 說明 |
| --- | --- |
| "lambda:CreateFunction",
"lambda:ListVersionsByFunction",
"lambda:GetFunctionConfiguration",
"lambda:PutFunctionConcurrency",
"lambda:ListTags",
"lambda:DeleteFunction",
"lambda:GetAlias",
"lambda:InvokeFunction",
"lambda:GetFunction",
"lambda:ListAliases",
"lambda:UpdateFunctionConfiguration",
"lambda:UpdateFunctionCode",
"lambda:AddPermission",
"lambda:DeleteFunctionConcurrency",
"lambda:RemovePermission",
"lambda:GetPolicy"
"lambda:GetAccountSettings",
"lambda:ListFunctions",
"lambda:ListEventSourceMappings",
| 允許建立和管理列為資源的 Lambda 函數。在範例中，資源識別符 `arn:aws:lambda:*:MyAWSAcctId:function:MyAthenaLambdaFunctionsPrefix*` 中使用名稱字首，其中 `MyAthenaLambdaFunctionsPrefix` 是 Lambda 函式群組的名稱中使用的共同字首，因此不需要個別指定為資源。您可以指定一或多個 Lambda 函數資源。 |
| "s3:GetObject"
| 允許讀取資源識別符 所指定 AWS Serverless Application Repository 需要 的儲存貯體arn:aws:s3:::awsserverlessrepo-changesets-1iiv3xa62ln3m/\$1。此儲存貯體可能專屬於您的帳戶。 |
| "cloudformation:*"
| 允許建立和管理資源 指定的 CloudFormation 堆疊`MyCFStackPrefix`。這些堆疊和堆疊集是部署連接器和 UDFs AWS Serverless Application Repository 的方式。 |
| "serverlessrepo:*"
| 允許搜尋、檢視、發佈和更新 中由資源識別符 AWS Serverless Application Repository指定的應用程式arn:aws:serverlessrepo:\$1:\$1:applications/\$1。 |
| "ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer"
| 允許已建立的 Lambda 函式存取聯合連接器 ECR 映像。 |
# 允許存取 Athena UDF：範例政策
本主題中的許可政策範例示範需要允許的動作，以及允許這些動作的資源。將類似的許可政策連接至 IAM 身分之前，請仔細檢查這些政策，並根據您的需求進行修改。
+ [Example Policy to Allow an IAM Principal to Run and Return Queries that Contain an Athena UDF Statement](#udf-using-iam)
+ [Example Policy to Allow an IAM Principal to Create an Athena UDF](#udf-creating-iam)
**Example - 允許 IAM 主體執行並傳回包含 Athena UDF 陳述式的查詢**
在下列以身分識別為基礎的許可政策中，允許使用者或其他 IAM 委託人需要的動作，有這些動作才能執行使用 Athena UDF 陳述式的查詢。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"athena:StartQueryExecution",
"lambda:InvokeFunction",
"athena:GetQueryResults",
"s3:ListMultipartUploadParts",
"athena:GetWorkGroup",
"s3:PutObject",
"s3:GetObject",
"s3:AbortMultipartUpload",
"athena:StopQueryExecution",
"athena:GetQueryExecution",
"s3:GetBucketLocation"
],
"Resource": [
"arn:aws:athena:*:MyAWSAcctId:workgroup/MyAthenaWorkGroup",
"arn:aws:s3:::MyQueryResultsBucket/*",
"arn:aws:lambda:*:MyAWSAcctId:function:OneAthenaLambdaFunction",
"arn:aws:lambda:*:MyAWSAcctId:function:AnotherAthenaLambdaFunction"
]
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": "athena:ListWorkGroups",
"Resource": "*"
}
]
}
```
**許可說明**
| 允許的動作 | 說明 |
| --- | --- |
| "athena:StartQueryExecution",
"athena:GetQueryResults",
"athena:GetWorkGroup",
"athena:StopQueryExecution",
"athena:GetQueryExecution",
| 在 `MyAthenaWorkGroup` 工作群組中執行查詢所需的 Athena 許可。 |
| "s3:PutObject",
"s3:GetObject",
"s3:AbortMultipartUpload"
| `s3:PutObject` 和 `s3:AbortMultipartUpload` 允許將查詢結果寫入 `arn:aws:s3:::MyQueryResultsBucket/*` 資源識別碼指定的查詢結果儲存貯體的所有子資料夾，其中 *MyQueryResultsBucket* 是 Athena 查詢結果儲存貯體。如需詳細資訊，請參閱[使用查詢結果和近期查詢](querying.md)。 `s3:GetObject` 針對指定為 `arn:aws:s3:::MyQueryResultsBucket` 的資源，允許讀取查詢結果和查詢歷史記錄，其中 *MyQueryResultsBucket* 是 Athena 查詢結果儲存貯體。如需詳細資訊，請參閱[使用查詢結果和近期查詢](querying.md)。 `s3:GetObject` 還允許從指定為 `"arn:aws:s3:::MyLambdaSpillBucket/MyLambdaSpillPrefix*"` 的資源讀取，其中 *MyLambdaSpillPrefix* 是在一或多個叫用的 Lambda 函數的組態中指定。 |
| "lambda:InvokeFunction"
| 允許查詢叫用 Resource區塊中指定的 AWS Lambda 函數。例如，arn:aws:lambda:\$1:MyAWSAcctId:function:MyAthenaLambdaFunction，其中 MyAthenaLambdaFunction 會指定要叫用的 Lambda 函數的名稱。如範例所示，可以指定多個函數。 |
**Example - 允許 IAM 主體建立 Athena UDF**
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"lambda:CreateFunction",
"lambda:ListVersionsByFunction",
"iam:CreateRole",
"lambda:GetFunctionConfiguration",
"iam:AttachRolePolicy",
"iam:PutRolePolicy",
"lambda:PutFunctionConcurrency",
"iam:PassRole",
"iam:DetachRolePolicy",
"lambda:ListTags",
"iam:ListAttachedRolePolicies",
"iam:DeleteRolePolicy",
"lambda:DeleteFunction",
"lambda:GetAlias",
"iam:ListRolePolicies",
"iam:GetRole",
"iam:GetPolicy",
"lambda:InvokeFunction",
"lambda:GetFunction",
"lambda:ListAliases",
"lambda:UpdateFunctionConfiguration",
"iam:DeleteRole",
"lambda:UpdateFunctionCode",
"s3:GetObject",
"lambda:AddPermission",
"iam:UpdateRole",
"lambda:DeleteFunctionConcurrency",
"lambda:RemovePermission",
"iam:GetRolePolicy",
"lambda:GetPolicy"
],
"Resource": [
"arn:aws:lambda:*:111122223333:function:MyAthenaLambdaFunctionsPrefix*",
"arn:aws:s3:::awsserverlessrepo-changesets-1iiv3xa62ln3m/*",
"arn:aws:iam::*:role/RoleName",
"arn:aws:iam::111122223333:policy/*"
]
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": [
"cloudformation:CreateUploadBucket",
"cloudformation:DescribeStackDriftDetectionStatus",
"cloudformation:ListExports",
"cloudformation:ListStacks",
"cloudformation:ListImports",
"lambda:ListFunctions",
"iam:ListRoles",
"lambda:GetAccountSettings",
"ec2:DescribeSecurityGroups",
"cloudformation:EstimateTemplateCost",
"ec2:DescribeVpcs",
"lambda:ListEventSourceMappings",
"cloudformation:DescribeAccountLimits",
"ec2:DescribeSubnets",
"cloudformation:CreateStackSet",
"cloudformation:ValidateTemplate"
],
"Resource": "*"
},
{
"Sid": "VisualEditor2",
"Effect": "Allow",
"Action": "cloudformation:*",
"Resource": [
"arn:aws:cloudformation:*:111122223333:stack/aws-serverless-repository-MyCFStackPrefix*/*",
"arn:aws:cloudformation:*:111122223333:stack/serverlessrepo-MyCFStackPrefix*/*",
"arn:aws:cloudformation:*:*:transform/Serverless-*",
"arn:aws:cloudformation:*:111122223333:stackset/aws-serverless-repository-MyCFStackPrefix*:*",
"arn:aws:cloudformation:*:111122223333:stackset/serverlessrepo-MyCFStackPrefix*:*"
]
},
{
"Sid": "VisualEditor3",
"Effect": "Allow",
"Action": "serverlessrepo:*",
"Resource": "arn:aws:serverlessrepo:*:*:applications/*"
},
{
"Sid": "ECR",
"Effect": "Allow",
"Action": [
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer"
],
"Resource": "arn:aws:ecr:*:*:repository/*"
}
]
}
```
**許可說明**
| 允許的動作 | 說明 |
| --- | --- |
| "lambda:CreateFunction",
"lambda:ListVersionsByFunction",
"lambda:GetFunctionConfiguration",
"lambda:PutFunctionConcurrency",
"lambda:ListTags",
"lambda:DeleteFunction",
"lambda:GetAlias",
"lambda:InvokeFunction",
"lambda:GetFunction",
"lambda:ListAliases",
"lambda:UpdateFunctionConfiguration",
"lambda:UpdateFunctionCode",
"lambda:AddPermission",
"lambda:DeleteFunctionConcurrency",
"lambda:RemovePermission",
"lambda:GetPolicy"
"lambda:GetAccountSettings",
"lambda:ListFunctions",
"lambda:ListEventSourceMappings",
| 允許建立和管理列為資源的 Lambda 函數。在該範例中，資源識別碼 `arn:aws:lambda:*:MyAWSAcctId:function:MyAthenaLambdaFunctionsPrefix*` 中使用名稱字首，其中 *MyAthenaLambdaFunctionsPrefix* 是 Lambda 函數群組的名稱中使用的共同字首，因此不需要個別指定為資源。您可以指定一或多個 Lambda 函數資源。 |
| "s3:GetObject"
| 允許讀取資源識別符 所指定 AWS Serverless Application Repository 需要 的儲存貯體arn:aws:s3:::awsserverlessrepo-changesets-1iiv3xa62ln3m/\$1。 |
| "cloudformation:*"
| 允許建立和管理資源 *MyCFStackPrefix* 指定的 CloudFormation 堆疊。這些堆疊和堆疊集是部署連接器和 UDFs AWS Serverless Application Repository 的方式。 |
| "serverlessrepo:*"
| 允許搜尋、檢視、發佈和更新 中由資源識別符 AWS Serverless Application Repository指定的應用程式arn:aws:serverlessrepo:\$1:\$1:applications/\$1。 |
# 允許使用 Athena 存取機器學習
必須允許執行 Athena 機器學習 (ML) 查詢的 IAM 主體對其使用的 Sagemaker 端點執行 `sagemaker:invokeEndpoint` 動作。在連接至使用者身分的以身分為基礎的許可政策中，加入類似下列的政策陳述式。此外，請連接 [AWS 受管政策：AmazonAthenaFullAccess](security-iam-awsmanpol.md#amazonathenafullaccess-managed-policy)，以授權完整存取 Athena 動作，或連接已修改的內嵌政策，以允許動作子集。
在範例中，以要在查詢中使用的模型端點的一或多個 ARN，替換 `arn:aws:sagemaker:region:AWSAcctID:ModelEndpoint`。如需詳細資訊，請參閱*服務授權參考*中的 [SageMaker AI 的動作、資源和條件金鑰](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonsagemaker.html)。
```
{
"Effect": "Allow",
"Action": [
"sagemaker:invokeEndpoint"
],
"Resource": "arn:aws:sagemaker:us-west-2:123456789012:workteam/public-crowd/default"
}
```
每當您使用 IAM 政策時，請務必遵循 IAM 最佳實務。如需詳細資訊，請參閱*《IAM 使用者指南》*中的 [IAM 中的安全性最佳實務](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)。
# 啟用對 Athena API 的聯合存取
本節討論的聯合存取，可讓組織中的使用者或用戶端應用程式呼叫 Amazon Athena API 操作。在這種情況下，組織的使用者無法直接存取 Athena。反之，您可以在 Microsoft Active Directory AWS 中管理 外部的使用者登入資料。Active Directory 支援 [SAML 2.0](https://wiki.oasis-open.org/security) (安全聲明標記語言 2.0)。
若要在此案例中驗證使用者，請使用支援 SAML.2.0 的 JDBC 或 ODBC 驅動程式，以存取 Active Directory Federation Services (ADFS) 3.0，並讓用戶端應用程式能夠呼叫 Athena API 操作。
如需 上 SAML 2.0 支援的詳細資訊 AWS，請參閱《*IAM 使用者指南*》中的[關於 SAML 2.0 聯合](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_saml.html)。
**注意**
特定類型的身分提供者 (IdP)，即 Active Directory Federation Service (ADFS 3.0) (Windows Server 的一部分) 支援對 Athena API 的聯合存取。聯合存取與 IAM Identity Center 信任身分傳播功能不相容。透過支援 SAML 2.0 的 JDBC 或 ODBC 驅動程式版本建立存取權。如需詳細資訊，請參閱 [使用 JDBC 連接到 Amazon Athena](connect-with-jdbc.md) 及 [使用 ODBC 連接到 Amazon Athena](connect-with-odbc.md)。
**Topics**
+ [開始之前](#access-federation-before-you-begin)
+ [了解身分驗證程序](#access-federation-diagram)
+ [程序：啟用對 Athena API 的 SAML 型聯合存取](#access-federation-procedure)
## 開始之前
開始之前，請先完成以下先決條件：
+ 在您的組織內，安裝 ADFS 3.0 並將其設定為您的 IdP。
+ 在用來存取 Athena 的用戶端上，安裝和設定最新可用版本的 JDBC 或 ODBC 驅動程式。此驅動程式必須支援與 SAML 2.0 相容的聯合身分存取。如需詳細資訊，請參閱 [使用 JDBC 連接到 Amazon Athena](connect-with-jdbc.md) 及 [使用 ODBC 連接到 Amazon Athena](connect-with-odbc.md)。
## 了解身分驗證程序
下列圖表說明聯合存取 Athena API 的身分驗證程序。
![\[Athena API 的聯合存取圖表。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/athena-saml-based-federation.png)
1. 組織中的使用者會使用用戶端應用程式搭配 JDBC 或 ODBC 驅動程式，請求獲得組織 IdP 的身分驗證。IdP 是 ADFS 3.0。
1. IdP 根據 Active Directory (組織的身分存放區) 對使用者進行身分驗證。
1. IdP 會建構一個具有使用者相關資訊的 SAML 聲明，並將此聲明經由 JDBC 或 ODBC 驅動程式發送到用戶端應用程式。
1. JDBC 或 ODBC 驅動程式會呼叫 AWS Security Token Service [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) API 操作，並傳遞下列參數：
+ SAML 供應商的 ARN
+ 要擔任的角色 ARN
+ 來自 IdP 的 SAML 聲明
如需詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)。
1. API 透過 JDBC 或 ODBC 驅動程式傳給用戶端應用程式的回應，包含臨時安全登入資料。
1. 用戶端應用程式使用臨時安全憑證呼叫 Athena API 操作，讓您的使用者可以存取 Athena API 操作。
## 程序：啟用對 Athena API 的 SAML 型聯合存取
此程序會在組織的 IdP 和 AWS 您的帳戶之間建立信任，以啟用對 Amazon Athena API 操作的 SAML 型聯合存取。
**若要啟用對 Athena API 的聯合存取：**
1. 在您的組織中，在您的 IdP 中註冊 AWS 為服務提供者 (SP)。這個程序稱為*依賴方信任*。如需詳細資訊，請參閱《IAM 使用者指南》**中的[使用依賴方信任設定您的 SAML 2.0 IdP](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_relying-party.html)。請執行以下步驟，做為此任務的一部分：
1. 從這個 URL 取得範例 SAML 中繼資料文件：[https://signin.aws.amazon.com/static/saml-metadata.xml](https://signin.aws.amazon.com/static/saml-metadata.xml)。
1. 在您組織的 IdP (ADFS) 中， 會產生同等的中繼資料 XML 檔案，將 IdP 描述為身分提供者 AWS。您的中繼資料檔案必須包含發行者名稱、建立日期、過期日期，以及 AWS 用於驗證組織中身分驗證回應 （聲明） 的金鑰。
1. 在 IAM 主控台中，您可以建立一個 SAML 身分提供者實體。如需詳細資訊，請參閱《IAM 使用者指南》**中的[建立 SAML 身分提供者](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html)。執行以下操作，做為此步驟的一部分：
1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 上傳在本程序步驟 1 中 IdP (ADFS) 產生的 SAML 中繼資料文件。
1. 在 IAM 主控台中為您的 IdP 建立一或多個 IAM 角色。如需詳細資訊，請參閱《IAM 使用者指南》**中的[為第三方身分提供者 (聯合) 建立角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp.html)。執行以下操作，做為此步驟的一部分：
+ 在該角色的許可政策中，列出允許組織的使用者在 AWS中執行的動作。
+ 在角色的信任政策中，將您在此程序步驟 2 中建立的 SAML 提供者實體設定為主體。
這會在您的組織與 之間建立信任關係 AWS。
1. 在組織的 IdP (ADFS) 中，定義可將組織中的使用者或群組映射到 IAM 角色的聲明。使用者和群組對 IAM 角色的映射也稱為*宣告規則*。請注意，組織中不同的使用者和群組可能映射到不同的 IAM 角色。
如需有關在 ADFS 中設定映射的資訊，請參閱部落格文章：[AWS 使用 Windows Active Directory、ADFS 和 SAML 2.0 啟用 的聯合。](https://aws.amazon.com/blogs/security/enabling-federation-to-aws-using-windows-active-directory-adfs-and-saml-2-0/)
1. 安裝並設定具 SAML 2.0 支援的 JDBC 和 ODBC 驅動程式。如需詳細資訊，請參閱 [使用 JDBC 連接到 Amazon Athena](connect-with-jdbc.md) 及 [使用 ODBC 連接到 Amazon Athena](connect-with-odbc.md)。
1. 指定從您的應用程式到 JDBC 和 ODBC 驅動程式的連接字串。如需有關應用程式應使用之連線字串的資訊，請參閱《JDBC 驅動器安裝和設定指南**》中的*「使用 Active Directory Federation Services (ADFS) 憑證提供者」*，或《ODBC 驅動器安裝和設定指南**》中的類似主題，可透過 PDF 形式從 [使用 JDBC 連接到 Amazon Athena](connect-with-jdbc.md) 和 [使用 ODBC 連接到 Amazon Athena](connect-with-odbc.md) 主題中下載。
以下是設定驅動程式連接字串的高階彙總：
1. 在 `AwsCredentialsProviderClass configuration` 中，設定 `com.simba.athena.iamsupport.plugin.AdfsCredentialsProvider` 以表示您想要透過 ADFS IdP 使用的 SAML 2.0 身分驗證。
1. 在 `idp_host` 提供 ADFS IdP 伺服器的主機名稱。
1. 在 `idp_port` 提供 ADFS IdP 監聽 SAML 聲明請求的連接埠號碼。
1. 在 `UID` 和 `PWD` 提供 AD 網域使用者登入資料。在 Windows 上使用驅動程式時，若未提供 `UID` 和 `PWD`，驅動程式會嘗試取得登入該 Windows 機器之使用者的使用者登入資料。
1. 您可以選擇將 `ssl_insecure` 設定為 `true`。在這種情況下，驅動程式不會檢查 ADFS IdP 伺服器的 SSL 憑證真偽。如果未將 ADFS IdP 的 SSL 憑證設定為受驅動程式信任，則必須設定為 `true`。
1. 若要啟用 Active Directory 網域使用者或群組到一個或多個 IAM 角色的映射 (如本程式庫步驟 4 中所述)，在 JDBC 或 ODBC 連接的 `preferred_role` 中，指定驅動程式連接中要擔任的 IAM 角色 (ARN)。指定 `preferred_role` 為選擇性，但如果角色不是宣告規則中列出的第一個角色，則非常有用。
由於此程序，發生下列動作：
1. JDBC 或 ODBC 驅動程式會呼叫 AWS STS [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) API，並傳遞宣告，如[架構圖](#access-federation-diagram)的步驟 4 所示。
1. AWS 會確保擔任角色的請求來自 SAML 提供者實體中參考的 IdP。
1. 如果請求成功， AWS STS [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) API 操作會傳回一組臨時安全登入資料，您的用戶端應用程式會使用此登入資料向 Athena 提出已簽署的請求。
您的應用程式現在已具有目前使用者相關資訊，且能以程式設計的方式存取 Athena。
# 記錄並監控 Athena
若要偵測事件，在事件發生時收到提醒，以及回應它們，請搭配 Amazon Athena 使用這些選項：
+ **使用 監控 Athena AWS CloudTrail** – [AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)提供使用者、角色或 Athena AWS 服務 中 所採取動作的記錄。其會從 Athena 主控台擷取呼叫，並將 Athena API 操作的呼叫編碼為事件。其允許您判斷向 Athena 提出的請求、提出請求的 IP 地址、提出請求的人員、提出請求的時間，以及其他詳細資訊。如需詳細資訊，請參閱[使用 記錄 Amazon Athena API 呼叫 AWS CloudTrail](monitor-with-cloudtrail.md)。
您也可以使用 Athena 查詢 Athena 和其他 AWS 服務的 CloudTrail 日誌檔案。如需詳細資訊，請參閱[查詢 AWS CloudTrail 日誌](cloudtrail-logs.md)。
+ **使用 CloudTrail 和 Amazon Quick 監控 Athena 使用情況** – [Amazon Quick](https://aws.amazon.com/quicksight/) 是一項全受管、雲端驅動的商業智慧服務，可讓您建立互動式儀表板，讓您的組織可以從任何裝置存取。如需使用 CloudTrail 和 Amazon Quick 監控 Athena 用量的解決方案範例，請參閱 AWS 大數據部落格文章 [Realtor.com 如何使用 AWS CloudTrail 和 Quick 監控 Amazon Athena 用量](https://aws.amazon.com/blogs/big-data/analyzing-amazon-athena-usage-by-teams-within-a-real-estate-company/)。
+ **搭配 Athena 使用 EventBridge ** – Amazon EventBridge 提供近乎即時的系統事件串流，說明 AWS 資源的變更。EventBridge 會察覺這些操作變更的發生，回應它們並視需要採取更正動作，方法為傳送訊息來回應環境、啟用功能、執行變更和擷取狀態資訊。盡可能發出事件。如需詳細資訊，請參閱 *《Amazon EventBridge 使用者指南》*中的 [Amazon EventBridge 入門](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html)。
+ **使用工作群組來區隔使用者、團隊、應用程式或工作負載，以及設定查詢限制並控制查詢成本** - 您可以檢視 Amazon CloudWatch 中的查詢相關指標，對掃描的資料量設定限制來控制查詢成本，建立閾值，以及在超過這些閾值時觸發動作，例如 Amazon SNS 警示。如需詳細資訊，請參閱[使用工作群組來控制查詢存取和成本](workgroups-manage-queries-control-costs.md)。使用資源層級 IAM 許可來控制特定群組的存取。如需詳細資訊，請參閱[使用 IAM 政策來控制工作群組存取](workgroups-iam-policy.md)及[使用 CloudWatch 和 EventBridge 來監控查詢和控制成本](workgroups-control-limits.md)。
**Topics**
+ [使用 記錄 Amazon Athena API 呼叫 AWS CloudTrail](monitor-with-cloudtrail.md)
# 使用 記錄 Amazon Athena API 呼叫 AWS CloudTrail
Athena 已與 整合 AWS CloudTrail，此服務提供 Athena AWS 服務 中使用者、角色或 所採取動作的記錄。
CloudTrail 會擷取 Athena 的 API 呼叫當作事件。擷取的呼叫包括從 Athena 主控台進行的呼叫，以及針對 Athena API 操作的程式碼呼叫。如果您建立線索，就可以將 CloudTrail 事件持續交付到 Amazon S3 儲存貯體，包括 Athena 的事件。即使您未設定線索，依然可以透過 CloudTrail 主控台中的 **Event history ** (事件歷史記錄) 檢視最新事件。
您可以利用 CloudTrail 所收集的資訊來判斷向 Athena 發出的請求，以及發出請求的 IP 地址、人員、時間和其他詳細資訊。
若要進一步了解 CloudTrail，請參閱[《AWS CloudTrail 使用者指南》](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)。
您可以使用 Athena 從 Athena 本身和其他 查詢 CloudTrail 日誌檔案 AWS 服務。如需詳細資訊，請參閱 [查詢 AWS CloudTrail 日誌](cloudtrail-logs.md)、 [Hive JSON SerDe](hive-json-serde.md)和 AWS 大數據部落格文章 [使用 CTAS 陳述式搭配 Amazon Athena 來降低成本和改善效能](https://aws.amazon.com/blogs/big-data/using-ctas-statements-with-amazon-athena-to-reduce-cost-and-improve-performance/)，這會使用 CloudTrail 來深入了解 Athena 用量。
## 關於 CloudTrail 中的 Athena 資訊
在您建立帳戶時，系統即會在 Amazon Web Services 帳戶中啟用 CloudTrail。當活動發生於 Athena 中時，系統便會將該活動記錄於 CloudTrail 事件中，並將其他 AWS 服務事件記錄至 **Event history** (事件歷史記錄) 中。您可以檢視、搜尋和下載 Amazon Web Services 帳戶中的最近事件。如需詳細資訊，請參閱[使用 CloudTrail 事件歷史記錄檢視事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html)。
如需 Amazon Web Services 帳戶中正在進行事件的記錄 (包含 Athena 的事件)，請建立線索。*線索*能讓 CloudTrail 將日誌檔案交付至 Amazon S3 儲存貯體。依預設，當您在主控台中建立追蹤時，該追蹤會套用至所有的 AWS 區域。線索會記錄 AWS 分割區中所有區域的事件，並將日誌檔案傳送到您指定的 Amazon S3 儲存貯體。此外，您可以設定其他 AWS 服務 來進一步分析和處理 CloudTrail 日誌中收集的事件資料。如需詳細資訊，請參閱下列內容：
+ [建立追蹤的概觀](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)
+ [CloudTrail 支援的服務和整合](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations)
+ [設定 CloudTrail 的 Amazon SNS 通知](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html)
+ [接收多個區域的 CloudTrail 日誌檔案](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html)和[接收多個帳戶的 CloudTrail 日誌檔案](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html)
所有 Athena 動作都由 CloudTrail 記錄，並以文件載明於 [Amazon Athena API 參考](https://docs.aws.amazon.com/athena/latest/APIReference/)中。例如，對 [StartQueryExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartQueryExecution.html) 和 [GetQueryResults](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartQueryExecution.html) 動作的呼叫會在 CloudTrail 日誌檔案中產生相關項目。
每一筆事件或日誌專案都會包含產生請求者的資訊。身分資訊可協助您判斷下列事項：
+ 是否使用根或 AWS Identity and Access Management (IAM) 使用者登入資料提出請求。
+ 提出該請求時，是否使用了特定角色或聯合身分使用者的暫時安全憑證。
+ 該請求是否由另一項 AWS 服務服務提出。
如需詳細資訊，請參閱 [CloudTrail userIdentity 元素](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)。
## 了解 Athena 日誌檔案項目
追蹤是一種組態，能讓事件以日誌檔案的形式交付到您指定的 Amazon S3 儲存貯體。CloudTrail 日誌檔案包含一或多個日誌專案。一個事件為任何來源提出的單一請求，並包含請求動作、請求的日期和時間、請求參數等資訊。CloudTrail 日誌檔並非依公有 API 呼叫的堆疊追蹤排序，因此不會以任何特定順序出現。
**注意**
為了防止意外揭露敏感資訊，`StartQueryExecution` 和 `CreateNamedQuery` 日誌中的 `queryString` 項目的值都為 `***OMITTED***`。這是設計本身所致。若要存取實際的查詢字串，您可以使用 Athena [GetQueryExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetQueryExecution.html) API，並從 CloudTrail 日誌傳入 `responseElements.queryExecutionId` 的值。
以下範例會示範個別 CloudTrail 日誌項目：
+ [StartQueryExecution (Successful)](#startqueryexecution-successful)
+ [StartQueryExecution (Failed)](#startqueryexecution-failed)
+ [CreateNamedQuery](#createnamedquery)
### StartQueryExecution (successful)
```
{
"eventVersion":"1.05",
"userIdentity":{
"type":"IAMUser",
"principalId":"EXAMPLE_PRINCIPAL_ID",
"arn":"arn:aws:iam::123456789012:user/johndoe",
"accountId":"123456789012",
"accessKeyId":"EXAMPLE_KEY_ID",
"userName":"johndoe"
},
"eventTime":"2017-05-04T00:23:55Z",
"eventSource":"athena.amazonaws.com",
"eventName":"StartQueryExecution",
"awsRegion":"us-east-1",
"sourceIPAddress":"77.88.999.69",
"userAgent":"aws-internal/3",
"requestParameters":{
"clientRequestToken":"16bc6e70-f972-4260-b18a-db1b623cb35c",
"resultConfiguration":{
"outputLocation":"s3://amzn-s3-demo-bucket/test/"
},
"queryString":"***OMITTED***"
},
"responseElements":{
"queryExecutionId":"b621c254-74e0-48e3-9630-78ed857782f9"
},
"requestID":"f5039b01-305f-11e7-b146-c3fc56a7dc7a",
"eventID":"c97cf8c8-6112-467a-8777-53bb38f83fd5",
"eventType":"AwsApiCall",
"recipientAccountId":"123456789012"
}
```
### StartQueryExecution (failed)
```
{
"eventVersion":"1.05",
"userIdentity":{
"type":"IAMUser",
"principalId":"EXAMPLE_PRINCIPAL_ID",
"arn":"arn:aws:iam::123456789012:user/johndoe",
"accountId":"123456789012",
"accessKeyId":"EXAMPLE_KEY_ID",
"userName":"johndoe"
},
"eventTime":"2017-05-04T00:21:57Z",
"eventSource":"athena.amazonaws.com",
"eventName":"StartQueryExecution",
"awsRegion":"us-east-1",
"sourceIPAddress":"77.88.999.69",
"userAgent":"aws-internal/3",
"errorCode":"InvalidRequestException",
"errorMessage":"Invalid result configuration. Should specify either output location or result configuration",
"requestParameters":{
"clientRequestToken":"ca0e965f-d6d8-4277-8257-814a57f57446",
"queryString":"***OMITTED***"
},
"responseElements":null,
"requestID":"aefbc057-305f-11e7-9f39-bbc56d5d161e",
"eventID":"6e1fc69b-d076-477e-8dec-024ee51488c4",
"eventType":"AwsApiCall",
"recipientAccountId":"123456789012"
}
```
### CreateNamedQuery
```
{
"eventVersion":"1.05",
"userIdentity":{
"type":"IAMUser",
"principalId":"EXAMPLE_PRINCIPAL_ID",
"arn":"arn:aws:iam::123456789012:user/johndoe",
"accountId":"123456789012",
"accessKeyId":"EXAMPLE_KEY_ID",
"userName":"johndoe"
},
"eventTime":"2017-05-16T22:00:58Z",
"eventSource":"athena.amazonaws.com",
"eventName":"CreateNamedQuery",
"awsRegion":"us-west-2",
"sourceIPAddress":"77.88.999.69",
"userAgent":"aws-cli/1.11.85 Python/2.7.10 Darwin/16.6.0 botocore/1.5.48",
"requestParameters":{
"name":"johndoetest",
"queryString":"***OMITTED***",
"database":"default",
"clientRequestToken":"fc1ad880-69ee-4df0-bb0f-1770d9a539b1"
},
"responseElements":{
"namedQueryId":"cdd0fe29-4787-4263-9188-a9c8db29f2d6"
},
"requestID":"2487dd96-3a83-11e7-8f67-c9de5ac76512",
"eventID":"15e3d3b5-6c3b-4c7c-bc0b-36a8dd95227b",
"eventType":"AwsApiCall",
"recipientAccountId":"123456789012"
},
```
# 的合規驗證
在多個合規計畫中，第三方稽核人員會評估 的安全與 AWS 合規。這些計劃包括 SOC、PCI、FedRAMP 等等。
如需特定合規計劃 AWS 服務 範圍內的 清單，請參閱[AWS 服務 合規計劃範圍內](https://aws.amazon.com/compliance/services-in-scope/)的 。如需一般資訊，請參閱 [AWS 合規計劃](https://aws.amazon.com/compliance/programs/)。
您可以使用 下載第三方稽核報告 AWS Artifact。如需詳細資訊，請參閱[在 中下載報告 AWS Artifact](https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html)。
您使用 時的合規責任取決於資料的機密性、您公司的合規目標，以及適用的法律和法規。 AWS 提供下列資源來協助合規：
+ [安全與合規快速入門指南](https://aws.amazon.com/quickstart/?awsf.quickstart-homepage-filter=categories%23security-identity-compliance) – 這些部署指南討論架構考量，並提供在其中部署以安全與合規為重心的基準環境的步驟 AWS。
+ [Amazon Web Services 上的 HIPAA 安全與合規架構](https://docs.aws.amazon.com/whitepapers/latest/architecting-hipaa-security-and-compliance-on-aws/architecting-hipaa-security-and-compliance-on-aws.html) – 本白皮書說明公司如何使用 AWS 來建立符合 HIPAA 規範的應用程式。
+ [AWS 合規資源](https://aws.amazon.com/compliance/resources/) – 此工作手冊和指南集合可能適用於您的產業和位置。
+ [AWS Config](https://docs.aws.amazon.com/config/latest/developerguide/evaluate-config.html) – 這會 AWS 服務 評估您的資源組態符合內部實務、產業準則和法規的程度。
+ [AWS Security Hub CSPM](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html) – 這 AWS 服務 可讓您全面檢視 內的安全狀態 AWS ，協助您檢查是否符合安全產業標準和最佳實務。
# Athena 中的復原功能
AWS 全球基礎設施是以 AWS 區域 和 可用區域為基礎建置。 AWS 區域 提供多個實體隔離和隔離的可用區域，這些可用區域與低延遲、高輸送量和高備援聯網連接。透過可用區域，您所設計與操作的應用程式和資料庫，就能夠在可用區域之間自動容錯移轉，而不會發生中斷。可用區域的可用性、容錯能力和擴充能力，均較單一或多個資料中心的傳統基礎設施還高。
如需 AWS 區域 和可用區域的詳細資訊，請參閱 [AWS 全球基礎設施](https://aws.amazon.com/about-aws/global-infrastructure/)。
除了 AWS 全球基礎設施之外， 還提供數種功能，以協助支援您的資料彈性和備份需求。
Athena 為無伺服器，無須設定或管理任何基礎設施。Athena 具有高可用性，並跨多個可用區域使用運算資源來執行查詢，如果無法連線特定可用區域，便會自動適當地路由查詢。Athena 會使用 Amazon S3 作為其基礎資料存放區，讓您的資料具有高可用性和耐用性。Amazon S3 會提供耐用的基礎設施來存放重要資料，其旨在提供 99.999999999% 的物件耐用性。您的資料會以冗餘方式存放在多個設施以及每個設施的多個裝置。
# Athena 中的基礎設施安全
作為受管服務， 受到 AWS 全球網路安全的保護。如需 AWS 安全服務以及如何 AWS 保護基礎設施的資訊，請參閱[AWS 雲端安全](https://aws.amazon.com/security/)。若要使用基礎設施安全的最佳實務來設計您的 AWS 環境，請參閱*安全支柱 AWS Well-Architected Framework* 中的[基礎設施保護](https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/infrastructure-protection.html)。
您可以使用 AWS 發佈的 API 呼叫，透過網路存取 。使用者端必須支援下列專案：
+ Transport Layer Security (TLS)。我們需要 TLS 1.2 並建議使用 TLS 1.3。
+ 具備完美轉送私密(PFS)的密碼套件，例如 DHE (Ephemeral Diffie-Hellman)或 ECDHE (Elliptic Curve Ephemeral Diffie-Hellman)。現代系統(如 Java 7 和更新版本)大多會支援這些模式。
使用 IAM 政策來限制對 Athena 操作的存取。每當您使用 IAM 政策時，請務必遵循 IAM 最佳實務。如需詳細資訊，請參閱*《IAM 使用者指南》*中的 [IAM 中的安全性最佳實務](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)。
Athena [受管政策](security-iam-awsmanpol.md)不但易於使用，且會隨著服務的演進以所需動作自動更新。客戶受管政策和內嵌政策允許您透過在政策內指定更精密的 Athena 動作來微調這些政策。授予對資料的 Amazon S3 位置之適當存取權。如需有關如何授予 Amazon S3 存取權的詳細資訊和案例，請參閱《Amazon Simple Storage Service 開發人員指南》**中的[演練範例：管理存取權](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-walkthroughs-managing-access.html)。如需詳細資訊以及允許哪些 Amazon S3 動作的範例，請參閱[跨帳戶存取](cross-account-permissions.md)中的儲存貯體政策範例。
**Topics**
+ [使用界面 VPC 端點連接至 Amazon Athena](interface-vpc-endpoint.md)
# 使用界面 VPC 端點連接至 Amazon Athena
在虛擬私有雲端 (VPC) 中使用[介面 VPC 端點 (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html) 和 [AWS Glue VPC 端點](https://docs.aws.amazon.com/glue/latest/dg/vpc-endpoint.html)，改善 VPC 的安全狀態。介面 VPC 端點可讓您控制從 VPC 內部到達哪些目的地，從而提高安全性。每個 VPC 端點皆會由一個或多個具私有 IP 地址[彈性網路介面](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) (ENI) 來表示，而該介面位於 VPC 子網路中。
介面 VPC 端點會將您的 VPC 直接連接到 Athena，無需網際網路閘道、NAT 裝置、VPN 連接或 Direct Connect 連線。VPC 中的執行個體不需要公有 IP 地址，就能與 Athena API 進行通訊。
若要透過 VPC 來使用 Athena，您必須從 VPC 中的執行個體來連接，或使用 Amazon Virtual Private Network (VPN) 或 Direct Connect將私有網路連接至 VPC。如需有關 Amazon VPN 的資訊，請參閱《Amazon Virtual Private Cloud 使用者指南》**中的 [VPN 連接](https://docs.aws.amazon.com/vpc/latest/userguide/vpn-connections.html)。如需 的詳細資訊 AWS Direct Connect，請參閱*Direct Connect 《 使用者指南*》中的[建立連線](https://docs.aws.amazon.com/directconnect/latest/UserGuide/create-connection.html)。
Athena 在所有提供 Amazon VPC 和 [Athena](https://docs.aws.amazon.com/general/latest/gr/rande.html#athena) AWS 區域 的所有 中都支援 VPC 端點。 [https://docs.aws.amazon.com/general/latest/gr/rande.html#vpc_region](https://docs.aws.amazon.com/general/latest/gr/rande.html#vpc_region)
您可以使用 AWS 管理主控台 或 AWS Command Line Interface (AWS CLI) 命令建立介面 VPC 端點以連線至 Athena。如需詳細資訊，請參閱[建立介面端點](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#create-interface-endpoint)。
在建立界面 VPC 端點之後，如果您啟用端點的[私有 DNS](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#vpce-private-dns) 主機名稱，則預設 Athena 端點 (https://athena.*Region*.amazonaws.com) 會解析為您的 VPC 端點。
如果您尚未啟用私有 DNS 主機名稱，Amazon VPC 會透過以下格式提供一個 DNS 端點名稱，供您使用：
```
VPC_Endpoint_ID.athena.Region.vpce.amazonaws.com
```
如需詳細資訊，請參閱*《Amazon VPC 使用者指南》*中的 [介面 VPC 端點 (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html)。
Athena 會支援在您的 VPC 內呼叫其所有 [API 動作](https://docs.aws.amazon.com/athena/latest/APIReference/API_Operations.html)。
## 為 Athena 建立 VPC 端點政策
您可以為 Athena 的 Amazon VPC 端點建立政策，以指定下列限制：
+ **主體** – 可執行動作的主體。
+ **動作** – 可執行的動作。
+ **資源** – 可供執行動作的資源。
+ **僅受信任的身分** – 使用 `aws:PrincipalOrgId`條件來限制僅存取屬於您 AWS 組織一部分的登入資料。這有助於防止非預期的主體存取。
+ **僅可信資源** – 使用 `aws:ResourceOrgId` 條件，以防止存取非預期的資源。
+ **僅可信身分和資源** – 為 VPC 端點建立組合政策，以協助防止存取非預期的主體和資源。
如需詳細資訊，請參閱《*Amazon* [VPC 使用者指南》中的使用 VPC 端點控制對服務的存取](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-access.html)，以及 AWS 《白皮書*建置資料周邊 AWS*》中的[附錄 2 – VPC 端點政策範例](https://docs.aws.amazon.com/whitepapers/latest/building-a-data-perimeter-on-aws/appendix-2-vpc-endpoint-policy-examples.html)。
**Example – VPC 端點政策**
下列範例允許組織身分對組織資源的請求，並允許 AWS 服務主體的請求。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowRequestsByOrgsIdentitiesToOrgsResources",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "*",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:PrincipalOrgID": "my-org-id",
"aws:ResourceOrgID": "my-org-id"
}
}
},
{
"Sid": "AllowRequestsByAWSServicePrincipals",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "*",
"Resource": "*",
"Condition": {
"Bool": {
"aws:PrincipalIsAWSService": "true"
}
}
}
]
}
```
每當您使用 IAM 政策時，請務必遵循 IAM 最佳實務。如需詳細資訊，請參閱《IAM 使用者指南》**中的 [IAM 中的安全性最佳實務](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)。
## 關於共用子網路中的 VPC 端點
無法在與您共用的子網路中建立、描述、修改或刪除 VPC 端點。不過，可以在與您共用的子網路中使用 VPC 端點。如需有關 VPC 子網路共用的資訊，請參閱《*Amazon VPC 使用者指南*》中的[與其他帳戶共用 VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-sharing.html)。
# Athena 中的組態與漏洞分析
Athena 是無伺服器，因此沒有可設定或管理的基礎設施。 會 AWS 處理基本安全任務，例如訪客作業系統 (OS) 和資料庫修補、防火牆組態和災難復原。這些程序已由適當的第三方進行檢閱並認證。如需詳細資訊，請參閱下列 AWS資源：
+ [共同的責任模型](https://aws.amazon.com/compliance/shared-responsibility-model/)
+ [安全性、身分與合規的最佳實務](https://aws.amazon.com/architecture/security-identity-compliance/)
# 使用 Athena 查詢向 註冊的資料 AWS Lake Formation
[AWS Lake Formation](https://docs.aws.amazon.com/lake-formation/latest/dg/what-is-lake-formation.html) 可讓您在使用 Athena 查詢來讀取存放在 Amazon S3 中的資料或透過聯合資料來源存取時，定義並強制執行資料庫、資料表和資料欄層級存取政策。Lake Formation 會針對存放在 Amazon S3 或聯合資料目錄中的資料提供授權和控管層。您可以使用 Lake Formation 中的許可階層來授予或撤銷讀取資料目錄物件 (例如資料庫、資料表和資料欄) 的許可。Lake Formation 可簡化許可的管理，並讓您實作資料的精細定義存取控制 (FGAC)。
您可以使用 Athena 查詢向 Lake Formation 註冊的資料，以及未向 Lake Formation 註冊的資料。
使用 Athena 查詢已向 Lake Formation 註冊之 Amazon S3 位置或資料目錄的來源資料時，Lake Formation 許可即適用。當您建立指向已註冊 Amazon S3 資料位置或資料目錄的資料庫和資料表時，Lake Formation 許可也適用。
寫入物件時，Lake Formation 許可不適用，也不適用於查詢未向 Lake Formation 註冊的資料或中繼資料時。對於未向 Lake Formation 註冊的來源資料和中繼資料，存取權取決於 IAM 許可政策和 AWS Glue 動作。Simple Storage Service (Amazon S3) 中的 Athena 查詢結果位置無法向 Lake Formation 註冊，且 Simple Storage Service (Amazon S3) 的 IAM 許可政策控制存取權限。此外，Lake Formation 許可不適用於 Athena 查詢歷史記錄。您可以使用 Athena 工作群組來控制查詢歷史記錄的存取。
如需有關 Lake Formation 的詳細資訊，請參閱 [Lake Formation 常見問答集](https://aws.amazon.com/lake-formation/faqs/)與《[AWS Lake Formation 開發人員指南](https://docs.aws.amazon.com/lake-formation/latest/dg/what-is-lake-formation.html)》。
## 將 Lake Formation 許可套用至現有資料庫和資料表
如果您是初次使用 Athena，且使用 Lake Formation 設定對查詢資料的存取，則不需要設定 IAM 政策以讓使用者能夠讀取資料和建立中繼資料。您可以使用 Lake Formation 來管理許可。
不需要向 Lake Formation 註冊資料和更新 IAM 許可政策。如果資料未向 Lake Formation 註冊，則擁有適當許可的 Athena 使用者可以繼續查詢未向 Lake Formation 註冊的資料。
如果您有現有的 Athena 使用者查詢未向 Lake Formation 註冊的 Amazon S3 資料，您可以更新 Amazon S3 和 的 IAM 許可 AWS Glue Data Catalog，如果適用的話，以便您可以使用 Lake Formation 許可集中管理使用者存取。對於讀取 Simple Storage Service (Amazon S3) 資料位置的許可，您可更新以資源和以身分為基礎的政策，來修改 Simple Storage Service (Amazon S3) 許可。對於中繼資料的存取，如果您使用 設定了精細存取控制的資源層級政策 AWS Glue，則可以改用 Lake Formation 許可來管理存取。
如需詳細資訊，請參閱《 *AWS Lake Formation 開發人員指南*》中的將資料許可[在 中設定資料庫和資料表的存取權 AWS Glue Data Catalog](fine-grained-access-to-glue-resources.md)升級到模型。 [AWS GlueAWS Lake Formation](https://docs.aws.amazon.com/lake-formation/latest/dg/upgrade-glue-lake-formation.html)
**Topics**
+ [將 Lake Formation 許可套用至現有資料庫和資料表](#lf-athena-apply-lf-permissions-to-existing-databases-and-tables)
+ [資料存取的運作方式](lf-athena-access.md)
+ [考量和限制](lf-athena-limitations.md)
+ [跨帳戶存取權](lf-athena-limitations-cross-account.md)
+ [管理使用者許可](lf-athena-user-permissions.md)
+ [使用 Lake Formation 和 JDBC 或 ODBC 進行聯合存取](security-athena-lake-formation-jdbc.md)
# Athena 如何存取向 Lake Formation 註冊的資料
本節所述的存取工作流程適用於在 Amazon S3 位置、資料目錄或針對向 Lake Formation 註冊的中繼資料物件執行 Athena 查詢時。如需詳細資訊，請參閱《AWS Lake Formation 開發人員指南》**中的[註冊資料湖](https://docs.aws.amazon.com/lake-formation/latest/dg/register-data-lake.html)。除了註冊資料之外，Lake Formation 管理員還會套用 Lake Formation 許可，以授予或撤銷對資料目錄中中繼資料 AWS Glue Data Catalog或 Amazon S3 中資料位置的存取權。如需詳細資訊，請參閱《AWS Lake Formation 開發人員指南》**中的[中繼資料與資料的安全性與存取控制](https://docs.aws.amazon.com/lake-formation/latest/dg/security-data-access.html#security-data-access-permissions)。
每當 Athena 主體 (使用者、群組或角色) 對使用 Lake Formation 註冊的資料執行查詢時，Lake Formation 都會驗證主體是否有適合查詢的資料庫、資料表和資料來源位置的適當 Lake Formation 許可。如果主體有權存取，Lake Formation 會將暫時性憑證*提供*給 Athena，且查詢會執行。
下圖顯示憑證販售如何在 Athena 中以逐次查詢為基礎運作，以便對 Lake Formation 中註冊之 Amazon S3 位置或資料目錄的資料表進行假設的 `SELECT` 查詢：
![\[Athena 資料表上的查詢的憑證販賣工作流程。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/lake-formation-athena-security.png)
1. 主體在 Athena 中執行 `SELECT` 查詢。
1. Athena 會分析查詢並檢查 Lake Formation 許可，以查看是否授予主體對資料表和資料欄的存取權。
1. 如果主體有權存取，則 Athena 會向 Lake Formation 請求憑證。如果主體*沒有*存取權，Athena 會發出存取遭拒錯誤。
1. Lake Formation 會在從 Amazon S3 或目錄讀取資料時發出憑證給 Athena，也會發出允許的資料欄之清單。
1. Athena 使用 Lake Formation 臨時憑證來查詢來自 Amazon S3 或目錄的資料。查詢完成後，Athena 會捨棄憑證。
# 查詢向 Lake Formation 註冊之資料的考量事項與限制
使用 Athena 查詢在 Lake Formation 中註冊的資料時請考慮以下項目。如需其他資訊，請參閱《AWS Lake Formation 開發人員指南》**中的 [AWS Lake Formation的已知問題](https://docs.aws.amazon.com/lake-formation/latest/dg/limitations.html)。
**Topics**
+ [在某些情況下，沒有資料欄資料許可的使用者可以看見資料欄中繼資料](#lf-athena-limitations-column-metadata)
+ [使用檢視的 Lake Formation 許可](#lf-athena-limitations-permissions-to-views)
+ [Iceberg DDL 支援](#lf-athena-limitations-iceberg-ddl-operations)
+ [Lake Formation 精細存取控制和 Athena 工作群組](#lf-athena-limitations-fine-grained-access-control)
+ [Amazon S3 中的 Athena 查詢結果位置未向 Lake Formation 註冊](#lf-athena-limitations-query-results-location)
+ [使用 Athena 工作群組限制查詢歷史記錄的存取](#lf-athena-limitations-use-workgroups-to-limit-access-to-query-history)
+ [無法在 Athena 中查詢向 Lake Formation 註冊的 CSE-KMS Amazon S3](#lf-athena-limitations-cse-kms)
+ [向 Lake Formation 註冊的分割資料位置必須位於資料表子目錄中](#lf-athena-limitations-partioned-data-locations)
+ [Create Table As Select (CTAS) 查詢需要 Amazon S3 寫入許可](#lf-athena-limitations-ctas-queries)
+ [預設資料庫需要 DESCRIBE 許可](#lf-athena-limitations-describe-default)
## 在某些情況下，未經授權的使用者利用 Avro 和自訂 SerDe 可以看見資料欄中繼資料
Lake Formation 資料欄層級授權可防止沒有 Lake Formation 許可的使用者存取資料欄中的資料。不過，在某些情況下，使用者可以存取描述資料表中所有資料欄的中繼資料，包括他們沒有資料許可的資料欄。
此情形會在資料欄中繼資料存放在資料表的資料表屬性中時發生，使用 Apache Avro 儲存格式或使用自訂序列化程式/還原序列化程式 (SerDe)，其中資料表結構描述與 SerDe 定義已一併在資料表屬性中定義。搭配 Lake Formation 使用 Athena 時，我們建議您檢閱向 Lake Formation 註冊的資料表屬性內容，並盡可能限制資料表屬性中所存放的資訊，以防止使用者看到任何敏感中繼資料。
## 了解 Lake Formation 和視觀表
對於向 Lake Formation 註冊的資料，Athena 使用者只有在擁有資料表、資料欄，以及來源 Simple Storage Service (Amazon S3) 資料位置 (此為 `VIEW` 之根據) 之 Lake Formation 許可時，才能建立 `VIEW`。在 Athena 中建立 `VIEW` 之後，Lake Formation 許可即可套用至 `VIEW`。資料欄層級許可不適用於 `VIEW`。具有 `VIEW` 的 Lake Formation 許可，但沒有資料表和資料欄許可 (此為檢視之根據) 的使用者，無法使用 `VIEW` 來查詢資料。不過，具有此混合許可的使用者可以使用陳述式 (例如 `DESCRIBE VIEW`、`SHOW CREATE VIEW` 和 `SHOW COLUMNS`) 來查看 `VIEW` 中繼資料。因此，請務必針對每個 `VIEW` 調整 Lake Formation 許可以符合基礎資料表的許可。在資料表中定義的儲存格篩選條件不適用於針對該資料表的 `VIEW`。資源連結名稱必須與原始帳戶中的資源名稱相同。在跨帳戶設定中使用檢視時，還會有其他限制。如需有關設定跨帳戶的共用視圖的許可的詳細資訊，請參閱[設定跨帳戶 Data Catalog 存取權](lf-athena-limitations-cross-account.md)。
## Iceberg DDL 支援
Athena 目前不支援位置已向 Lake Formation 註冊的 Iceberg 資料表執行 DDL 操作。嘗試對其中一個 Iceberg 資料表執行 DDL 查詢可能會傳回 Amazon S3 存取遭拒錯誤，或因查詢逾時失敗。Iceberg 資料表上的 DDL 操作要求使用者擁有對 Iceberg 資料表位置的直接 Amazon S3 存取權。
## Lake Formation 精細存取控制和 Athena 工作群組
同一 Athena 工作群組中的使用者可以看到 Lake Formation 精細存取控制設定為可供工作群組存取的資料。如需有關在 Lake Formation 中使用精細定義存取控制的詳細資訊，請參閱 *AWS 大數據部落格*中的[使用 AWS Lake Formation管理精細定義存取控制](https://aws.amazon.com/blogs/big-data/manage-fine-grained-access-control-using-aws-lake-formation/)。
## Amazon S3 中的 Athena 查詢結果位置未向 Lake Formation 註冊
Simple Storage Service (Amazon S3) 中的 Athena 查詢結果無法向 Lake Formation 註冊。Lake Formation 許可不會限制對這些位置的存取。除非您限制存取，否則 Athena 使用者可以在沒有 Lake Formation 的資料許可時存取查詢結果檔案和中繼資料。若要避免這種情況，我們建議您使用工作群組來指定查詢結果的位置，並使工作群組成員資格與 Lake Formation 許可保持一致。然後，您可以使用 IAM 許可政策來限制查詢結果位置的存取。如需有關查詢結果的詳細資訊，請參閱[使用查詢結果和近期查詢](querying.md)。
## 使用 Athena 工作群組限制查詢歷史記錄的存取
Athena 查詢歷史記錄會公開已儲存查詢和完整查詢字串的清單。除非您使用工作群組來分隔查詢歷程記錄的存取權限，否則未獲授權在 Lake Formation 中查詢資料的 Athena 使用者可以檢視對該資料執行的查詢字串，包括資料欄名稱、選取準則等。我們建議您使用工作群組來分隔查詢歷程記錄，並使 Athena 工作群組成員資格與 Lake Formation 許可保持一致，以限制存取。如需詳細資訊，請參閱[使用工作群組來控制查詢存取和成本](workgroups-manage-queries-control-costs.md)。
## 查詢向 Lake Formation 註冊的 CSE\$1KMS 加密資料表
無法使用 Athena 查詢具有下列特性的開放資料表格式 (OTF) 資料表，例如 Apache Iceberg：
+ 這些資料表以向 Lake Formation 註冊的 Amazon S3 資料位置為基礎。
+ 使用用戶端加密 (CSE) 對 Amazon S3 中的物件進行加密。
+ 加密使用 AWS KMS 客戶受管金鑰 (`CSE_KMS`)。
若要查詢使用`CSE_KMS`金鑰加密的非OTF 資料表，請將下列區塊新增至您用於 CSE 加密的 AWS KMS 金鑰政策。** 是加密資料的 AWS KMS 金鑰 ARN。** 是 Lake Formation 中註冊 Amazon S3 位置的 IAM 角色的 ARN。
```
{
"Sid": "Allow use of the key",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "kms:Decrypt",
"Resource": "",
"Condition": {
"ArnLike": {
"aws:PrincipalArn": ""
}
}
}
```
## 向 Lake Formation 註冊的分割資料位置必須位於資料表子目錄中
向 Lake Formation 註冊的分割資料表必須在目錄中擁有分割資料，這些目錄是 Simple Storage Service (Amazon S3) 中資料表的子目錄。例如，具有 `s3://amzn-s3-demo-bucket/mytable` 位置和分割區 `s3://amzn-s3-demo-bucket/mytable/dt=2019-07-11`、`s3://amzn-s3-demo-bucket/mytable/dt=2019-07-12` 等的資料表，可以向 Lake Formation 註冊並使用 Athena 進行查詢。另一方面，位置 `s3://amzn-s3-demo-bucket/mytable` 的資料表和位於 `s3://amzn-s3-demo-bucket/dt=2019-07-11`、`s3://amzn-s3-demo-bucket/dt=2019-07-12` 等的分割區，無法向 Lake Formation 註冊。此類分割區不是 `s3://amzn-s3-demo-bucket/mytable` 的子目錄，因此也無法從 Athena 讀取。
## Create Table As Select (CTAS) 查詢需要 Amazon S3 寫入許可
Create Table As Statements (CTAS) 需要對資料表的 Simple Storage Service (Amazon S3) 位置的寫入存取權限。若要對在 Lake Formation 註冊的資料執行 CTAS 查詢，Athena 使用者除了適當的 Lake Formation 許可以讀取資料位置之外，還必須具有 IAM 許可才能寫入資料表 Simple Storage Service (Amazon S3) 位置。如需詳細資訊，請參閱[從查詢結果建立資料表 (CTAS)](ctas.md)。
## 預設資料庫需要 DESCRIBE 許可
`default` 資料庫需要 Lake Formation `DESCRIBE` 許可，如此 Lake Formation 才能檢視該資料庫。下列範例 AWS CLI 命令會將`default`資料庫的 `DESCRIBE`許可授予 AWS 帳戶 `datalake_user1`中的使用者`111122223333`。
```
aws lakeformation grant-permissions --principal DataLakePrincipalIdentifier=arn:aws:iam::111122223333:user/datalake_user1 --permissions "DESCRIBE" --resource '{ "Database": {"Name":"default"}}
```
如需詳細資訊，請參閱《AWS Lake Formation 開發人員指南》**中的 [DESCRIBE](https://docs.aws.amazon.com/lake-formation/latest/dg/lf-permissions-reference.html#perm-describe)。
# 設定跨帳戶 Data Catalog 存取權
若要存取另一個帳戶中的資料目錄，您可以使用 Athena 的跨帳戶 AWS Glue 功能或在 Lake Formation 中設定跨帳戶存取。
## 選項 A：在 Athena 中設定跨帳戶 Data Catalog 存取權
您可以使用 Athena 的跨帳戶 AWS Glue 目錄功能，在帳戶中註冊目錄。僅 Athena 引擎版本 2 及更新版本中提供此功能，且僅限於帳戶之間的相同區域使用。如需詳細資訊，請參閱[從另一個帳戶註冊 Data Catalog](data-sources-glue-cross-account.md)。
如果要共用的資料目錄在 中設定了資源政策 AWS Glue，則必須更新以允許存取 ， AWS Resource Access Manager 並授予許可給帳戶 B 使用帳戶 A 的資料目錄。
如需詳細資訊，請參閱[設定 AWS Glue 資料目錄的跨帳戶存取](security-iam-cross-account-glue-catalog-access.md)。
## 選項 B：在 Lake Formation 中設定跨帳戶存取權
AWS Lake Formation 可讓您使用單一帳戶來管理中央 Data Catalog。您可以使用此功能來實作對資料目錄中繼資料和基礎資料的[跨帳戶存取](https://docs.aws.amazon.com/lake-formation/latest/dg/access-control-cross-account.html)。例如，擁有者帳戶可以授予另一個 (收件人) 帳戶對資料表的 `SELECT` 許可。
若要在 Athena 查詢編輯器中顯示共用的資料庫或資料表，您需在 Lake Formation 中對共用的資料庫或資料表[建立資源連結](https://docs.aws.amazon.com/lake-formation/latest/dg/resource-links-about.html)。當 Lake Formation 中的收件人帳戶查詢擁有者的資料表時，[CloudTrail](https://docs.aws.amazon.com/lake-formation/latest/dg/cross-account-logging.html) 會將資料存取事件新增至收件人帳戶和擁有者帳戶的記錄。
如需共用視圖，請謹記下列要點：
+ 在目標資源連結上執行，而不是來源資料表或視圖上執行查詢，然後將輸出共用到目標帳戶。
+ 僅共用視圖並不足夠。建立視圖所涉及的所有資料表必須是跨帳戶共用的一部分。
+ 在共用資源上建立的資源連結的名稱必須與擁有者帳戶中的資源名稱相符。如果名稱不相符，則會出現一則錯誤訊息，例如分析存放檢視 'awsdatacatalog.*my-lf-resource-link*.*my-lf-view*' 失敗：行 3:3：結構描述 *schema\$1name* 不存在。
如需有關在 Lake Formation 中跨帳戶存取的詳細資訊，請參閱《AWS Lake Formation 開發人員指南》**中的以下資源：
[跨帳戶存取](https://docs.aws.amazon.com/lake-formation/latest/dg/access-control-cross-account.html)
[資源連結在 Lake Formation 中如何運作](https://docs.aws.amazon.com/lake-formation/latest/dg/resource-links-about.html)
[跨帳戶 CloudTrail 記錄](https://docs.aws.amazon.com/lake-formation/latest/dg/cross-account-logging.html)
# 管理 Lake Formation 和 Athena 使用者許可
Lake Formation 提供憑證來查詢向 Lake Formation 註冊的 Amazon S3) 資料存放區或聯合目錄。如果您之前使用 IAM 政策來允許或拒絕讀取 Amazon S3 中目錄或資料位置的許可，您可以改為使用 Lake Formation 許可。不過，仍需要其他 IAM 許可。
每當您使用 IAM 政策時，請務必遵循 IAM 最佳實務。如需詳細資訊，請參閱*《IAM 使用者指南》*中的 [IAM 中的安全性最佳實務](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)。
以下章節摘要說明使用 Athena 查詢在 Lake Formation 中註冊之資料所需的許可。如需詳細資訊，請參閱《AWS Lake Formation 開發人員指南》**中的 [AWS Lake Formation的安全性](https://docs.aws.amazon.com/lake-formation/latest/dg/security.html)。
**Topics**
+ [Lake Formation 和 Athena 的身分型許可](#lf-athena-user-permissions-identity-based)
+ [Athena 查詢結果位置的 Amazon S3 許可](#lf-athena-user-permissions-query-results-locations)
+ [查詢歷史記錄的 Athena 工作群組成員資格](#lf-athena-user-permissions-workgroup-memberships-query-history)
+ [Lake Formation 的資料許可](#lf-athena-user-permissions-data)
+ [寫入 Amazon S3 位置的 IAM 許可](#lf-athena-user-permissions-s3-write)
+ [加密資料、中繼資料和 Athena 查詢結果的許可](#lf-athena-user-permissions-encrypted)
+ [外部帳戶中的 Amazon S3 儲存貯體以資源為基礎的許可 (選用)](#lf-athena-user-permissions-s3-cross-account)
## Lake Formation 和 Athena 的身分型許可
任何使用 Athena 查詢向 Lake Formation 註冊之資料的人，都必須擁有允許 `lakeformation:GetDataAccess` 動作的 IAM 許可政策。[AWS 受管政策：AmazonAthenaFullAccess](security-iam-awsmanpol.md#amazonathenafullaccess-managed-policy) 允許此動作。如果您使用內嵌政策，請務必更新許可政策來允許此動作。
在 Lake Formation 中，*資料湖管理員*具有建立中繼資料物件 (例如資料庫和資料表)、授予 Lake Formation 許可給其他使用者，以及註冊新 Amazon S3 位置或資料目錄的許可。若要註冊新的位置，需要 Lake Formation 的服務連結角色許可。如需詳細資訊，請參閱《AWS Lake Formation 開發人員指南》**中的[建立資料湖管理員](https://docs.aws.amazon.com/lake-formation/latest/dg/getting-started-setup.html#create-data-lake-admin)和 [Lake Formation 的服務連結角色許可](https://docs.aws.amazon.com/lake-formation/latest/dg/service-linked-roles.html#service-linked-role-permissions)。
Lake Formation 使用者可以根據資料湖管理員授予的 Lake Formation 許可，使用 Athena 查詢資料庫、資料表、資料表資料欄和基礎 Amazon S3 資料存放區或目錄。使用者無法建立資料庫或資料表，或向 Lake Formation 註冊新的 Simple Storage Service (Amazon S3) 位置。如需詳細資訊，請參閱《AWS Lake Formation 開發人員指南》**中的[建立資料湖使用者](https://docs.aws.amazon.com/lake-formation/latest/dg/cloudtrail-tut-create-lf-user.html)。
在 Athena 中，身分型許可政策 (包括 Athena 工作群組的政策) 仍然控制 Amazon Web Services 帳戶使用者對 Athena 動作的存取。此外，還可能透過 Athena 驅動程式提供以 SAML 為基礎的身分驗證來提供聯合存取。如需詳細資訊，請參閱[使用工作群組來控制查詢存取和成本](workgroups-manage-queries-control-costs.md)、[使用 IAM 政策來控制工作群組存取](workgroups-iam-policy.md)及[啟用對 Athena API 的聯合存取](access-federation-saml.md)。
如需詳細資訊，請參閱《AWS Lake Formation 開發人員指南》**中的[授予 Lake Formation 許可](https://docs.aws.amazon.com/lake-formation/latest/dg/lake-formation-permissions.html)。
## Athena 查詢結果位置的 Amazon S3 許可
Simple Storage Service (Amazon S3) 中的 Athena 查詢結果無法向 Lake Formation 註冊。Lake Formation 許可不會限制對這些位置的存取。除非您限制存取，否則 Athena 使用者可以在沒有 Lake Formation 的資料許可時存取查詢結果檔案和中繼資料。若要避免這種情況，我們建議您使用工作群組來指定查詢結果的位置，並使工作群組成員資格與 Lake Formation 許可保持一致。然後，您可以使用 IAM 許可政策來限制查詢結果位置的存取。如需有關查詢結果的詳細資訊，請參閱[使用查詢結果和近期查詢](querying.md)。
## 查詢歷史記錄的 Athena 工作群組成員資格
Athena 查詢歷史記錄會公開已儲存查詢和完整查詢字串的清單。除非您使用工作群組來分隔查詢歷程記錄的存取權限，否則未獲授權在 Lake Formation 中查詢資料的 Athena 使用者可以檢視對該資料執行的查詢字串，包括資料欄名稱、選取準則等。我們建議您使用工作群組來分隔查詢歷程記錄，並使 Athena 工作群組成員資格與 Lake Formation 許可保持一致，以限制存取。如需詳細資訊，請參閱[使用工作群組來控制查詢存取和成本](workgroups-manage-queries-control-costs.md)。
## Lake Formation 的資料許可
除了使用 Lake Formation 的基準許可之外，Athena 使用者還必須具備 Lake Formation 許可，才能存取其查詢的資源。這些許可是由 Lake Formation 管理員授予和管理。如需詳細資訊，請參閱《AWS Lake Formation 開發人員指南》**中的[中繼資料與資料的安全性與存取控制](https://docs.aws.amazon.com/lake-formation/latest/dg/security-data-access.html#security-data-access-permissions)。
## 寫入 Amazon S3 位置的 IAM 許可
對 Simple Storage Service (Amazon S3) 的 Lake Formation 許可不包含寫入 Simple Storage Service (Amazon S3) 的能力。Create Table As Statements (CTAS) 需要對資料表的 Simple Storage Service (Amazon S3) 位置的寫入存取權限。若要對在 Lake Formation 註冊的資料執行 CTAS 查詢，Athena 使用者除了適當的 Lake Formation 許可以讀取資料位置之外，還必須具有 IAM 許可才能寫入資料表 Simple Storage Service (Amazon S3) 位置。如需詳細資訊，請參閱[從查詢結果建立資料表 (CTAS)](ctas.md)。
## 加密資料、中繼資料和 Athena 查詢結果的許可
在 Amazon S3 中的基礎來源資料，以及向 Lake Formation 註冊的目錄中繼資料都可以加密。使用 Athena 查詢向 Lake Formation 註冊的資料時，Athena 處理查詢結果加密的方式沒有變更。如需詳細資訊，請參閱[加密 Amazon S3 中存放的 Athena 查詢結果](encrypting-query-results-stored-in-s3.md)。
+ **加密來源資料** – 支援 Simple Storage Service (Amazon S3) 資料位置來源資料的加密。查詢向 Lake Formation 註冊的已加密 Simple Storage Service (Amazon S3) 位置的 Athena 使用者，需要加密和解密資料的許可。如需有關需求的詳細資訊，請參閱[支援的 Amazon S3 加密選項](encryption.md#encryption-options-S3-and-Athena)和[Amazon S3 中加密資料的許可](encryption.md#permissions-for-encrypting-and-decrypting-data)。
+ **加密中繼資料** – AWS Glue Data Catalog 支援在 中加密中繼資料。對於使用 Athena 的主體，身分型政策必須允許用於加密中繼資料之索引鍵的 `"kms:GenerateDataKey"`、`"kms:Decrypt"` 和 `"kms:Encrypt"` 動作。如需詳細資訊，請參閱《AWS Glue 開發人員指南**》和 [在 中設定從 Athena 到加密中繼資料的存取權 AWS Glue Data Catalog](access-encrypted-data-glue-data-catalog.md) 中的[加密您的資料目錄](https://docs.aws.amazon.com/glue/latest/dg/encrypt-glue-data-catalog.html)。
## 外部帳戶中的 Amazon S3 儲存貯體以資源為基礎的許可 (選用)
若要在不同帳戶中查詢 Simple Storage Service (Amazon S3) 資料位置，以資源為基礎的 IAM 政策 (儲存貯體政策) 必須允許存取該位置。如需詳細資訊，請參閱[設定 Athena 中的 Amazon S3 儲存貯體跨帳戶存取權](cross-account-permissions.md)。
如需有關在其他帳戶中存取目錄的資訊，請參閱 [選項 A：在 Athena 中設定跨帳戶 Data Catalog 存取權](lf-athena-limitations-cross-account.md#lf-athena-limitations-cross-account-glue)。
# 使用 Lake Formation 和 JDBC 或 ODBC 驅動器對 Athena 進行聯合存取
Athena JDBC 和 ODBC 驅動程式支援使用 Okta 和 Microsoft Active Directory 聯合服務 (AD FS) 身分提供者，實現以 SAML 2.0 為基礎的 Athena 聯合。透過整合 Amazon Athena 與 AWS Lake Formation，您可以使用公司登入資料對 Athena 啟用 SAML 型身分驗證。使用 Lake Formation 和 AWS Identity and Access Management (IAM)，您可以對 SAML 使用者可用的資料維持精細的資料層級存取控制。透過 Athena JDBC 和 ODBC 驅動程式，聯合存取可用於工具或程式設計存取。
若要使用 Athena 存取 Lake Formation 控制的資料來源，您需要透過設定身分提供者 (IdP) 和 AWS Identity and Access Management (IAM) 角色來啟用 SAML 2.0 型聯合。如需詳細步驟，請參閱[教學課程：使用 Lake Formation 和 JDBC 設定 Okta 使用者對 Athena 的聯合存取](security-athena-lake-formation-jdbc-okta-tutorial.md)。
## 先決條件
若要使用 Amazon Athena 和 Lake Formation 進行聯合存取，您必須符合以下需求：
+ 您使用現有以 SAML 為基礎的身分提供者來管理您的公司身分，例如 Okta 或 Microsoft Active Directory 聯合服務 (AD FS)。
+ 您可以使用 AWS Glue Data Catalog 做為中繼資料存放區。
+ 您在 Lake Formation 中定義和管理許可，以存取 AWS Glue Data Catalog中的資料庫、資料表和資料欄。如需詳細資訊，請參閱《AWS Lake Formation 開發人員指南》[https://docs.aws.amazon.com/lake-formation/latest/dg/](https://docs.aws.amazon.com/lake-formation/latest/dg/)。
+ 您使用 2.0.14 版或更新版本的 [Athena JDBC 驅動程式](https://docs.aws.amazon.com/athena/latest/ug/connect-with-jdbc.html)，或 1.1.3 版或更新版本的 [Athena ODBC 驅動程式](connect-with-odbc.md)。
## 考量和限制
使用 Athena JDBC 或 ODBC 驅動程式和 Lake Formation 來設定對 Athena 的聯合存取時，請記住下列幾點：
+ 目前，Athena JDBC 驅動程式和 ODBC 驅動程式支援 Okta、Microsoft Active Directory 聯合服務 (AD FS) 和 Azure AD 身分提供者。雖然 Athena JDBC 驅動程式具有可擴充為使用其他身分提供者的通用 SAML 類別，但是讓其他身分提供者 (IdP) 搭配 Athena 使用的自訂擴充功能支援可能會受到限制。
+ 使用 JDBC 和 ODBC 驅動程式的聯合存取與 IAM Identity Center 信任身分傳播功能不相容。
+ 目前，您無法使用 Athena 主控台來設定 IdP 和 SAML 與 Athena 搭配使用時的支援。若要設定此支援，請使用第三方身分提供者、Lake Formation 和 IAM 管理主控台，以及 JDBC 或 ODBC 驅動程式用戶端。
+ 在設定身分提供者和 SAML 以與 Lake Formation 和 Athena 搭配使用之前，您應先了解 [SAML 2.0 規格](https://www.oasis-open.org/standards#samlv2.0)以及其如何與您的身分提供者搭配使用。
+ SAML 提供者和 Athena JDBC 和 ODBC 驅動程式由第三方提供，因此對 的使用相關問題 AWS 的支援可能會受到限制。
**Topics**
+ [先決條件](#security-athena-lake-formation-jdbc-prerequisites)
+ [考量和限制](#security-athena-lake-formation-jdbc-considerations-and-limitations)
+ [教學課程：使用 Lake Formation 和 JDBC 設定 Okta 使用者對 Athena 的聯合存取](security-athena-lake-formation-jdbc-okta-tutorial.md)
# 教學課程：使用 Lake Formation 和 JDBC 設定 Okta 使用者對 Athena 的聯合存取
本教學課程說明如何設定 Okta AWS Lake Formation、、 AWS Identity and Access Management permissions 和 Athena JDBC 驅動程式，以啟用 Athena 的 SAML 型聯合使用。Lake Formation 為以 SAML 為基礎的使用者提供對 Athena 中可用資料的精細存取控制。若要設定此組態，教學課程會使用 Okta 開發人員主控台、IAM AWS 和 Lake Formation 主控台，以及 SQL Workbench/J 工具。
**先決條件**
此教學課程假設您已完成下列作業：
+ 已建立 Amazon Web Services 帳戶。若要建立帳戶，請造訪 [Amazon Web Services 首頁](https://aws.amazon.com/)。
+ 在 Amazon S3 中為 Athena [設定查詢結果位置](query-results-specify-location.md)。
+ 向 Lake Formation [註冊 Amazon S3 資料儲存貯體位置](https://docs.aws.amazon.com/lake-formation/latest/dg/register-data-lake.html)
+ 在 [AWS Glue 資料目錄](https://docs.aws.amazon.com/glue/latest/dg/what-is-glue.html) (指向您在 Amazon S3 中的資料) 上定義[資料庫](https://docs.aws.amazon.com/glue/latest/dg/define-database.html)和[資料表](https://docs.aws.amazon.com/glue/latest/dg/tables-described.html)。
+ 如果您尚未定義資料表，請[執行 AWS Glue 爬蟲程式](https://docs.aws.amazon.com/glue/latest/dg/add-crawler.html)[或使用 Athena 為您要存取的資料定義資料庫和一或多個資料表](work-with-data.md)。
+ 本教學課程使用以[紐約計程車行程資料集](https://registry.opendata.aws/nyc-tlc-trip-records-pds/) (可於 [AWS上的開放資料登記處](https://registry.opendata.aws/)取得) 為基礎的資料表。本教學課程會使用資料庫名稱 `tripdb` 和資料表名稱 `nyctaxi`。
**Topics**
+ [步驟 1：建立 Okta 帳戶](#security-athena-lake-formation-jdbc-okta-tutorial-step-1-create-an-okta-account)
+ [步驟 2：將使用者和群組新增至 Okta](#security-athena-lake-formation-jdbc-okta-tutorial-step-2-set-up-an-okta-application-for-saml-authentication)
+ [步驟 3：設定用於 SAML 身分驗證的 Okta 應用程式](#security-athena-lake-formation-jdbc-okta-tutorial-step-3-set-up-an-okta-application-for-saml-authentication)
+ [步驟 4：建立 AWS SAML 身分提供者和 Lake Formation 存取 IAM 角色](#security-athena-lake-formation-jdbc-okta-tutorial-step-4-create-an-aws-saml-identity-provider-and-lake-formation-access-IAM-role)
+ [步驟 5：將 IAM 角色和 SAML 身分提供者新增至 Okta 應用程式](#security-athena-lake-formation-jdbc-okta-tutorial-step-5-update-the-okta-application-with-the-aws-role-and-saml-identity-provider)
+ [步驟 6：透過 授予使用者和群組許可 AWS Lake Formation](#security-athena-lake-formation-jdbc-okta-tutorial-step-6-grant-permissions-through-aws-lake-formation)
+ [步驟 7：驗證透過 Athena JDBC 用戶端的存取](#security-athena-lake-formation-jdbc-okta-tutorial-step-7-verify-access-through-athena-jdbc-client)
+ [結論](#security-athena-lake-formation-jdbc-okta-tutorial-conclusion)
+ [相關資源](#security-athena-lake-formation-jdbc-okta-tutorial-related-resources)
## 步驟 1：建立 Okta 帳戶
本教學課程使用 Okta 作為以 SAML 為基礎的身分提供者。如果您還沒有 Okta 帳戶，您可以建立免費的帳戶。需要 Okta 帳戶，以便您可以建立用於 SAML 身分驗證的 Okta 應用程式。
**若要建立 Okta 帳戶**
1. 若要使用 Okta，請導覽至 [Okta 開發人員註冊頁面](https://developer.okta.com/signup/)並建立免費的 Okta 試用帳戶。開發人員版服務免費提供，最高可達 Okta 在 [developer.okta.com/pricing](https://developer.okta.com/pricing) 指定的限制。
1. 收到啟用電子郵件時，請啟用您的帳戶。
Okta 網域名稱將會指派給您。儲存網域名稱以供參考。稍後，您可以使用 JDBC 字串 (連接到 Athena) 中的網域名稱 (**)。
## 步驟 2：將使用者和群組新增至 Okta
在此步驟中，您可以使用 Okta 主控台來執行以下任務：
+ 建立兩個 Okta 使用者。
+ 建立兩個 Okta 群組。
+ 在每個 Okta 群組中新增一個 Okta 使用者。
**若要將使用者新增至 Okta**
1. 啟用 Okta 帳戶之後，請以管理使用者身分登入指派的 Okta 網域。
1. 在左側導覽窗格中，選擇 **Directory** (目錄)，然後選擇 **People** (人員)。
1. 選擇 **Add Person** (新增人員)，新增一個將透過 JDBC 驅動程式存取 Athena 的新使用者。
![\[選擇 Add Person (新增人員)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-3.png)
1. 在 **Add Person** (新增人員) 對話方塊中，輸入所需資訊。
+ 輸入 **First name** (名字) 和 **Last name** (姓氏) 的值。本教學課程使用 *athena-okta-user*。
+ 輸入 **Username** (使用者名稱) 和 **Primary email** (主要電子郵件地址)。本教學課程使用 *athena-okta-user@anycompany.com*。
+ 對於 **Password** (密碼)，選擇 **Set by admin** (由管理員設定)，然後提供密碼。本教學課程會清除 **User must change password on first login** (使用者首次登入時必須變更密碼) 的選項；您的安全需求可能會有所不同。
![\[將使用者新增至 Okta 應用程式。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-4.png)
1. 選擇 **Save and Add Another** (儲存並新增另一個)。
1. 輸入另一個使用者的資訊。此範例會新增業務分析師使用者 *athena-ba-user@anycompany.com*。
![\[將使用者新增至 Okta 應用程式。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-4a.png)
1. 選擇**儲存**。
在下列程序中，您可以新增 "Business Analysts" (業務分析師) 群組和 "Developer" (開發人員) 群組，透過 Athena JDBC 驅動程式提供兩個 Okta 群組的存取權限。
**若要新增 Okta 群組**
1. 在 Okta 導覽窗格中選擇 **Directory** (目錄)，然後選擇 **Groups** (群組)。
1. 在 **Groups** (群組) 頁面上，選擇 **Add Group** (新增群組)。
![\[選擇 Add Group (新增群組)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-4c.png)
1. 在 **Add Group** (新增群組) 對話方塊中，輸入所需資訊。
+ 在 **Name** (名稱) 中輸入 *lf-business-analyst*。
+ 在 **Group Description** (群組描述) 中輸入 *Business Analysts* (業務分析師)。
![\[新增 Okta 群組。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-4d.png)
1. 選擇 **Add Group** (新增群組)。
1. 在 **Groups** (群組) 頁面上，再次選擇 **Add Group** (新增群組)。現在輸入開發人員群組的資訊。
1. 輸入所需資訊。
+ 在 **Name** (名稱) 中輸入 *lf-developer*。
+ 在 **Group Description** (群組描述) 中輸入 *Developers* (開發人員)。
1. 選擇 **Add Group** (新增群組)。
現在您已擁有兩個使用者和兩個群組，可以在每個群組中新增使用者。
**若要將使用者新增至群組**
1. 在 **Groups** (群組) 頁面上，選擇您剛建立的 **lf-developer** 群組。您需將您建立為開發人員的 Okta 使用者之一新增至此群組。
![\[選擇 lf-developer。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-4f.png)
1. 選擇 **Manage People** (管理人員)。
![\[選擇 Manage People (管理人員)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-4g.png)
1. 從 **Not Members** (非成員) 清單，選擇 **athena-okta-user**。
![\[選擇要新增至成員清單的使用者。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-4h.png)
使用者的項目會從左側的 **Not Members** (非成員) 清單移動至右側的 **Members** (成員) 清單。
![\[Okta 使用者已新增至 Okta 群組。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-4i.png)
1. 選擇**儲存**。
1. 選擇 **Back to Group** (返回群組)，或選擇 **Directory** (目錄)，接著選擇 **Groups** (群組)。
1. 選擇 **lf-business-analyst** 群組。
1. 選擇 **Manage People** (管理人員)。
1. 將 **athena-ba-user** 新增至 **lf-business-analyst** 群組的 **Members** (成員) 清單，然後選擇 **Save** (儲存)。
1. 選擇 **Back to Group** (返回群組)，或依序選擇 **Directory** (目錄)、**Groups** (群組)。
**Groups** (群組) 頁面現在顯示每個群組都有一個 Okta 使用者。
![\[Okta 主控台中的每個 Okta 群組均已新增一個使用者。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-4j.png)
## 步驟 3：設定用於 SAML 身分驗證的 Okta 應用程式
在此步驟中，您需使用 Okta 開發人員主控台以執行下列任務：
+ 新增 SAML 應用程式以搭配 使用 AWS。
+ 將應用程式指派給 Okta 使用者。
+ 將應用程式指派給 Okta 群組。
+ 下載產生的身分提供者中繼資料，以便稍後與 AWS搭配使用。
**若要新增應用程式以進行 SAML 身分驗證**
1. 在 Okta 導覽窗格中，選擇 **Applications** (應用程式)、**Applications** (應用程式)，以便您可設定 Okta 應用程式以進行對 Athena 的 SAML 身分驗證。
1. 按一下 **Browse App Catalog** (瀏覽應用程式目錄)。
1. 在搜尋方塊中，輸入 **Redshift**。
1. 選擇 **Amazon Web Services Redshift**。本教學課程中的 Okta 應用程式對 Amazon Redshift 使用現有的 SAML 整合。
![\[選擇 Amazon Web Services Redshift。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-7.png)
1. 在 **Amazon Web Services Redshift** 頁面上，選擇 **Add** (新增) 來為 Amazon Redshift 建立以 SAML 為基礎的應用程式。
![\[選擇 Add (新增) 來建立以 SAML 為基礎的應用程式。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-8.png)
1. 在 **Application** (應用程式) 標籤中輸入 `Athena-LakeFormation-Okta`，然後選擇 **Done** (完成)。
![\[輸入 Okta 應用程式的名稱。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-9.png)
現在您已建立 Okta 應用程式，您可以將其指派給您建立的使用者和群組。
**若要將應用程式指派給使用者和群組**
1. 在 **Applications** (應用程式) 頁面上，選擇 **Athena-LakeFormation-Okta** 應用程式。
1. 在 **Assignments** (指派) 索引標籤上，依序選擇 **Assign** (指派)、**Assign to People** (指派給人員)。
![\[依序選擇 Assign (指派)、Assign to People (指派給人員)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-10.png)
1. 在 **Assign Athena-LakeFormation-Okta to People** (將 Athena-LakeFormation-Okta 指派給人員) 對話方塊中，尋找您之前建立的 **athena-okta-user** 使用者。
1. 選擇 **Assign** (指派) 將使用者指派給應用程式。
![\[選擇 Assign (指派)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-11.png)
1. 選擇 **Save and Go Back** (儲存並返回)。
1. 選擇 **Done** (完成)。
1. 在 **Athena-LakeFormation-Okta** 應用程式的 **Assignments** (指派) 索引標籤上，依序選擇 **Assign** (指派)、**Assign to Groups** (指派給群組)。
1. 對於 **lf-business-analyst**，選擇 **Assign** (指派)，將 **Athena-LakeFormation-Okta** 應用程式指派給 **lf-business-analyst** 群組，然後選擇 **Done** (完成)。
![\[將 Okta 應用程式指派給 Okta 使用者群組。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-12b.png)
該群組會出現在應用程式的群組清單中。
![\[Okta 應用程式指派給 Okta 群組。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-12c.png)
現在您已準備好下載身分提供者應用程式中繼資料，以與 AWS搭配使用。
**若要下載應用程式中繼資料**
1. 選擇 Okta 應用程式 **Sign On** (登入) 索引標籤，然後以滑鼠右鍵按一下 **Identity Provider metadata** (身分提供者中繼資料)。
![\[在 Identity Provider metadata (身分提供者中繼資料) 上按一下滑鼠右鍵。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-13.png)
1. 選擇 **Save Link As** (另存連結)，將 XML 格式的身分提供者中繼資料儲存至檔案中。指定一個您認識的名稱 (例如 `Athena-LakeFormation-idp-metadata.xml`)。
![\[儲存身分提供者中繼資料。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-14.png)
## 步驟 4：建立 AWS SAML 身分提供者和 Lake Formation 存取 IAM 角色
在此步驟中，您可以使用 AWS Identity and Access Management (IAM) 主控台來執行下列任務：
+ 為 AWS建立身分提供者。
+ 為 Lake Formation 存取建立 IAM 角色。
+ 將 AmazonAthenaFullAccess 受管政策新增至該角色。
+ 將 Lake Formation 和 的政策 AWS Glue 新增至角色。
+ 將 Athena 查詢結果的政策新增至該角色。
**建立 AWS SAML 身分提供者**
1. 以 **Amazon Web Services 帳戶管理員**身分登入 **Amazon Web Services 帳戶****主控台**，並導覽至 **IAM** 主控台 ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/))。
1. 在導覽窗格中，選擇 **Identity providers** (身分提供者)，然後按一下 **Add provider** (新增供應商)。
1. 在 **Configure provider** (設定供應商) 畫面上，輸入以下資訊：
+ 對於 **Provider type** (供應商類型)，選擇 **SAML**。
+ 對於 **Provider name** (供應商名稱)，輸入 `AthenaLakeFormationOkta`。
+ 對於 **Metadata document** (中繼資料文件)，使用 **Choose file** (選擇檔案) 選項，以上傳您下載的身分提供者 (IdP) 中繼資料 XML 檔案。
1. 選擇 **Add provider** (新增供應商)。
接著，您可以建立 IAM 角色以進行 AWS Lake Formation 存取。您可以將兩個內嵌政策新增至該角色。一個政策提供存取 Lake Formation 和 AWS Glue APIs的許可。另一個政策可用於存取 Athena 和在 Amazon S3 中的 Athena 查詢結果位置。
**建立用於 AWS Lake Formation 存取的 IAM 角色**
1. 在 IAM 主控台導覽窗格中，選擇 **Roles** (角色)，然後選擇 **Create role** (建立角色)。
1. 在 **Create role** (建立角色) 頁面上，執行以下步驟：
![\[將 IAM 角色設定為使用 SAML 2.0。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-20.png)
1. 對於 **Select type of trusted entity** (選取信任的實體類型)，選擇 **SAML 2.0 Federation** (SAML 2.0 聯合)。
1. 對於 **SAML provider** (SAML 供應商)，選取 **AthenaLakeFormationOkta**。
1. 對於 **SAML 供應商**，選取**允許程式設計和 AWS 管理主控台 存取**選項。
1. 選擇 **Next: Permissions** (下一步：許可)。
1. 在 **Attach Permissions policies** (連接許可政策) 頁面上，對於 **Filter policies** (篩選條件政策)，輸入 **Athena**。
1. 選取名為 **AmazonAthenaFullAccess** 的受管政策，然後選擇 **Next: Tags** (下一步：標籤)。
![\[將 AmazonAthenaFullAccess 受管政策附加至 IAM 角色。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-21.png)
1. 在 **Add tags** (新增標籤) 頁面上，選擇 **Next: Review** (下一步：檢閱)。
1. 在 **Review** (檢閱) 頁面上，對於 **Role name** (角色名稱)，輸入角色的名稱 (例如 *Athena-LakeFormation-OktaRole*)，然後選擇 **Create role** (建立角色)。
![\[輸入 IAM 角色的名稱。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-22.png)
接著，您可以新增內嵌政策，允許存取 Amazon S3 中的 Lake Formation、 AWS Glue APIs和 Athena 查詢結果。
每當您使用 IAM 政策時，請務必遵循 IAM 最佳實務。如需詳細資訊，請參閱《IAM 使用者指南》**中的 [IAM 中的安全性最佳實務](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)。
**將內嵌政策新增至 Lake Formation 和 的角色 AWS Glue**
1. 從 IAM 主控台的角色清單中，選擇新建立的 `Athena-LakeFormation-OktaRole`。
1. 在角色的 **Summary** (摘要) 頁面之 **Permissions** (許可) 索引標籤上，選擇 **Add inline policy** (新增內嵌政策)。
1. 在 **Create policy** (建立政策) 頁面上，選擇 **JSON**。
1. 新增內嵌政策 (如下所示)，該政策提供對 Lake Formation 和 AWS Glue API 的存取權限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"lakeformation:GetDataAccess",
"glue:GetTable",
"glue:GetTables",
"glue:GetDatabase",
"glue:GetDatabases",
"glue:CreateDatabase",
"glue:GetUserDefinedFunction",
"glue:GetUserDefinedFunctions"
],
"Resource": "*"
}
}
```
------
1. 選擇 **Review policy** (檢閱政策)。
1. 對於 **Name** (名稱)，輸入政策名稱 (例如 **LakeFormationGlueInlinePolicy**)。
1. 選擇 **Create policy** (建立政策)。
**若要針對 Athena 查詢結果位置將內嵌政策新增至角色**
1. 在 `Athena-LakeFormation-OktaRole` 角色 的 **Summary** (摘要) 頁面之 **Permissions** (許可) 索引標籤上，選擇 **Add inline policy** (新增內嵌政策)。
1. 在 **Create policy** (建立政策) 頁面上，選擇 **JSON**。
1. 新增內嵌政策 (如下所示)，該政策允許對 Athena 查詢結果位置進行角色存取。將範例中的 ** 預留位置取代為您的 Amazon S3 儲存貯體名稱。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AthenaQueryResultsPermissionsForS3",
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:PutObject",
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::",
"arn:aws:s3:::/*"
]
}
]
}
```
------
1. 選擇 **Review policy** (檢閱政策)。
1. 對於 **Name** (名稱)，輸入政策名稱 (例如 **AthenaQueryResultsInlinePolicy**)。
1. 選擇 **Create policy** (建立政策)。
接下來，您要複製 Lake Formation 存取角色的 ARN 和您建立的 SAML 供應商的 ARN。在本教學課程的下一節中設定 Okta SAML 應用程式時，這些都是必要的程序。
**若要複製角色 ARN 和 SAML 身分提供者 ARN**
1. 在 IAM 主控台中，在 `Athena-LakeFormation-OktaRole` 角色的 **Summary** (摘要) 頁面上，選擇 **Role ARN** (角色 ARN) 旁的 **Copy to clipboard** (複製至剪貼簿) 圖示。ARN 採用下列格式：
```
arn:aws:iam:::role/Athena-LakeFormation-OktaRole
```
1. 安全地儲存完整的 ARN 以供日後參考。
1. 在 IAM 主控台導覽窗格中，選擇 **Identity providers** (身分提供者)。
1. 選擇 **AthenaLakeFormationOkta** 供應商。
1. 在 **Summary** (摘要) 頁面上，選擇 **Provider ARN** (供應商 ARN) 旁的 **Copy to clipboard** (複製至剪貼簿) 圖示。ARN 看起來應該如下所示：
```
arn:aws:iam:::saml-provider/AthenaLakeFormationOkta
```
1. 安全地儲存完整的 ARN 以供日後參考。
## 步驟 5：將 IAM 角色和 SAML 身分提供者新增至 Okta 應用程式
在此步驟中，您需返回 Okta 開發人員主控台並執行下列任務：
+ 將使用者和群組的 Lake Formation URL 屬性新增至 Okta 應用程式。
+ 將身分提供者的 ARN 和 IAM 角色的 ARN 新增至 Okta 應用程式。
+ 複製 Okta 應用程式 ID。連接至 Athena 的 JDBC 設定檔中需要 Okta 應用程式 ID。
**若要將使用者和群組的 Lake Formation URL 屬性新增至 Okta 應用程式**
1. 登入 Okta 開發人員主控台。
1. 選擇 **Applications** (應用程式) 索引標籤，然後選擇 `Athena-LakeFormation-Okta` 應用程式。
1. 選擇應用程式的 **Sign On** (登入) 索引標籤，然後選擇 **Edit** (編輯)。
![\[編輯 Okta 應用程式。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-24.png)
1. 選擇 **Attributes (optional)** (屬性 (選填)) 以將其展開。
![\[將使用者 Lake Formation URL 屬性新增至 Okta 應用程式。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-25.png)
1. 對於 **Attribute Statements (optional)** (屬性陳述式 (選填))，新增下列屬性：
+ 對於 **Name** (名稱)，輸入 **https://lakeformation.amazon.com/SAML/Attributes/Username**。
+ 對於 **Value** (值)，輸入 **user.login**
1. 在 **Group Attribute Statements (optional)** (群組屬性陳述式 (選填)) 下，新增下列屬性：
+ 對於 **Name** (名稱)，輸入 **https://lakeformation.amazon.com/SAML/Attributes/Groups**。
+ 對於 **Name format** (名稱格式)，輸入 **Basic**
+ 對於 **Filter** (篩選條件)，選擇 **Matches regex** (符合 regex)，然後在篩選條件方塊中輸入 **.\$1**。
![\[將群組的 Lake Formation URL 屬性新增至 Okta 應用程式。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-25a.png)
1. 向下捲動至 **Advanced Sign-On Settings** (進階登入設定) 區段，您可以在此將身分提供者和 IAM 角色 ARN 新增至 Okta 應用程式。
**若要將身分提供者和 IAM 角色的 ARN 新增至 Okta 應用程式**
1. 對於 **Idp ARN 和角色 ARN**，以逗號分隔值格式輸入 AWS 身分提供者 ARN 和角色 ARN，格式為 **、**。組合的字串看起來應該如下所示：
```
arn:aws:iam:::saml-provider/AthenaLakeFormationOkta,arn:aws:iam:::role/Athena-LakeFormation-OktaRole
```
![\[在 Okta 應用程式中輸入身分提供者 ARN 和 IAM 角色 ARN。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-26.png)
1. 選擇**儲存**。
接下來，複製 Okta 應用程式 ID。您稍後需要此 ID，以用於連接至 Athena 的 JDBC 字串。
**若要尋找並複製 Okta 應用程式 ID**
1. 選擇 Okta 應用程式的 **General** (一般) 索引標籤。
![\[選擇 Okta 應用程式的 General (一般) 索引標籤。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-27.png)
1. 向下捲動至 **App Embed Link** (應用程式內嵌連結) 區段。
1. 從 **Embed Link** (內嵌連結)，複製並安全地儲存 URL 的 Okta 應用程式 ID 部分。Okta 應用程式 ID 是 URL 中在 `amazon_aws_redshift/` 之後、下一個正斜線之前的部分。例如，如果 URL 包含 `amazon_aws_redshift/aaa/bbb`，則應用程式 ID 為 `aaa`。
![\[複製 Okta 應用程式 ID。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-28.png)
**注意**
無法使用嵌入的連結直接登入 Athena 主控台以查看資料庫。僅當您使用 JDBC 或 ODBC 驅動程式向 Athena 提交查詢時，才能識別 SAML 使用者和群組的 Lake Formation 許可。若要查看資料庫，您可以使用 SQL Workbench/J 工具，其使用 JDBC 驅動程式連接至 Athena。在 [步驟 7：驗證透過 Athena JDBC 用戶端的存取](#security-athena-lake-formation-jdbc-okta-tutorial-step-7-verify-access-through-athena-jdbc-client) 中有SQL Workbench/J 工具的說明。
## 步驟 6：透過 授予使用者和群組許可 AWS Lake Formation
在此步驟中，您可以使用 Lake Formation 主控台，將資料表的許可授予 SAML 使用者和群組。執行以下任務：
+ 指定 Okta SAML 使用者的 ARN 和資料表的相關使用者許可。
+ 指定 Okta SAML 群組的 ARN 和資料表的相關群組許可。
+ 確認您授予的許可。
**若要在 Lake Formation 中為 Okta 使用者授予許可**
1. 以資料湖管理員身分登入 AWS 管理主控台。
1. 開啟 Lake Formation 主控台，網址為 [https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/)。
1. 從導覽窗格中，選擇 **Tables** (資料表)，然後選取您要為其授予許可的資料表。本教學課程使用來自 `tripdb` 資料庫的 `nyctaxi` 資料表。
![\[選擇您要為其授予許可的資料表。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-29.png)
1. 從 **Actions** (動作)，選擇 **Grant** (授予)。
![\[選擇 Grant (授予)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-30.png)
1. 在 **Grant permissions** (授予許可) 對話方塊中，輸入下列資訊：
1. 在 **SAML 和 Amazon Quick 使用者和群組**下，以下列格式輸入 Okta SAML 使用者 ARN：
```
arn:aws:iam:::saml-provider/AthenaLakeFormationOkta:user/@
```
1. 對於 **Columns** (資料欄)、**Choose filter type** (選擇篩選條件類型)，選擇性地選擇 **Include columns** (包含資料欄) 或 **Exclude columns** (排除資料欄)。
1. 使用篩選條件下的 **Choose one or more columns** (選擇一或多個資料欄) 下拉式清單，以指定您要包含或排除使用者的資料欄。
1. 對於 **Table permissions** (資料表許可)，選擇 **Select** (選取)。本教學課程僅授予 `SELECT` 許可；您的需求可能會有所不同。
![\[將表格和資料欄層級許可授予 Okta 使用者。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-31.png)
1. 選擇 **Grant** (授予)。
現在再針對 Okta 群組執行類似的步驟。
**若要在 Lake Formation 中為 Okta 群組授予許可**
1. 在 Lake Formation 主控台的 **Tables** (資料表) 頁面上，確定仍選取 **nyctaxi** 資料表。
1. 從 **Actions** (動作)，選擇 **Grant** (授予)。
1. 在 **Grant permissions** (授予許可) 對話方塊中，輸入下列資訊：
1. 在 **SAML 和 Amazon Quick 使用者和群組**下，以下列格式輸入 Okta SAML 群組 ARN：
```
arn:aws:iam:::saml-provider/AthenaLakeFormationOkta:group/lf-business-analyst
```
1. 對於 **Columns** (資料欄)、**Choose filter type** (選擇篩選條件類型)，選擇 **Include columns** (包含資料欄)。
1. 對於 **Choose one or more columns** (選擇一或多個資料欄)，選擇資料表的前三個資料欄。
1. 對於 **Table permissions** (資料表許可)，選擇要授予的特定存取許可。本教學課程僅授予 `SELECT` 許可；您的需求可能會有所不同。
![\[將資料表許可授予 Okta 群組。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-31b.png)
1. 選擇 **Grant** (授予)。
1. 若要確認您授予的許可，請選擇 **Actions** (動作)、**View permissions** (檢視許可)。
![\[選擇 View permissions (檢視許可) 以確認授予的許可。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-32.png)
`nyctaxi` 資料表的**資料許可**頁面會顯示 **athena-okta-user** 與 **lf-business-analyst** 群組的許可。
![\[檢視授予 Okta 使用者和群組的許可。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-33.png)
## 步驟 7：驗證透過 Athena JDBC 用戶端的存取
現在，您已經準備好使用 JDBC 用戶端，以 Okta SAML 使用者身分執行與 Athena 的測試連接。
在本節中，您需執行下列任務：
+ 準備測試用戶端 – 下載 Athena JDBC 驅動程式，安裝 SQL Workbench，然後將驅動程式新增至 Workbench。本教學課程使用 SQL Workbench 透過 Okta 身分驗證來存取 Athena，並驗證 Lake Formation 許可。
+ 在 SQL Workbench 中：
+ 為 Athena Okta 使用者建立連線。
+ 以 Athena Okta 使用者身分執行測試查詢。
+ 為業務分析師使用者建立並測試連線。
+ 在 Okta 主控台中，將業務分析師使用者新增至開發人員群組。
+ 在 Lake Formation 主控台中，設定開發人員群組的資料表許可。
+ 在 SQL Workbench 中，以業務分析師使用者身分執行測試查詢，並確認許可變更如何影響結果。
**若要準備測試用戶端**
1. 從 [使用 JDBC 連接到 Amazon Athena](connect-with-jdbc.md) 下載並解壓縮 Lake Formation 相容的 Athena JDBC 驅動程式 (2.0.14 或更高版本)。
1. 下載並安裝免費的 [SQL Workbench/J](https://www.sql-workbench.eu/index.html) SQL 查詢工具 (可在修改後的 Apache 2.0 授權下取得)。
1. 在 SQL Workbench 中，選擇 **File** (檔案)，然後選擇 **Manage Drivers** (管理驅動程式)。
![\[選擇 Manage Drivers (管理驅動程式)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-verify-access-1.png)
1. 在 **Manage Drivers** (管理驅動程式) 對話方塊中，執行以下步驟：
1. 選擇新驅動程式圖示。
1. 對於 **Name** (名稱)，輸入 **Athena**。
1. 對於 **Library** (程式庫)，瀏覽並選擇您剛下載的 Simba Athena JDBC `.jar` 檔案。
1. 選擇**確定**。
![\[將 Athena JDBC 驅動程式新增到 SQL Workbench。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-verify-access-2.png)
您現在可以開始建立並測試 Athena Okta 使用者的連線。
**若要為 Okta 使用者建立連線**
1. 依序選擇 **File** (檔案)、**Connect window** (連接視窗)。
![\[選擇 Connect window (連接視窗)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-verify-access-3.png)
1. 在 **Connection profile** (連線設定檔) 對話方塊中，輸入下列資訊來建立連線：
+ 在名稱方塊中，輸入 **Athena\$1Okta\$1User\$1Connection**。
+ 對於 **Driver** (驅動程式)，選擇 Simba Athena JDBC 驅動程式。
+ 對於 **URL**，執行下列其中一項作業：
+ 若要使用連線 URL，請輸入單行連線字串。以下範例新增了換行以方便閱讀。
```
jdbc:awsathena://AwsRegion=region-id;
S3OutputLocation=s3://amzn-s3-demo-bucket/athena_results;
AwsCredentialsProviderClass=com.simba.athena.iamsupport.plugin.OktaCredentialsProvider;
user=athena-okta-user@anycompany.com;
password=password;
idp_host=okta-idp-domain;
App_ID=okta-app-id;
SSL_Insecure=true;
LakeFormationEnabled=true;
```
+ 若要使用 AWS 設定檔型 URL，請執行下列步驟：
1. 設定具有 AWS 登入資料檔案的[AWS 設定檔](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html)，如下列範例所示。
```
[athena_lf_dev]
plugin_name=com.simba.athena.iamsupport.plugin.OktaCredentialsProvider
idp_host=okta-idp-domain
app_id=okta-app-id
uid=athena-okta-user@anycompany.com
pwd=password
```
1. 對於 **URL**，輸入單行連線字串，如下列範例所示。該範例新增了換行以方便閱讀。
```
jdbc:awsathena://AwsRegion=region-id;
S3OutputLocation=s3://amzn-s3-demo-bucket/athena_results;
profile=athena_lf_dev;
SSL_Insecure=true;
LakeFormationEnabled=true;
```
請注意，這些範例是連接至 Athena 所需的 URL 的基本表示。如需 URL 中支援的完整參數清單，請參閱 [JDBC 文件](connect-with-jdbc.md)。
下圖顯示使用連線 URL 的 SQL Workbench 連線設定檔。
![\[SQL Workbench 中的連線設定檔。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-verify-access-4.png)
現在您已經為 Okta 使用者建立了連線，您可以擷取一些資料來進行測試。
**若要測試 Okta 使用者的連線**
1. 選擇 **Test** (測試)，然後確認連線成功。
1. 從 SQL Workbench **Statement** (陳述式) 視窗中，執行下列 SQL `DESCRIBE` 命令。確認已顯示所有資料欄。
```
DESCRIBE "tripdb"."nyctaxi"
```
![\[已顯示所有資料欄。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-verify-access-5.png)
1. 從 SQL Workbench **Statement** (陳述式) 視窗中，執行下列 SQL `SELECT` 命令。確認已顯示所有資料欄。
```
SELECT * FROM tripdb.nyctaxi LIMIT 5
```
![\[確認已顯示所有資料欄。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-verify-access-6.png)
接下來，您需確認 **athena-ba-user** (**lf-business-analyst** 群組的成員) 只能存取您先前在 Lake Formation 中指定之資料表的前三個資料欄。
**若要確認 **athena-ba-user** 的存取權限**
1. 在 SQL Workbench 的 **Connection profile** (連線設定檔) 對話方塊中，建立另一個連線設定檔。
+ 對於連線設定檔名稱，輸入 ** Athena\$1Okta\$1Group\$1Connection**。
+ 對於 **Driver** (驅動程式)，選擇 Simba Athena JDBC 驅動程式。
+ 對於 **URL**，執行下列其中一項作業：
+ 若要使用連線 URL，請輸入單行連線字串。以下範例新增了換行以方便閱讀。
```
jdbc:awsathena://AwsRegion=region-id;
S3OutputLocation=s3://amzn-s3-demo-bucket/athena_results;
AwsCredentialsProviderClass=com.simba.athena.iamsupport.plugin.OktaCredentialsProvider;
user=athena-ba-user@anycompany.com;
password=password;
idp_host=okta-idp-domain;
App_ID=okta-application-id;
SSL_Insecure=true;
LakeFormationEnabled=true;
```
+ 若要使用 AWS 設定檔型 URL，請執行下列步驟：
1. 設定具有登入資料檔案的 AWS 設定檔，如下列範例所示。
```
[athena_lf_ba]
plugin_name=com.simba.athena.iamsupport.plugin.OktaCredentialsProvider
idp_host=okta-idp-domain
app_id=okta-application-id
uid=athena-ba-user@anycompany.com
pwd=password
```
1. 對於 **URL**，輸入單行連線字串，如下所示。該範例新增了換行以方便閱讀。
```
jdbc:awsathena://AwsRegion=region-id;
S3OutputLocation=s3://amzn-s3-demo-bucket/athena_results;
profile=athena_lf_ba;
SSL_Insecure=true;
LakeFormationEnabled=true;
```
1. 選擇 **Test** (測試) 以確認連線是否成功。
1. 從 **SQL Statement** (SQL 陳述式) 視窗中，執行與您之前執行相同的 `DESCRIBE` 和 `SELECT` SQL 命令並檢查結果。
由於 **athena-ba-user** 是 **lf-business-analyst** 群組的成員，只會傳回您在 Lake Formation 主控台中指定的前三個資料欄。
![\[只會傳回前三個資料欄。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-verify-access-7.png)
![\[來自前三個資料欄的資料。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-verify-access-8.png)
接下來，您需返回 Okta 主控台，將 `athena-ba-user` 新增至 `lf-developer` Okta 群組。
**若要將 athena-ba-user 新增至 lf-developer 群組**
1. 以指派的 Okta 網域的管理使用者身分登入 Okta 主控台。
1. 選擇 **Directory** (目錄)，然後選擇 **Groups** (群組)。
1. 在 Groups (群組) 頁面上，選擇 **lf-developer** 群組。
![\[選擇 lf-developer 群組。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-verify-access-9.png)
1. 選擇 **Manage People** (管理人員)。
1. 從 **Not Members** (非成員) 清單中，選擇 **athena-ba-user**，將其新增至 **lf-developer** 群組。
1. 選擇**儲存**。
現在請返回 Lake Formation 主控台來設定 **lf-developer** 群組的資料表許可。
**若要為 lf-developer-group 設定資料表許可**
1. 以資料湖管理員身分登入 Lake Formation 主控台。
1. 在導覽窗格中，選擇 **Tables** (資料表)。
1. 選取 **nyctaxi** 資料表。
1. 依序選擇 **Actions** (動作) 和 **Grant** (授予)。
1. 在 **Grant Permissions** (授予許可) 對話方塊中，輸入下列資訊：
+ 針對 **SAML 和 Amazon Quick 使用者和群組**，以下列格式輸入 Okta SAML lf-developer 群組 ARN：
+ 對於 **Columns** (資料欄)、**Choose filter type** (選擇篩選條件類型)，選擇 **Include columns** (包含資料欄)。
+ 選擇 **trip\$1type** 資料欄。
+ 對於 **Table permissions** (資料表許可)，選擇 **SELECT** (選取)。
1. 選擇 **Grant** (授予)。
現在，您可以使用 SQL Workbench 來驗證 **lf-developer** 群組的許可變更。變更應反映在 **athena-ba-user** (現在是 **lf-developer** 群組的成員) 可用的資料中。
**若要驗證 athena-ba-user 許可的變更**
1. 關閉 SQL Workbench 程式，然後再重新開啟。
1. 連接至 **athena-ba-user** 的設定檔。
1. 從 **Statement** (陳述式) 視窗中，發出您先前執行的相同 SQL 陳述式：
這一次將會顯示 **trip\$1type** 資料欄。
![\[第四個資料欄可用於查詢。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-verify-access-10.png)
由於 **athena-ba-user** 現在是 **lf-developer** 和 **lf-business-analyst** 群組的成員，這些群組的 Lake Formation 許可的組合會決定傳回的資料欄。
![\[資料結果中的第四個資料欄。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/security-athena-lake-formation-jdbc-okta-tutorial-verify-access-11.png)
## 結論
在本教學課程中，您將 Athena 整合設定為 AWS Lake Formation 使用 Okta 做為 SAML 供應商。您使用 Lake Formation 和 IAM 來控制資料湖 AWS Glue 資料目錄中 SAML 使用者可用的資源。
## 相關資源
如需相關資訊，請參閱下列資源。
+ [使用 JDBC 連接到 Amazon Athena](connect-with-jdbc.md)
+ [啟用對 Athena API 的聯合存取](access-federation-saml.md)
+ [AWS Lake Formation 開發人員指南](https://docs.aws.amazon.com/lake-formation/latest/dg/)
+ 《AWS Lake Formation 開發人員指南》**中的[授予和撤銷資料目錄許可](https://docs.aws.amazon.com/lake-formation/latest/dg/granting-catalog-permissions.html)。
+ 《IAM 使用者指南》**中的身分提供者[身分提供者與聯合](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html)。
+ 《IAM 使用者指南》**中的[建立 IAM SAML 身分提供者](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html)。
+ *AWS 安全部落格*上的[啟用聯合 AWS 使用 Windows Active Directory、ADFS 和 SAML 2.0。](https://aws.amazon.com/blogs/security/enabling-federation-to-aws-using-windows-active-directory-adfs-and-saml-2-0/)
# 工作負載管理
您可以使用 Athena 的工作群組、容量管理、效能調校、壓縮支援、標籤和服務配額功能來管理工作負載。
**Topics**
+ [使用工作群組來控制查詢存取和成本](workgroups-manage-queries-control-costs.md)
+ [管理查詢處理容量](capacity-management.md)
+ [最佳化 Athena 效能](performance-tuning.md)
+ [在 Athena 中使用壓縮](compression-formats.md)
+ [標記 Athena 資源](tags.md)
+ [Service Quotas](service-limits.md)
# 使用工作群組來控制查詢存取和成本
您可以使用 Athena 工作群組來分隔工作負載、控制團隊存取權、強制執行組態，以及追蹤查詢指標和控制成本。
**分隔工作負載**
您可以使用工作群組來分隔工作負載。例如，您可以建立兩個獨立工作群組，一個用於自動排定的應用程式，例如產生報告，另一個供分析師臨時使用。
**控制團隊存取權**
因為工作群組扮演 IAM 資源的角色，所以您可以使用資源層級的身分型政策，控制可存取工作群組並在其中執行查詢的人員。若要隔離組織中兩個不同團隊的查詢，您可以為每個團隊建立單獨的工作群組。每個工作群組都有其自己的查詢歷史記錄以及該工作群組中的查詢的易儲存查詢的清單，而不是針對帳戶中的所有查詢。如需詳細資訊，請參閱[使用 IAM 政策來控制工作群組存取](workgroups-iam-policy.md)。
**強制執行組態**
您可以選擇性地對該工作群組中執行的所有查詢強制執行相同的工作群組整體設定。這些設定包含 Amazon S3 中查詢結果的位置、預期的儲存貯體擁有者、加密和對寫入查詢結果儲存貯體之物件的控制。如需詳細資訊，請參閱[Override client-side settings (覆寫用戶端設定)](workgroups-settings-override.md)。
**追蹤查詢指標、查詢事件和控制成本**
若要追蹤每個 Athena 工作群組的查詢指標、查詢事件和控制成本，您可以使用下列功能：
+ **發布查詢指標** – 將工作群組的查詢指標發布至 CloudWatch。在 Athena 主控台中，您可以檢視每個工作群組的查詢指標。在 CloudWatch 中，您可以建立自訂儀表板，並針對這些指標設定閾值和警示。如需詳細資訊，請參閱[在 Athena 中啟用 CloudWatch 查詢指標](athena-cloudwatch-metrics-enable.md)及[使用 CloudWatch 監控 Athena 查詢指標](query-metrics-viewing.md)。
+ **監控 Athena 用量指標** – 透過在 CloudWatch 圖表和儀表板上顯示您目前的服務用量，了解您的帳戶如何使用資源。如需詳細資訊，請參閱[使用 CloudWatch 監控 Athena 用量指標](monitoring-athena-usage-metrics.md)
+ **監控查詢事件** – 使用 Amazon EventBridge 來接收查詢狀態的即時通知。如需詳細資訊，請參閱[使用 EventBridge 監控 Athena 查詢事件](athena-events.md)。
+ **建立資料用量控制** – 在 Athena 中，您可以設定每一查詢和每一工作群組資料用量控制。Athena 會在超過指定閾值時取消查詢，或在超過工作群組閾值時啟用 Amazon SNS 警示。如需詳細資訊，請參閱[設定每一查詢和每一工作群組資料用量控制](workgroups-setting-control-limits-cloudwatch.md)。
+ **使用成本分配標籤** – 使用帳單和成本管理主控台為工作群組加上成本分配標籤。與工作群組中執行查詢相關聯的成本會在成本和用量報告中顯示，並具有相應的成本分配標籤。如需詳細資訊，請參閱《AWS Billing 使用者指南**》中的[使用使用者定義的成本分配標籤](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/custom-tags.html)。
+ **使用容量保留** – 您可以使用指定的資料處理單位數目來建立容量保留，並將一或多個工作群組新增至保留。如需詳細資訊，請參閱[管理查詢處理容量](capacity-management.md)。
如需有關使用 Athena 工作群組分隔工作負載、控制使用者存取和管理查詢用量和成本的其他資訊，請參閱 AWS 大數據部落格文章[使用 Amazon Athena 工作群組分隔查詢和管理成本](https://aws.amazon.com/blogs/big-data/separating-queries-and-managing-costs-using-amazon-athena-workgroups/)。
**注意**
Amazon Athena 資源現可在 Amazon SageMaker Unified Studio (預覽版) 內進行存取，如此可協助您存取組織的資料，並使用最佳工具對其採取行動。您可以將儲存的查詢從 Athena 工作群組移轉至 SageMaker Unified Studio 專案、使用現有的 Athena 工作群組設定專案，以及透過 IAM 角色更新維護必要許可。如需詳細資訊，請參閱[將 Amazon Athena 資源移轉至 Amazon SageMaker Unified Studio (預覽版)](https://github.com/aws/Unified-Studio-for-Amazon-Sagemaker/tree/main/migration/athena)。
## 考量和限制
當您在 Athena 中使用工作群組時，請謹記以下幾點：
+ 每個帳戶都有一個主要工作群組。在預設情況下，如果您尚未建立任何工作群組，則您帳戶中的所有查詢會在主要工作群組中執行。無法刪除主要工作群組。預設許可允許所有已驗證身分的使用者存取該工作群組。
+ 當您能夠存取工作群組時，您可以檢視工作群組的設定、指標和資料用量控制限制。利用額外的許可，您可以編輯設定和資料用量控制限制。
+ 當您執行查詢時，它們會在目前工作群組中執行。您可以在主控台中，透過 API 操作、命令列介面或使用 JDBC 或 ODBC 驅動器的用戶端應用程式，在工作群組的內容中執行查詢。
+ 在 Athena 主控台查詢編輯器中，每個工作群組最多可開啟十個查詢索引標籤。在工作群組之間切換時，您的查詢索引標籤最多可以在三個工作群組中保持開啟。
+ AWS 區域 您帳戶中的每個 最多可建立 1000 個工作群組。
+ 工作群組可以停用。停用工作群組會阻止查詢在該工作群組中執行，直到您重新啟用該工作群組。
+ 如果您嘗試刪除包含已儲存查詢的工作群組，Athena 會向您發出警告。在您刪除其他使用者可存取的工作群組之前，請確保其可以存取能夠讓他們用於執行查詢的其他工作群組。
**Topics**
+ [考量和限制](#workgroups-considerations-limitations)
+ [建立工作群組](creating-workgroups.md)
+ [受管工作群組](workgroups-create-update-delete.md)
+ [使用 CloudWatch 和 EventBridge 來監控查詢](workgroups-control-limits.md)
+ [使用 Athena 工作群組 API](workgroups-api-list.md)
+ [對工作群組進行疑難排解](workgroups-troubleshooting.md)
# 建立工作群組
建立工作群組需要有執行 `CreateWorkgroup` API 動作的許可。請參閱 [設定存取工作群組和標籤](workgroups-access.md) 和 [使用 IAM 政策來控制工作群組存取](workgroups-iam-policy.md)。如果您新增標籤，您也需要將許可新增到 `TagResource`。請參閱 [工作群組的標籤政策範例](tags-access-control.md#tag-policy-examples-workgroups)。
下列程序說明如何使用 Athena 主控台來建立工作群組。若要使用 Athena API 建立工作群組，請參閱 [CreateWorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_CreateWorkGroup.html)。
**在 Athena 主控台中建立工作群組**
1. 決定建立哪些工作群組。要考量的幾個關鍵因素包括：
+ 誰可以在每個工作群組中執行查詢，以及誰擁有工作群組的組態。使用 IAM 政策來強制執行工作群組許可。如需詳細資訊，請參閱[使用 IAM 政策來控制工作群組存取](workgroups-iam-policy.md)。
+ Amazon S3 中用於存放工作群組查詢結果的位置。工作群組的所有使用者必須能夠存取這個位置。
+ 工作群組查詢結果是否必須加密。由於加密是按工作群組 (而不是按查詢) 進行的，因此您應該為加密和非加密的查詢結果建立單獨的工作群組。如需詳細資訊，請參閱[加密 Amazon S3 中存放的 Athena 查詢結果](encrypting-query-results-stored-in-s3.md)。
1. 如果未顯示主控台的導覽窗格，請選擇左側的展開選單。
![\[選擇展開選單。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/nav-pane-expansion.png)
1. 在 Athena 主控台導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 在 **Workgroups** (工作群組) 頁面中，請選擇 **Create workgroup** (建立工作群組)。
1. 在 **Create workgroup** (建立工作群組) 頁面上，如下所示填寫欄位：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/creating-workgroups.html)
1. 選擇**建立工作群組**。工作群組會出現在 **Workgroups** (工作群組) 頁面上的清單。
在查詢編輯器中，Athena 會在位於主控台右上角的**工作群組**選項中顯示目前工作群組。您可以使用此選項來切換工作群組。當您執行查詢時，它們會在目前工作群組中執行。
1. 建立 IAM 政策以允許使用者、群組或角色存取工作群組。政策建立工作群組成員資格和在 `workgroup` 資源上的動作存取權。如需詳細資訊，請參閱[使用 IAM 政策來控制工作群組存取](workgroups-iam-policy.md)。如需 JSON 政策的範例，請參閱[設定存取工作群組和標籤](workgroups-access.md)。
1. (選用) 當覆寫用戶端設定選項不會強制執行工作群組整體加密時，在 Amazon S3 中對該工作群組的所有查詢結果設定最低層級的加密。您可以使用此功能，確保查詢結果絕不會儲存在處於未加密狀態的 Amazon S3 儲存貯體中。如需詳細資訊，請參閱[為工作群組設定最低加密](workgroups-minimum-encryption.md)。
1. (選用) 使用 Amazon CloudWatch 和 Amazon EventBridge 來監控工作群組的查詢和控制成本。如需詳細資訊，請參閱[使用 CloudWatch 和 EventBridge 來監控查詢和控制成本](workgroups-control-limits.md)。
1. (選用) 使用帳單和成本管理主控台為工作群組加上成本分配標籤。如需詳細資訊，請參閱《AWS Billing 使用者指南**》中的[使用使用者定義的成本分配標籤](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/custom-tags.html)。
1. (選用) 若要取得工作群組中查詢的專用處理容量，請將該工作群組新增至容量保留。您可以將一或多個工作群組指派給預留。如需詳細資訊，請參閱[管理查詢處理容量](capacity-management.md)。
# Override client-side settings (覆寫用戶端設定)
當您建立或編輯工作群組時，您可以選擇**覆寫用戶端設定**選項。預設不會選取此選項。視您是否選取它而定，Athena 的行為如下：
+ 如果未選取**覆寫用戶端設定**，則不會在用戶端層級強制工作群組設定。當未為工作群組選取覆寫用戶端設定選項時，Athena 將對工作群組中執行的所有查詢使用用戶端的設定，包括查詢結果位置、預期的儲存貯體擁有者、加密和對寫入查詢結果儲存貯體之物件的控制等的設定。每個使用者可以在主控台的**設定**選單中指定其自己的設定。如果不設定用戶端設定，則會套用工作群組整體設定。如果您使用 AWS CLI、 API 動作或 JDBC 和 ODBC 驅動程式，在不覆寫用戶端設定的工作群組中執行查詢，您的查詢會使用您在查詢中指定的設定。
+ 如果選取**覆寫用戶端設定**，則會在工作群組層級強制工作群組中所有用戶端執行工作群組設定。當為工作群組選取覆寫用戶端設定選項時，Athena 將對工作群組中執行的所有查詢使用工作群組的設定，包括查詢結果位置、預期的儲存貯體擁有者、加密和對寫入查詢結果儲存貯體之物件的控制等的設定。當您使用主控台、API 動作或 JDBC 或 ODBC 驅動程式時，工作群組設定會覆寫您為查詢指定的任何用戶端設定。將工作群組設定設定為覆寫用戶端設定之後，可以省略驅動器或 API 中的用戶端設定。
如果您覆寫使用者端設定，則您或任何工作群組使用者下次開啟 Athena 主控台時，Athena 會向您告知此工作群組中的查詢使用工作群組的設定，並提示您確認此變更。
**注意**
由於覆寫用戶端設定可能會中斷根據任意 Amazon S3 儲存貯體中結果可用性的自訂自動化，我們建議您在覆寫之前先通知使用者。
**重要**
如果您使用 API 動作 AWS CLI、 或 JDBC 和 ODBC 驅動程式在覆寫用戶端設定的工作群組中執行查詢，請確定您省略查詢中的用戶端設定，或更新它們以符合工作群組的設定。
如果您在查詢中指定用戶端設定，但在覆寫設定的工作群組中執行這些設定，則將會使用工作群組設定執行查詢。如需有關檢視工作群組設定的資訊，請參閱 [檢視工作群組的詳細資訊](viewing-details-workgroups.md)。
# 受管工作群組
在 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 的 Athena 主控台中，您可以執行下列任務：
| 陳述式 | Description |
| --- | --- |
| [建立工作群組](creating-workgroups.md) | 建立新的工作群組。 |
| [檢視工作群組的詳細資訊](viewing-details-workgroups.md) | 檢視工作群組的詳細資訊，例如其名稱、描述、資料用量限制、查詢結果的位置、預期查詢結果儲存貯體擁有者、加密和對寫入查詢結果儲存貯體之物件的控制。如果已勾選 Override client-side settings (覆寫用戶端設定)，您也可以驗證此工作群組是否強制其設定。 |
| [指定查詢的工作群組](specify-wkgroup-to-athena-in-which-to-run-queries.md) | 您必須向 Athena 指定要使用的工作群組，才能執行查詢。您必須具有此工作群組的許可。 |
| [切換工作群組](switching-workgroups.md) | 在您可以存取的工作群組之間切換。 |
| [編輯工作群組](editing-workgroups.md) | 編輯工作群組和變更其設定。您無法變更工作群組的名稱，但可以使用相同的設定和不同的名稱來建立新的工作群組。 |
| [啟用或停用工作群組](workgroups-enabled-disabled.md) | 啟用或停用工作群組。當工作群組停用時，其使用者無法執行查詢，或建立新的具名查詢。如果您可以存取此工作群組，則您仍可以檢視指標、資料用量限制控制、工作群組的設定、查詢歷史記錄和儲存的查詢。 |
| [在工作群組之間複製儲存的查詢](copy-a-query-between-workgroups.md) | 在工作群組之間複製儲存的查詢。例如，如果您在預覽工作群組中建立了查詢，並且想要在非預覽工作群組中使用該查詢，則您可能需要執行此操作。 |
| [刪除工作群組](deleting-workgroups.md) | 刪除工作群組。如果您刪除工作群組，將會刪除查詢歷史記錄、儲存的查詢、工作群組的設定和每一查詢資料限制控制。CloudWatch 中會保留工作群組整體的資料限制控制，您可以個別刪除它們。 無法刪除主要工作群組。 |
| [使用 IAM 政策來控制工作群組存取](workgroups-iam-policy.md) | 使用 IAM 政策來控制工作群組存取權。如需工作群組政策的範例，請參閱 [工作群組政策範例](example-policies-workgroup.md)。 |
| [建立使用 IAM Identity Center 身分驗證的 Athena 工作群組](workgroups-identity-center.md) | 若要將 IAM Identity Center 身分與 Athena 搭配使用，您必須建立啟用 IAM Identity Center 的工作群組。建立工作群組後，您可以使用 IAM Identity Center 主控台或 API，將 IAM Identity Center 使用者或群組指派給工作群組。 |
| [為工作群組設定最低加密](workgroups-minimum-encryption.md) | 在 Amazon S3 對工作群組的所有查詢結果強制執行最低層級的加密。使用此功能，確保查詢結果絕不會儲存在處於未加密狀態的 Amazon S3 儲存貯體中。 |
# 檢視工作群組的詳細資訊
對於每個工作群組，您可以查看其詳細資訊。詳細資訊包括工作群組的名稱、描述、已啟用或停用，以及工作群組中執行的查詢所使用的設定，其中包括查詢結果的位置、預期的儲存貯體擁有者、加密和對寫入查詢結果儲存貯體之物件的控制。如果工作群組有資料用量限額，則也會顯示。
**若要檢視工作群組的詳細資訊**
1. 在 Athena 主控台導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 在 **Workgroups** (工作群組) 頁面上，請選擇您要檢視的工作群組連結。工作群組的 **Overview Details** (概觀詳細資料) 頁面隨即會顯示。
# 指定查詢的工作群組
若要指定使用的工作群組，您必須具有此工作群組的許可。
**指定工作群組使用**
1. 請確認您的許可允許您在您想要使用在工作群組中執行查詢。如需詳細資訊，請參閱[使用 IAM 政策來控制工作群組存取](workgroups-iam-policy.md)。
1. 若要指定工作群組，請使用以下其中一個選項：
+ 如果您正在使用 Athena 主控台，請[切換工作群組](switching-workgroups.md)來設定工作群組。
+ 如果您是使用 Athena API 操作，請在 API 動作中指定工作群組名稱。例如，您可以在 [StartQueryExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartQueryExecution.html) 中設定工作群組名稱，如下所示：
```
StartQueryExecutionRequest startQueryExecutionRequest = new StartQueryExecutionRequest()
.withQueryString(ExampleConstants.ATHENA_SAMPLE_QUERY)
.withQueryExecutionContext(queryExecutionContext)
.withWorkGroup(WorkgroupName)
```
+ 如果您是使用 JDBC 或 ODBC 驅動程式，請在連線字串中使用 `Workgroup` 組態參數來設定工作群組名稱。驅動程式會將工作群組名稱傳遞給 Athena。在連線字串中指定工作群組參數，如下列範例所示：
```
jdbc:awsathena://AwsRegion=;UID=;
PWD=;S3OutputLocation=s3://amzn-s3-demo-bucket/-/;
Workgroup=;
```
# 切換工作群組
如果您對兩個工作群組都有許可，您可以從其中一個切換到另一個。
在每個工作群組內，您最多可以開啟十個查詢索引標籤。在工作群組之間切換時，您的查詢索引標籤最多可以在三個工作群組中保持開啟。
**切換工作群組**
1. 在 Athena 主控台中，使用右上角的 **Workgroup** (工作群組) 選項選擇工作群組。
1. 如果**工作群組 *workgroup-name* 設定**對話方塊出現時，請選擇 **Acknowledge** (確認)。
**Workgroup** (工作群組) 選項會顯示您已切換到其中的工作群組名稱。您現在可以在此工作群組中執行查詢。
# 編輯工作群組
編輯工作群組需要有執行 `UpdateWorkgroup` API 操作的許可。請參閱 [設定存取工作群組和標籤](workgroups-access.md) 和 [使用 IAM 政策來控制工作群組存取](workgroups-iam-policy.md)。如果您新增或編輯標籤，您也需要有 `TagResource` 的許可。請參閱 [工作群組的標籤政策範例](tags-access-control.md#tag-policy-examples-workgroups)。
**在主控台編輯工作群組**
1. 在 Athena 主控台導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 在 **Workgroups** (工作群組) 頁面上，選取您要編輯的工作群組的按鈕。
1. 選擇 **Actions** (動作)、**Edit** (編輯)。
1. 請依需求變更欄位。關於欄位清單，請參閱[建立工作群組](creating-workgroups.md)。工作群組的名稱除外，您可以變更所有欄位。如果您需要變更名稱，請使用新的名稱和相同的設定建立另一個工作群組。
1. 選擇**儲存變更**。更新的工作群組會出現在 **Workgroups** (工作群組) 頁面上的清單。
# 啟用或停用工作群組
如果您有許可這樣做，您可以在主控台、使用 API 操作或透過 JDBC 和 ODBC 驅動程式來啟用或停用工作群組。
**若要啟用或停用工作群組**
1. 在 Athena 主控台導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 在 **Workgroups** (工作群組) 頁面上，請選擇工作群組的連結。
1. 在右上角，選擇 **Enable workgroup** (啟用工作群組) 或 **Disable workgroup** (停用工作群組)。
1. 在確認提示時，選擇 **Enable** (啟用) 或 **Disable** (停用)。如果您停用工作群組，則其使用者無法在其中執行查詢，或建立新的具名查詢。如果您啟用工作群組，使用者可以使用它來執行查詢。
# 在工作群組之間複製儲存的查詢
Athena 主控台目前沒有將儲存的查詢從某個工作群組直接複製到另一個工作群組的選項，但您可以使用下列程序手動執行相同的任務。
**若要在工作群組之間複製儲存的查詢**
1. 在 Athena 主控台中，從您想要從中複製查詢的工作群組中，選擇 **Saved queries** (儲存的查詢) 索引標籤。
1. 選擇您想要複製的已儲存查詢連結。Athena 會在查詢編輯器中開啟查詢。
1. 在查詢編輯器中，選取查詢文字，然後按下 **Ctrl\$1C** 以進行複製。
1. [切換](switching-workgroups.md)至目的地工作群組，或[建立工作群組](creating-workgroups.md)，然後切換至該工作群組。
1. 在查詢編輯器中開啟新索引標籤，然後按下 **Ctrl\$1V** 將文字貼到新索引標籤中。
1. 在查詢編輯器中，選擇 **Save as** (另存為)，將查詢儲存在目的地工作群組中。
1. 在 **Choose a name** (選擇名稱) 對話方塊中，輸入查詢的名稱和選擇性描述。
1. 選擇**儲存**。
# 刪除工作群組
如果您有許可刪除工作群組，您可以這樣做。無法刪除主要工作群組。
如有許可，您可以隨時刪除空的工作群組。您也可以刪除包含儲存的查詢的工作群組。在這種情況下，在繼續刪除工作群組之前，Athena 會警告將刪除儲存的查詢。
如果您刪除自己所在的工作群組，主控台將焦點切換到主要工作群組。如果您有它的存取權，則可以執行查詢和檢視其設定。
如果您刪除工作群組，則其設定和每一查詢資料限制控制也會刪除。CloudWatch 中會保留工作群組整體的資料限制控制，您可以視需要刪除它們。
**重要**
在刪除工作群組之前，請確定其使用者也屬於能夠讓他們繼續執行查詢的其他工作群組。如果使用者的 IAM 政策*僅*允許他們在此工作群組中執行查詢，而且您刪除此工作群組，則他們再也沒有許可來執行查詢。如需詳細資訊，請參閱[Example policy for running queries in the primary workgroup](example-policies-workgroup.md#example4-run-in-primary-access)。
**在主控台刪除工作群組**
1. 在 Athena 主控台導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 在 **Workgroups** (工作群組) 頁面上，選取您要刪除的工作群組的按鈕。
1. 選擇 **動作**、**刪除**。
1. 在 **Delete workgroup** (刪除工作群組) 確認提示中，輸入工作群組的名稱，然後選擇 **Delete** (刪除)。
若要使用 API 操作來刪除工作群組，請使用 `DeleteWorkGroup` 動作。
# 使用 CloudWatch 和 EventBridge 來監控查詢和控制成本
工作群組可讓您設定每一查詢或每一工作群組的資料用量控制限制，設定超過這些限制時的警示，以及將查詢指標發布至 CloudWatch。
在每個工作群組中，您可以：
+ 設定每一查詢和每一工作群組的 **Data usage controls (資料用量控制)**，並建立當查詢超出閾值時將採取的動作。
+ 檢視和分析查詢指標，並將其發布至 CloudWatch。如果您在主控台中建立工作群組，則系統會為您選取將指標發布至 CloudWatch 的設定。如果您使用 API 操作，您必須[啟用發布指標](athena-cloudwatch-metrics-enable.md)。發布指標時，其會顯示在 **Workgroups** (工作群組) 面板中的 **Metrics** (指標) 索引標籤。對於主要工作群組，預設會停用指標。
## 影片
下列影片說明如何在 CloudWatch 中建立自訂儀表板，以及設定指標的警示和觸發。您可以直接從 Athena 主控台使用預先填入的儀表板，以使用這些查詢指標。
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/x1V_lhkdKCg)
**Topics**
+ [影片](#athena-cloudwatch-metrics-video)
+ [啟用查詢指標](athena-cloudwatch-metrics-enable.md)
+ [使用 CloudWatch 監控查詢指標](query-metrics-viewing.md)
+ [使用 CloudWatch 監控用量指標](monitoring-athena-usage-metrics.md)
+ [使用 EventBridge 監控查詢事件](athena-events.md)
+ [設定資料用量控制](workgroups-setting-control-limits-cloudwatch.md)
# 在 Athena 中啟用 CloudWatch 查詢指標
當您在主控台中建立工作群組時，系統預設會選取將查詢指標發布至 CloudWatch 的設定。
**若要在 Athena 主控台中啟用或停用工作群組的查詢指標**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 如果未顯示主控台的導覽窗格，請選擇左側的展開選單。
![\[選擇展開選單。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/nav-pane-expansion.png)
1. 在導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 選擇您想要修改的工作群組連結。
1. 在工作群組的詳細資訊頁面上，選擇 **Edit** (編輯)。
1. 在**設定**區段中，選取或清除將**查詢指標發佈至 AWS CloudWatch**。
如果您使用 API 操作、命令列界面或具有 JDBC 驅動程式的用戶端應用程式來建立工作群組，啟用查詢指標的發布，請在 [WorkGroupConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroupConfiguration.html) 中將 `PublishCloudWatchMetricsEnabled` 設定為 `true`。以下範例只顯示指標組態，而省略其他組態：
```
"WorkGroupConfiguration": {
"PublishCloudWatchMetricsEnabled": "true"
....
}
```
# 使用 CloudWatch 監控 Athena 查詢指標
當已選取 [publish query metrics to CloudWatch](athena-cloudwatch-metrics-enable.md) (將查詢指標發布至 CloudWatch) 選項時，Athena 會將查詢相關指標發布至 Amazon CloudWatch。您可以建立自訂儀表板，在 CloudWatch 中設定指標的警示和觸發，或直接從 Athena 主控台使用預先填入的儀表板。
當您為工作群組中的查詢啟用查詢指標時，Athena 主控台中每個工作群組的指標會顯示在 **Workgroups** (工作群組) 面板中的 **Metrics** (指標) 索引標籤中。
Athena 會將以下指標發布至 CloudWatch 主控台：
+ `DPUAllocated` – 在容量保留中佈建的用於執行查詢的 DPU (資料處理單位) 總數。
+ `DPUConsumed` – 在指定的時間，容量保留中處於 `RUNNING` 狀態的查詢主動使用的 DPU 數目。僅當工作群組與容量保留相關聯，並包含與保留關聯的所有工作群組時，才會發出指標。
+ `DPUCount` – 查詢使用的 DPU 數目上限，僅當查詢完成時發布一次。
+ `EngineExecutionTime` – 執行查詢所花費的毫秒數。
+ `ProcessedBytes` – Athena 在每次 DML 查詢所掃描的位元組。
+ `QueryPlanningTime` – Athena 規劃查詢處理流程所花費的毫秒數。
+ `QueryQueueTime` – 查詢在查詢佇列中等待資源的毫秒數。
+ `ServicePreProcessingTime` – 提交查詢至查詢引擎之前，Athena 預先處理查詢所花費的毫秒數。
+ `ServiceProcessingTime` – 查詢引擎完成查詢的執行後，Athena 處理查詢結果所花費的毫秒數。
+ `TotalExecutionTime` – Athena 執行 DDL 或 DML 查詢所花費的毫秒數。
如需更完整的描述，請參閱本文件稍後的 [Athena 的 CloudWatch 指標和維度清單](#athena-cloudwatch-metrics-table)。
這些指標具有下列維度：
+ `CapacityReservation`– 用於執行查詢的容量保留名稱 (如果適用)。
+ `QueryState` – `SUCCEEDED`、`FAILED` 或 `CANCELED`
+ `QueryType` – `DML`、`DDL` 或 `UTILITY`
+ `WorkGroup` – 工作群組的名稱
Athena 會將以下指標發布至 `AmazonAthenaForApacheSpark` 命名空間下的 CloudWatch 主控台：
+ `DPUCount` – 工作階段期間用來執行計算所消耗的 DPU 數目。
該指標具有下列兩個維度：
+ `SessionId` – 要提交計算的工作階段 ID。
+ `WorkGroup` – 工作群組的名稱。
如需詳細資訊，請參閱本主題稍後的[Athena 的 CloudWatch 指標和維度清單](#athena-cloudwatch-metrics-table)。如需有關 Athena 用量指標的資訊，請參閱[使用 CloudWatch 監控 Athena 用量指標](monitoring-athena-usage-metrics.md)。
您可以在 Athena 主控台或 CloudWatch 主控台中檢視查詢指標。
## 在 Athena 主控台中檢視查詢指標
**在 Athena 主控台中檢視工作群組的查詢指標**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 如果未顯示主控台的導覽窗格，請選擇左側的展開選單。
![\[選擇展開選單。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/nav-pane-expansion.png)
1. 在導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 從清單中選擇所需的工作群組，然後選擇 **Metrics** (指標) 索引標籤。
指標儀表板隨即顯示。
**注意**
如果您最近剛啟用工作群組的指標，且/或最近沒有任何查詢活動，儀表板上的圖形可能會是空白的狀態。系統會根據您在下一個步驟中指定的間隔，從 CloudWatch 擷取查詢活動。
1. 在 **Metrics** (指標) 區段中，選擇 Athena 應用來從 CloudWatch 擷取查詢指標的指標間隔，或指定自訂間隔。
![\[指定 Athena 主控台中工作群組的指標擷取間隔。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/wg-custom-interval.png)
1. 若要重新整理顯示的指標，請選擇重新整理圖示。
![\[選擇重新整理圖示。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/wg-refresh-metrics.png)
1. 按一下重新整理圖示旁的箭頭，以選擇您希望指標顯示的更新頻率。
![\[選擇 Athena 主控台中工作群組指標顯示的重新整理間隔。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/wg-choose-refresh-interval.png)
## 在 CloudWatch 主控台中檢視查詢指標
**若要在 Amazon CloudWatch 主控台中檢視指標**
1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 在導覽窗格中，選擇 **Metrics** (指標)、**All metrics** (所有指標)。
1. 選取 **AWS/Athena** 命名空間。
## 使用 檢視查詢指標 AWS CLI
**使用 檢視指標 AWS CLI**
+ 執行以下任意一項：
+ 若要列出 Athena 的指標，請開啟命令提示，然後使用下列命令：
```
aws cloudwatch list-metrics --namespace "AWS/Athena"
```
+ 若要列出所有可用的指標，請使用以下命令：
```
aws cloudwatch list-metrics"
```
## Athena 的 CloudWatch 指標和維度清單
如果您已在 Athena 中啟用 CloudWatch 指標，其會按照工作群組將以下指標傳送到 CloudWatch。下列指標使用 `AWS/Athena` 命名空間。
| 指標名稱 | Description |
| --- | --- |
| DPUAllocated | 在容量保留中佈建的用於執行查詢的 DPU (資料處理單位) 總數。 |
| DPUConsumed | 在給定的時間，保留區中處於 RUNNING 狀態的查詢主動使用的 DPU 數目。僅當工作群組與容量保留相關聯並包含與保留關聯的所有工作群組時，才會發出這個指標。如果您將工作群組從一個保留區移至另一個保留區，則該指標會包含該工作群組屬於第一個保留區時的資料。如需有關容量保留的詳細資訊，請參閱 [管理查詢處理容量](capacity-management.md)。 |
| DPUCount | 查詢使用的 DPU 數目上限，僅當查詢完成時發布一次。只有附加至容量保留的工作群組才會發出此指標。 |
| EngineExecutionTime | 查詢執行所花費的毫秒數。 |
| ProcessedBytes | Athena 在每次 DML 查詢所掃描的位元組。對於取消的查詢 (無論是由使用者取消，或達到上限時自動取消)，這包括取消前掃描的資料量。DDL 查詢不會報告此指標。 |
| QueryPlanningTime | Athena 規劃查詢處理流程所花費的毫秒數。這包括從資料來源擷取資料表分割區所花費的時間。請注意，因為查詢引擎會執行查詢規劃，所以查詢規劃時間是 EngineExecutionTime 的子集。 |
| QueryQueueTime | 查詢在查詢佇列中等待資源的毫秒數。請注意，如果發生暫時性錯誤，查詢可能自動加回到佇列。 |
| ServicePreProcessingTime | 提交查詢至查詢引擎之前，Athena 預先處理查詢所花費的毫秒數。 |
| ServiceProcessingTime | 查詢引擎完成查詢的執行後，Athena 處理查詢結果所花費的毫秒數。 |
| TotalExecutionTime | Athena 執行 DDL 或 DML 查詢所花費的毫秒數。TotalExecutionTime 包括 QueryQueueTime、QueryPlanningTime、EngineExecutionTime 和 ServiceProcessingTime。 |
Athena 的這些指標具有下列維度。
| 維度 | Description |
| --- | --- |
| CapacityReservation | 用於執行查詢的容量保留名稱 (如果適用)。當未使用容量保留時，此維度不會傳回任何資料。 |
| QueryState | 查詢狀態。 有效的統計資訊：已成功、已失敗、已取消。 |
| QueryType | 查詢類型。 有效的統計資訊：`DDL`、`DML` 或 `UTILITY`。執行的查詢陳述式類型。`DDL` 表示 DDL (資料定義語言) 查詢陳述式。`DML` 表示 DML (資料處理語言) 查詢陳述式，例如 `CREATE TABLE AS SELECT`。`UTILITY` 表示除 DDL 和 DML 以外的查詢陳述式，例如 `SHOW CREATE TABLE` 或 `DESCRIBE TABLE`。 |
| WorkGroup | 工作群組的名稱。 |
# 使用 CloudWatch 監控 Athena 用量指標
您可使用 CloudWatch 用量指標，透過在 CloudWatch 圖表和儀表板中顯示目前的服務使用量狀況，瞭解您的帳戶如何使用資源。
對於 Athena，用量可用性指標對應至 Athena AWS 服務 的配額。您可以設定警示，在您的用量接近服務配額時發出警示。如需有關 Athena 服務配額的詳細資訊，請參閱[Service Quotas](service-limits.md)。如需 AWS 用量指標的詳細資訊，請參閱《*Amazon CloudWatch 使用者指南*》中的[AWS 用量指標](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Service-Quota-Integration.html)。
Athena 在 `AWS/Usage` 命名空間中發布下列指標。
| 指標名稱 | Description |
| --- | --- |
| `ResourceCount` | AWS 區域 每個帳戶所有佇列和執行查詢的總和，依查詢類型 (DML 或 DDL) 分隔。此指標唯一實用的統計資料是「上限」。 此指標每分鐘定期發布一次。如果您沒有執行任何查詢，則指標不會報告任何內容 (甚至不會報告 0)。僅當採用指標時正在執行啟用查詢時，指標才會發布。 |
下列維度用於強化 Athena 所發布的用量指標。
| 維度 | Description |
| --- | --- |
| `Service` | AWS 服務 包含資源的 名稱。對 Athena 而言，此維度的數值為 `Athena`。 |
| `Resource` | 正在執行的資源類型。Athena 查詢用量的資源值為 `ActiveQueryCount`。 |
| `Type` | 正在報告的實體類型。目前，Athena 用量指標的唯一有效值為 `Resource`。 |
| `Class` | 正在追蹤的資源類別。對 Athena 而言，`Class` 可以是 `DML` 或 `DDL`。 |
## 在 CloudWatch 主控台中檢視 Athena 資源用量指標
您可以使用 CloudWatch 主控台查看 Athena 用量指標圖表，並設定警示在用量接近服務配額時提醒您。
**檢視 Athena 資源用量指標**
1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 在導覽窗格中，選擇 **Metrics** (指標)、**All metrics** (所有指標)。
1. 選擇**用量**，然後選擇**依據 AWS 資源**。
服務配額用量指標清單隨即出現。
1. 選取 **Athena** 和 **ActiveQueryCount** 旁的核取方塊。
1. 選擇 **Graphed metrics (圖表化指標)** 標籤。
上圖顯示資源的目前用量 AWS 。
如需了解如何將服務配額新增至圖表，以及設定警示，讓系統在用量接近服務配額時通知您，請參閱*《Amazon CloudWatch 使用者指南》*中[視覺化您的服務配額和設定警示](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Quotas-Visualize-Alarms.html)。如需設定每個工作群組用量限制的詳細資訊，請參閱 [設定每一查詢和每一工作群組資料用量控制](workgroups-setting-control-limits-cloudwatch.md)。
# 使用 EventBridge 監控 Athena 查詢事件
您可以搭配使用 Amazon EventBridge 與 Amazon Athena，以接收有關查詢狀態的即時通知。當您提交的查詢轉換狀態時，Athena 會將事件發布至 EventBridge，當中包含該查詢狀態轉換的相關資訊。您可以針對感興趣的事件撰寫簡單的規則，並在事件符合規則時採取自動化動作。例如，您可以建立規則，在查詢達到終端狀態時叫用 AWS Lambda 函數。盡可能發出事件。
在您為 Athena 建立事件規則之前，請執行下列動作：
+ 熟悉 Eventbridge 中的事件、規則和目標。如需詳細資訊，請參閱[什麼是 Amazon EventBridge？](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) 如需有關如何設定規則的詳細資訊，請參閱 [Amazon EventBridge 入門](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html)。
+ 建立要在事件規則中使用的一或多個目標。
**注意**
Athena 目前提供一種事件類型 (Athena 查詢狀態變更)，但可能會新增其他事件類型和詳細資訊。如果您是透過程式設計方式將事件 JSON 資料還原序列化，請確定您的應用程式在新增這些額外屬性時已準備好處理不明屬性。
## Athena 事件格式
以下是 Amazon Athena 事件的基本模式。
```
{
"source":[
"aws.athena"
],
"detail-type":[
"Athena Query State Change"
],
"detail":{
"currentState":[
"SUCCEEDED"
]
}
}
```
## Athena 查詢狀態變更事件
下列範例會顯示 `currentState` 值為 `SUCCEEDED` 的 Athena 狀態變更事件。
```
{
"version":"0",
"id":"abcdef00-1234-5678-9abc-def012345678",
"detail-type":"Athena Query State Change",
"source":"aws.athena",
"account":"123456789012",
"time":"2019-10-06T09:30:10Z",
"region":"us-east-1",
"resources":[
],
"detail":{
"versionId":"0",
"currentState":"SUCCEEDED",
"previousState":"RUNNING",
"statementType":"DDL",
"queryExecutionId":"01234567-0123-0123-0123-012345678901",
"workgroupName":"primary",
"sequenceNumber":"3"
}
}
```
下列範例會顯示 `currentState` 值為 `FAILED` 的 Athena 狀態變更事件。只有在 `currentState` 為 `FAILED` 時，才會顯示 `athenaError` 區塊。如需有關 `errorCategory` 和 `errorType` 值的詳細資訊，請參閱 [Athena 錯誤目錄](error-reference.md)。
```
{
"version":"0",
"id":"abcdef00-1234-5678-9abc-def012345678",
"detail-type":"Athena Query State Change",
"source":"aws.athena",
"account":"123456789012",
"time":"2019-10-06T09:30:10Z",
"region":"us-east-1",
"resources":[
],
"detail":{
"athenaError": {
"errorCategory": 2.0, //Value depends on nature of exception
"errorType": 1306.0, //Type depends on nature of exception
"errorMessage": "Amazon S3 bucket not found", //Message depends on nature of exception
"retryable":false //Retryable value depends on nature of exception
},
"versionId":"0",
"currentState": "FAILED",
"previousState": "RUNNING",
"statementType":"DML",
"queryExecutionId":"01234567-0123-0123-0123-012345678901",
"workgroupName":"primary",
"sequenceNumber":"3"
}
}
```
### 輸出屬性
JSON 輸出包含以下屬性。
****
| 屬性 | Description |
| --- | --- |
| athenaError | 只有在 currentState 為 FAILED 時才會顯示。包含發生之錯誤的相關資訊，包括錯誤類別、錯誤類型、錯誤訊息，以及是否可以重試導致錯誤的動作。每個欄位的值視錯誤性質而定。如需有關 errorCategory 和 errorType 值的詳細資訊，請參閱 [Athena 錯誤目錄](error-reference.md)。 |
| versionId | 詳細資訊物件之結構描述的版本號碼。 |
| currentState | 在事件發生時查詢所轉換成的狀態。 |
| previousState | 在事件發生時查詢從其轉換的狀態。 |
| statementType | 執行的查詢陳述式類型。 |
| queryExecutionId | 查詢執行的唯一識別碼。 |
| workgroupName | 執行查詢的工作群組名稱。 |
| sequenceNumber | 單調遞增的數字，允許刪除重複和排序涉及所執行單一查詢的傳入事件。當針對相同的狀態轉換發布重複事件時，sequenceNumber 值是相同的。當查詢經歷一次以上的狀態轉換時 (例如遇到鮮少列入佇列的查詢)，您可以使用 sequenceNumber 來排序 currentState 和 previousState 值相同的事件。 |
## 範例
下列範例會將事件發布至您已訂閱的 Amazon SNS 主題。查詢 Athena 時，您會收到一封電子郵件。該範例假設 Amazon SNS 主題存在且您已訂閱該主題。
**若要將 Athena 事件發布至 Amazon SNS 主題**
1. 建立 Amazon SNS 主題的目標。授予 EventBridge 事件服務主體發布至 Amazon SNS 主題的 `events.amazonaws.com` 許可，如下列範例所示。
```
{
"Effect":"Allow",
"Principal":{
"Service":"events.amazonaws.com"
},
"Action":"sns:Publish",
"Resource":"arn:aws:sns:us-east-1:111111111111:your-sns-topic"
}
```
1. 使用 AWS CLI `events put-rule`命令來建立 Athena 事件的規則，如下列範例所示。
```
aws events put-rule --name {ruleName} --event-pattern '{"source": ["aws.athena"]}'
```
1. 使用 AWS CLI `events put-targets`命令將 Amazon SNS 主題目標連接至規則，如下列範例所示。
```
aws events put-targets --rule {ruleName} --targets Id=1,Arn=arn:aws:sns:us-east-1:111111111111:your-sns-topic
```
1. 查詢 Athena 並觀察被叫用的目標。您應該會收到來自該 Amazon SNS 主題的相應電子郵件。
## AWS 使用者通知 搭配 Amazon Athena 使用
您可使用 [AWS 使用者通知](https://docs.aws.amazon.com/notifications/latest/userguide/what-is.html) 來設定交付管道，以取得有關 Amazon Athena 事件的通知。當事件符合您指定的規則時，便會收到通知。您可以透過多個管道接收事件通知，包括電子郵件、[聊天應用程式中的 Amazon Q Developer](https://docs.aws.amazon.com/chatbot/latest/adminguide/what-is.html) 聊天通知或 [AWS Console Mobile Application](https://docs.aws.amazon.com/consolemobileapp/latest/userguide/what-is-consolemobileapp.html) 推送通知。您也可以在[主控台通知中心](https://console.aws.amazon.com/notifications/)查看通知。 使用者通知 支援彙總，這可以減少您在特定事件期間收到的通知數量。
如需詳細資訊，請參閱[「*AWS 使用者通知 使用者指南」*](https://docs.aws.amazon.com/notifications/latest/userguide/what-is.html)。
# 設定每一查詢和每一工作群組資料用量控制
Athena 可讓您設定兩種類型的成本控制：每一查詢限制和每一工作群組限制。對於每個工作群組，您只能設定一個每一查詢限制和多個每一工作群組限制。
+ **每一查詢控制限制**指定每次查詢所掃描的資料總量。如果工作群組中執行的任何查詢超過此限制，則會取消。您在工作群組中只能建立一個每一查詢控制限制，它會套用到其中執行的每個查詢。如果您需要變更限制，請編輯限制。如需詳細步驟，請參閱[建立每一查詢資料用量控制](#configure-control-limit-per-query)。
+ **工作群組整體資料用量控制限制**指定在指定期間內針對此工作群組中執行的所有查詢所掃描的資料總量。您可以為每一工作群組建立多個限制。工作群組整體查詢限制可讓您針對工作群組中執行的查詢所掃描的資料，在每小時或每日彙總上設定多個閾值。
如果掃描的資料總量超過閾值，您可以將通知推送至 Amazon SNS 主題。若要這麼做，請在 Athena 主控台中設定 Amazon SNS 警示和動作，以便在超過限制時通知管理員。如需詳細步驟，請參閱[建立每一工作群組資料用量控制](#configure-control-limit-per-workgroup)。對於 Athena 從 CloudWatch 主控台發布的任何指標，您也可以建立警示和動作。例如，您可以對失敗的查詢次數設定提醒。如果次數超過特定閾值，這個提醒可以觸發將電子郵件寄給管理員。如果超過限制，將會有動作將 Amazon SNS 警示通知傳送給指定的使用者。
您可以採取的其他動作：
+ 調用 Lambda 函數。如需詳細資訊，請參閱《Amazon Simple Notification Service 開發人員指南》**中的[使用 Amazon SNS 通知叫用 Lambda 函數](https://docs.aws.amazon.com/sns/latest/dg/sns-lambda-as-subscriber.html)。
+ 停用工作群組，以停止執行任何進一步的查詢。如需這些步驟，請參閱 [啟用或停用工作群組](workgroups-enabled-disabled.md)。
每一查詢限制和每一工作群組限制彼此獨立。每當超過任一限制時就會採取指定的動作。如果兩個或更多使用者在同一個工作群組中同時執行查詢，則可能每個查詢都不超過任何指定的限制，但掃描的資料總數超過每一工作群組的資料用量限制。在這種情況下，Amazon SNS 警示會傳送給使用者。
## 建立每一查詢資料用量控制
**建立每一查詢資料用量控制**
每一查詢控制限制指定每次查詢所掃描的資料總量。如果工作群組中執行的任何查詢超過此限制，則會取消。已取消的查詢會按照 [Amazon Athena 定價](https://aws.amazon.com/athena/pricing/)計費。
**注意**
如果是已取消或失敗的查詢，Athena 可能已將局部結果寫入 Amazon S3。在這種情況下，Athena 不會從存放結果的 Amazon S3 字首中刪除這些局部結果。您必須移除含有局部結果的 Amazon S3 字首。Athena 使用 Amazon S3 分段上傳，將資料寫入 Amazon S3。我們建議您設定儲存貯體生命週期政策，指定當查詢失敗時結束分段上傳。如需詳細資訊，請參閱《Amazon Simple Storage Service 使用者指南》**中的[使用儲存貯體生命週期政策中止未完成的分段上傳](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html#mpu-abort-incomplete-mpu-lifecycle-config)。
在某些情況下，Athena 可能會自動重試查詢執行。在大多數情況下，這些查詢能夠成功完成，且查詢 ID 會標記為 `Completed`。這些查詢可能在初始嘗試期間已寫入部分結果，並可能產生未完成的分段上傳。
您在工作群組中只能建立一個每一查詢控制限制，它會套用到其中執行的每個查詢。如果您需要變更限制，請編輯限制。
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 在導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 從清單中選擇工作群組名稱。
1. 在**執行控制項**索引標籤上，選擇**編輯控制項**。
1. 編輯**資料掃描限制**的值。
+ 指定介於 10 MB （最小值） 和 7 EB （最大值） 之間的值。
+ 從下拉式清單中選取單位值 （例如 **Kilobytes KB** 或 **Exabytes EB**)。
**注意**
預設動作是在查詢超過限制時取消查詢。此設定無法變更。
1. 選擇**儲存**以立即套用您的變更。
## 建立或編輯每一工作群組資料用量提醒
**建立或編輯每一工作群組資料用量提醒**
當工作群組中執行的查詢在特定時段內掃描指定數量的資料時，您可以設定多個提醒閾值。提醒會透過 Amazon CloudWatch 警示實作，並套用於工作群組中的所有查詢。達到閾值後，您可以讓 Amazon SNS 向您指定的使用者傳送電子郵件。達到閾值時，查詢作業不會自動取消。
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 如果未顯示主控台的導覽窗格，請選擇左側的展開選單。
1. 在導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 從清單中選擇工作群組名稱。
1. 選擇 **Edit** (編輯) 以編輯工作群組的設定。
1. 向下捲動到並展開 **Workgroup data usage alerts - optional** (工作群組資料用量提醒 - 選用)。
1. 選擇 **Add alert** (新增提醒)。
1. 針對 **Data usage threshold configuration** (資料用量閾值組態)，指定值，如下所示：
+ 針對 **Data threshold** (資料閾值)，指定數字，然後從下拉式清單中選取單位值。
+ 對於 **Time period** (期間)，請從下拉式清單中選擇期間。
+ 針對 **SNS topic selection** (SNS 主題選擇)，請從下拉式清單中選擇 Amazon SNS 主題。或者，選擇 **Create SNS topic** (建立 SNS 主題)，直接前往 [Amazon SNS 主控台](https://console.aws.amazon.com/sns/v2/home)，建立 Amazon SNS 主題，並為 Athena 帳戶中的其中一個使用者設定主題訂閱。如需詳細資訊，請參閱《Amazon Simple Notification Service 開發人員指南》**中的 [Amazon SNS 入門](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html)。
1. 如果您正在建立新提醒，請選擇 **Add alert** (新增提醒)，或選擇 **Save** (儲存) 來儲存現有提醒。
# 使用 Athena 工作群組 API
以下是一些用於 Athena 工作群組的 REST API 操作。在以下所有操作中 (`ListWorkGroups` 除外)，您必須指定工作群組。在其他操作中，例如 `StartQueryExecution`，工作群組參數是選擇性，此處未列出這些操作。如需操作的完整清單，請參閱 [Amazon Athena API 參考](https://docs.aws.amazon.com/athena/latest/APIReference/)。
+ [CreateWorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_CreateWorkGroup.html)
+ [DeleteWorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_DeleteWorkGroup.html)
+ [GetWorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetWorkGroup.html)
+ [ListWorkGroups](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListWorkGroups.html)
+ [UpdateWorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_UpdateWorkGroup.html)
# 對工作群組錯誤進行疑難排解
使用以下秘訣進行工作群組疑難排解。
+ 檢查您的帳戶中個別使用者的許可。他們必須有權存取查詢結果的位置，以及您們想要在其中執行查詢的工作群組。如果他們想要切換工作群組，則還需要有這兩個工作群組的許可。如需相關資訊，請參閱[使用 IAM 政策來控制工作群組存取](workgroups-iam-policy.md)。
+ 請注意 Athena 主控台中的內容，了解您將在哪個工作群組中執行查詢。如果您使用驅動程式，請務必設定為您需要的工作群組。如需相關資訊，請參閱[指定查詢的工作群組](specify-wkgroup-to-athena-in-which-to-run-queries.md)。
+ 如果您使用 API 或驅動程式來執行查詢，您必須使用其中一種方式指定查詢結果位置：對於個別的查詢，使用 [OutputLocation](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultConfiguration.html#athena-Type-ResultConfiguration-OutputLocation) (用戶端)。在工作群組中，使用 [WorkGroupConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroupConfiguration.html)。如果未以任何方式指定位置，Athena 會在查詢執行期時發出錯誤。
+ 如果您以工作群組設定覆寫用戶端設定，您可能會遇到查詢結果位置方面的錯誤。例如，工作群組的使用者可能沒有許可，無法在 Amazon S3 中的工作群組位置存放查詢結果。在這種情況下，請新增必要的許可。
+ 工作群組會對 API 操作的行為造成改變。您帳戶中的使用者在 IAM 中，對工作群組需要有以資源為基礎的許可，才能在這些工作群組中呼叫以下現有的 API 操作。如果沒有工作群組和工作群組動作的許可，下列 API 動作會擲出 `AccessDeniedException`：**CreateNamedQuery**、**DeleteNamedQuery**、**GetNamedQuery**、**ListNamedQueries**、**StartQueryExecution**、**StopQueryExecution**、**ListQueryExecutions**、**GetQueryExecution**、**GetQueryResults** 和 **GetQueryResultsStream** (此 API 動作只適用於驅動器，不公開為公有使用)。如需詳細資訊，請參閱《服務授權參考》**中的 [Amazon Athena 的動作、資源和條件索引鍵](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonathena.html)。
只有針對在使用者可存取的工作群組中執行的查詢，呼叫 **BatchGetQueryExecution** 和 **BatchGetNamedQuery** API 操作才會傳回查詢的相關資訊。如果使用者無法存取此工作群組，這些 API 操作會在未處理的 ID 清單中傳回未經授權的查詢 ID。如需詳細資訊，請參閱[使用 Athena 工作群組 API](workgroups-api-list.md)。
+ 如果執行查詢的工作群組已設定有[強制的查詢結果位置](workgroups-settings-override.md)，請勿為 CTAS 查詢指定 `external_location`。在這種情況下，Athena 會發出錯誤，且指定 `external_location` 的查詢會失敗。例如，如果您覆寫用戶端的查詢結果位置設定，而強制工作群組使用其自己的位置，此查詢會失敗：`CREATE TABLE . WITH (format='Parquet', external_location='s3://amzn-s3-demo-bucket/test/') AS SELECT * FROM . LIMIT 10;`
您可能會看到下列錯誤。下表列出工作群組的一些相關錯誤和建議的解決方案。
**工作群組錯誤**
| 錯誤 | 發生時情況... |
| --- | --- |
| 查詢狀態為 CANCELED (已取消)。超出掃描的位元組限制。 | 查詢達到每一查詢資料限制，並且被取消。請考慮重寫查詢，以讀取較少的資料，或聯絡您的帳戶管理員。 |
| 使用者 arn:aws:iam::123456789012:user/abc 無權對資源 arn:aws:athena:us-east-1:123456789012:workgroup/workgroupname 執行 athena:StartQueryExecution | 使用者在工作群組中執行查詢，但沒有它的存取權。更新您的政策以提供此工作群組的存取權。 |
| INVALID\$1INPUT。工作群組 已停用。 | 使用者在工作群組中執行查詢，但此工作群組已停用。管理員可能停用您的工作群組。也可能是您沒有它的存取權。在這兩種情況下，請聯絡有權修改工作群組的管理員。 |
| INVALID\$1INPUT。找不到工作群組 。 | 使用者在工作群組中執行查詢，但此工作群組不存在。如果已刪除工作群組，則可能發生此情況。切換到另一個工作群組來執行您的查詢。 |
| InvalidRequestException：呼叫 StartQueryExecution 操作時：未提供輸出位置。需要透過工作群組結果組態設定或作為 API 輸入來提供輸出位置。 | 使用者以 API 執行查詢，但未指定查詢結果的位置。您必須使用兩種方式之一來設定查詢結果的輸出位置：對於個別的查詢，使用 [OutputLocation](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultConfiguration.html#athena-Type-ResultConfiguration-OutputLocation) (用戶端)，或在工作群組中，使用 [WorkGroupConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroupConfiguration.html)。 |
| Create Table As Select 查詢失敗，因為該查詢已使用 'external\$1location' 屬性提交至 Athena 工作群組，而該工作群組會針對所有查詢強制執行集中輸出位置。請移除 'external\$1location' 屬性，然後重新提交查詢。 | 如果執行查詢的工作群組已設定[強制的查詢結果位置](workgroups-settings-override.md)，而且您為 CTAS 查詢指定 external\$1location。在這種情況下，請移除 external\$1location 並重新執行查詢。 |
| 無法建立預備陳述式 prepared\$1statement\$1name。此工作群組中的預備陳述式數目超過 1000 的上限。 | 工作群組包含的預備陳述式超過 1000 的上限。若要解決此問題，請使用 [DEALLOCATE PREPARE](sql-deallocate-prepare.md) 以從工作群組中移除一或多個預備陳述式。或者，建立新的工作群組。 |
# 管理查詢處理容量
您可以使用容量保留，為您在 Athena 中執行的查詢取得專用無伺服器處理容量。透過容量保留，您可以利用工作負載管理功能，協助您排定優先順序、控制和擴展最重要的工作負載。例如，您可以新增容量來控制可同時執行的查詢數量、選擇可使用容量的工作負載，以及在工作負載之間共用容量。容量是無伺服器且由 Athena 完全管理，只要您需要，就會為您保留。設定非常簡單，不需要變更 SQL 查詢。
若要取得查詢的處理能力，您可建立容量保留、指定所需的資料處理單位 (DPU) 數目，然後將一或多個工作群組指派給保留。
當您使用容量保留時，工作群組扮演著重要角色。工作群組可讓您將查詢組織成邏輯分組或使用案例。透過容量保留，您可以選擇性地將容量指派給工作群組，以便控制每個工作群組的查詢行為方式以及計費方式。如需有關工作群組的詳細資訊，請參閱 [使用工作群組來控制查詢存取和成本](workgroups-manage-queries-control-costs.md)。
將工作群組指派給容量保留可讓您優先處理這些查詢，因為它們會在預留容量上執行，且不計入您的 DDL 和 DML 查詢配額。例如，您可以將容量分配給用於時間敏感財務報告查詢的工作群組，以將這些查詢與其他工作群組中較不重要的查詢隔離。這可讓您預測關鍵工作負載的查詢執行，同時允許其他工作負載獨立執行。
您可以結合使用容量保留和工作群組，以滿足不同的需求。以下為一些範例案例：
+ **隔離重要的查詢** – 為了確保重要的工作負載具有所需的容量，請建立容量保留，並將其工作群組指派給保留。只有來自指派工作群組的查詢會使用保留的處理容量。例如，為了確保可靠執行支援生產應用程式的查詢，請將這些查詢的生產工作群組指派給容量保留。開發查詢時，請使用與保留無關的個別工作群組，並在就緒時將查詢移至生產工作群組。
+ **在類似的工作負載之間共用容量** – 多個工作負載可以從一個保留中共用容量。這可讓您實現這些工作負載的可預測成本，並控制其並行。例如，如果您的排程工作負載可容忍延遲的查詢執行開始時間，您可以將其工作群組指派給單一保留。這樣可以釋放 DDL 和 DML 查詢配額，以便在相同帳戶中執行的互動式查詢，確保這些查詢以最少的延遲開始。
## 了解 DPU
容量是以資料處理單位 (DPU) 為單位測量而得。DPUs代表 Athena 用來代表您存取和處理資料的無伺服器運算和記憶體資源。一個 DPU 通常提供 4 個 vCPUs和 16 GB 的記憶體。您持有DPUs 數量會影響您可以同時執行的查詢數量。例如，具有 256 個 DPU 的保留所支援的並行查詢數量大約是具有 128 個 DPU 的保留的兩倍。
如需有關估算容量需求的資訊，請參閱 [判斷容量需求](capacity-management-requirements.md)。如需定價資訊，請參閱 [Amazon Athena 定價](https://aws.amazon.com/athena/pricing/)。
## 考量和限制
+ 您可以根據掃描的資料，在同一帳戶中同時使用容量保留和每個查詢計費。
+ 在容量保留上執行的查詢不會計入您的 DDL 和 DML 查詢配額。
+ 如果您的容量忙於處理其他查詢，新提交的查詢會排入佇列，直到容量可用為止。佇列中允許的時間上限為 10 小時。
+ 一個工作群組一次可以指派給一個容量保留。您總共可以將 20 個工作群組指派給單一保留。當您將多個工作群組指派給保留時，容量會跨工作群組共用，並根據其提交順序配置給查詢。由於 Athena 如何動態分配容量給查詢，執行順序可能會有所不同。
+ Athena 會根據 DML 查詢的複雜性，自動將 4 到 124 DPUs 配置給 DML 查詢。DDL 查詢各使用 4 DPUs。如需詳細資訊，請參閱下列主題：
+ [判斷容量需求](capacity-management-requirements.md)
+ [控制容量用量](capacity-management-control-capacity-usage.md)
+ 每個容量保留所需的 DPUs 數目下限為 4。如需定價資訊，請參閱 [Amazon Athena 定價](https://aws.amazon.com/athena/pricing/)。
+ 您可建立多達 100 個容量保留，每個帳戶和區域可建立多達 1,000 個 DPU 總數目上限。如果您的使用案例需要 1,000 個以上的 DPU，請聯絡 [athena-feedback@amazon.com](mailto:athena-feedback@amazon.com?subject=Athena Provisioned Capacity DPU Limit Request)。
+ 無法保證容量請求，且可能需要 30 分鐘才能完成。容量無法轉移至另一個容量保留 AWS 帳戶，或 AWS 區域。
+ `DPUConsumed` CloudWatch 指標是以工作群組為單位，而非保留區為單位。因此，如果您將工作群組從一個保留區移至另一個保留區，則 `DPUConsumed` 指標會包含該工作群組屬於第一個保留區時的資料。如需有關使用 Athena 中的 CloudWatch 指標的詳細資訊，請參閱 [使用 CloudWatch 監控 Athena 查詢指標](query-metrics-viewing.md)。
+ 若要刪除已指派給保留的工作群組，請先從保留中移除該工作群組。
+ 不支援設定為使用 Apache Spark 的工作群組。
+ 容量保留不適用於下列商業 AWS 區域：
+ 以色列 (特拉維夫)
+ 中東 (阿拉伯聯合大公國)
+ Middle East (Bahrain)
+ 亞太區域 (紐西蘭)
**Topics**
+ [了解 DPU](#capacity-management-understanding-dpus)
+ [考量和限制](#capacity-management-considerations-limitations)
+ [判斷容量需求](capacity-management-requirements.md)
+ [建立容量保留](capacity-management-creating-capacity-reservations.md)
+ [控制容量用量](capacity-management-control-capacity-usage.md)
+ [自動調整容量](capacity-management-automatically-adjust-capacity.md)
+ [管理保留](capacity-management-managing-reservations.md)
+ [容量保留的 IAM 政策](capacity-reservations-iam-policy.md)
+ [Athena 容量保留 API](capacity-management-api-list.md)
# 判斷容量需求
建立容量保留之前，您可以預估所需的容量，以便為其指派正確的 DPU 數目。而且，在使用保留後，您可能需要檢查保留的容量是不足還是過多。本主題說明可用來進行這些預估的技術，也說明評估用量和成本的一些 AWS 工具。
**Topics**
+ [預估所需的容量](#capacity-management-requirements-estimating)
+ [需要更多容量的跡象](#capacity-management-requirements-insufficient-capacity)
+ [檢查閒置容量](#capacity-management-requirements-idle-capacity)
+ [監控 DPU 使用量](#capacity-management-requirements-monitoring-dpu-consumption)
## 預估所需的容量
預估容量需求時，考慮兩個觀點非常有用：特定查詢可能需要多少容量，以及一般需要多少容量。
### 預估每個查詢的容量需求
若要判斷查詢可能需要的 DPU 數目，您可以使用下列指導方針：
+ DDL 查詢會消耗 4 個 GPU。
+ DML 查詢會消耗 4 到 124 個 GPU。
Athena 可判斷提交查詢時 DML 查詢所需的 DPU 數目。數目會根據資料大小、儲存格式、查詢建構和其他因素而異。一般而言，Athena 會嘗試選取最低、最有效率的 DPU 數目。如果 Athena 判斷需要更多的運算能力才能順利完成查詢，則會增加指派給查詢的 DPU 數目。
### 預估工作負載特定容量需求
若要判斷同時執行多個查詢時可能需要多少容量，請考慮下列資料表中的一般指導方針：
****
| 並行查詢 | 所需的 DPU |
| --- | --- |
| 10 | 40 或以上 |
| 20 | 96 或以上 |
| 30 或以上 | 240 或以上 |
請注意，您實際需要的 DPU 數目取決於您的目標和分析模式。例如，如果您想要立即開始查詢而不排入佇列，請判斷尖峰並行查詢需求，然後相應地佈建 DPU 數目。
您可以佈建比尖峰需求更少的 DPU，但在發生尖峰需求時可能會導致佇列。進行佇列時，Athena 會將您的查詢保存在佇列中，並在容量可用時執行查詢。
如果您的目標是在固定預算內執行查詢，您可以使用 [AWS Pricing Calculator](https://calculator.aws/#/addService/Athena) 來判斷適合您預算的 DPU 數目。
最後請記住，資料大小、儲存格式和查詢的寫入方式會影響查詢所需的 DPU。若要提高查詢效能，您可以壓縮或分割資料，或將其轉換為單欄式格式。如需詳細資訊，請參閱[最佳化 Athena 效能](performance-tuning.md)。
## 需要更多容量的跡象
容量不足錯誤訊息和查詢佇列是指派容量不足的兩個指示。
如果您的查詢失敗並顯示容量不足錯誤訊息，則容量保留的 DPU 數目太低，無法滿足您的查詢要求。例如，如果您的保留具有 24 個 DPU，且執行的查詢需要 24 個以上的 DPU，則查詢將失敗。若要監控此查詢錯誤，您可以使用 Athena 的 [EventBridge 事件](athena-events.md)。嘗試新增更多 DPU，然後重新執行查詢。
如果有許多查詢排入佇列，則表示您的容量已被其他查詢充分利用。若要減少佇列，請執行下列任意一項：
+ 將 DPU 新增至您的保留，以提高查詢並行性。
+ 從保留中移除工作群組，以釋放容量供其他查詢使用。
若要檢查是否有過多的查詢佇列，請針對容量保留中的工作群組使用 Athena 查詢佇列時間 [CloudWatch 指標](query-metrics-viewing.md)。如果該值超過您偏好的閾值，您可以將 DPU 新增至容量保留。
## 檢查閒置容量
若要檢查閒置容量，您可以減少保留中的 DPU 數目或增加其工作負載，然後觀察結果。
**若要檢查閒置容量**
1. 執行以下任意一項：
+ 減少保留中的 DPU 數目 (減少可用資源)
+ 將工作群組新增至您的保留 (增加工作負載)
1. 使用 [CloudWatch](query-metrics-viewing.md) 來測量查詢佇列時間。
1. 如果佇列時間增加超過理想水平，請執行下列任意一項
+ 移除工作群組
+ 將 DPU 新增至您的容量保留
1. 每次變更之後，請檢查效能和查詢佇列時間。
1. 繼續調整工作負載及/或 DPU 計數，以達到所需的平衡。
如果您不想將容量維持在偏好期間以外，您可以[取消](capacity-management-cancelling-a-capacity-reservation.md)保留並稍後建立另一個保留。但是，即使您最近取消了其他保留的容量，也無法保證請求新容量，而且建立新的保留需要一些時間。
## 監控 DPU 使用量
查詢執行後，您可以檢視查詢使用的 DPU，以協助精簡容量預估。Athena 透過主控台、API 操作和 CloudWatch 提供 DPU 耗用指標。此資訊可協助您識別耗用比預期更多或更少資源的查詢，並根據實際資料最佳化容量配置。如需檢視和追蹤 DPU 使用量的詳細資訊，請參閱 [監控 DPU 用量](capacity-management-control-capacity-usage.md#capacity-management-monitor-dpu-usage)。
## 評估容量需求和成本的工具
您可以在 中使用下列服務和功能 AWS 來測量您的 Athena 用量和成本。
### CloudWatch 指標
您可以將 Athena 設定為在工作群組層級將查詢相關指標發佈到 Amazon CloudWatch。為工作群組啟用指標後，工作群組查詢的指標會顯示在工作群組詳細資訊頁面的 Athena 主控台中。
如需有關發佈至 CloudWatch 的 Athena 指標及其維度的資訊，請參閱 [使用 CloudWatch 監控 Athena 查詢指標](query-metrics-viewing.md)。
### CloudWatch 用量指標
您可使用 CloudWatch 用量指標，透過在 CloudWatch 圖表和儀表板中顯示目前的服務使用量狀況，瞭解您的帳戶如何使用資源。對於 Athena，用量可用性指標對應至 Athena AWS [的服務配額](service-limits.md)。您可以設定警示，在您的用量接近服務配額時發出警示。
如需詳細資訊，請參閱[使用 CloudWatch 監控 Athena 用量指標](monitoring-athena-usage-metrics.md)。
### Amazon EventBridge 事件
您可以搭配使用 Amazon EventBridge 與 Amazon Athena，以接收有關查詢狀態的即時通知。當您提交的查詢變更狀態時，Athena 會將事件發布至 EventBridge，當中包含該查詢狀態轉換的相關資訊。您可以針對感興趣的事件撰寫簡單的規則，並在事件符合規則時採取自動化動作。
如需詳細資訊，請參閱下列資源。
+ [使用 EventBridge 監控 Athena 查詢事件](athena-events.md)
+ [什麼是 Amazon EventBridge？](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html)
+ [Amazon EventBridge 事件](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html)
### Tags (標籤)
在 Athena 中，容量保留支援標籤。一個標籤均包含一个索引鍵和一個值。若要在 Athena 中追蹤您的成本，您可以使用 AWS產生的成本分配標籤。 AWS 會使用成本分配標籤來整理成本[和用量報告中](https://docs.aws.amazon.com/cur/latest/userguide/what-is-cur.html)的資源成本。這可讓您更輕鬆地分類和追蹤 AWS 成本。若要啟用 Athena 的成本分配標籤，請使用 [AWS 帳單與成本管理 主控台](https://console.aws.amazon.com/billing/)。
如需詳細資訊，請參閱下列資源。
+ [標記 Athena 資源](tags.md)
+ [啟用 AWS產生的成本分配標籤](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activate-built-in-tags.html)
+ [使用 AWS 成本分配標籤](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html)
# 建立容量保留
若要開始使用，您可建立具有所需 DPU 數目的容量保留，然後指派一或多個工作群組，以使用該容量進行查詢。您可以稍後視需要調整容量，以提供更一致的效能或更好地管理成本。如需有關估算容量需求的資訊，請參閱 [判斷容量需求](capacity-management-requirements.md)。
**重要**
無法保證容量請求，且可能需要 30 分鐘才能完成。
**若要建立容量保留**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 如果未顯示主控台的導覽窗格，請選擇左側的展開選單。
1. 選擇**管理**、**容量保留**。
1. 選擇**建立容量保留**。
1. 在**建立容量保留**頁面上，對於**容量保留名稱**，輸入名稱。名稱必須是唯一的，長度介於 1 至 128 個字元之間，且只能使用字元 a-z、A-Z、0-9、\$1(底線)、.(句點) 和 -(連字號)。建立保留後，便無法變更名稱。
1. 對於 **DPU**，選擇或輸入所需的資料處理單位 (DPU) 數目，增量為 4。如需詳細資訊，請參閱[了解 DPU](capacity-management.md#capacity-management-understanding-dpus)。
1. (選用) 展開**標籤**選項，然後選擇**新增標籤**，以新增一或多個鍵值組，進而與容量保留資源建立關聯。如需詳細資訊，請參閱[標記 Athena 資源](tags.md)。
1. 選擇**檢閱**。
1. 在**確認建立容量保留**提示中，確認 DPUs數量 AWS 區域和其他資訊。如果您接受，請選擇**提交**。
在詳細資訊頁面上，容量保留的**狀態**會顯示為**待定**。當您的預留容量可用於執行查詢時，其狀態會顯示為**作用中**。
此時，您可在保留中新增一或多個工作群組。如需這些步驟，請參閱 [將工作群組新增至保留](capacity-management-adding-workgroups-to-a-reservation.md)。
# 控制容量用量
您可以設定最大或最小 DPU 控制項，以控制 Athena 配置給查詢的 DPU 數量。您可以在工作群組層級設定這些項目，以為所有查詢建立基準控制，或在個別查詢層級建立精細控制。這可讓您直接控制查詢效能、工作負載並行和成本。
+ 當您設定最大數量的 DPU 時，會防止查詢消耗超過您指定的容量。這可讓您輕鬆地控制成本和工作負載並行。例如，如果您的容量保留有 200 個 DPU，將每個查詢的 DPU 上限設定為 8 可讓您同時執行 25 個查詢。如果您將保留增加到 400 個 DPU，您可以同時執行 50 個查詢。
+ 當您設定最低數量的 DPU 時，您可以確保使用所需的最低數量的 DPU 執行查詢。當您事先了解查詢的一般容量用量描述檔時，這會很有幫助。
**注意**
DPU 用量控制僅適用於使用容量保留執行的查詢。
**注意**
若要對所有查詢使用相同數量的 DPU，請針對最小和最大 DPU 使用相同的值。
## 在工作群組層級設定 DPU 控制項
在工作群組層級設定 DPU 控制，以管理成本和控制您選擇的工作群組的工作負載效能。啟用**覆寫用戶端設定**時，工作群組層級設定的 DPU 控制項會套用至所有查詢。
**使用主控台設定 DPU 控制項**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 在導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 選取使用容量保留的工作群組。
1. 在**執行控制項**索引標籤上，選擇**編輯控制項**。
1. 設定下列項目：
+ 對於**每個查詢的最小 DPU**，以 4 為增量，輸入介於 4 到 124 之間的值。
+ 對於**每個查詢的最大 DPU**，以 4 為增量，輸入介於 4 到 124 之間的值。
1. 選擇**儲存**。
1. （選用） 選取**覆寫用戶端設定**以強制執行這些設定，並忽略查詢層級 DPU 組態。
**使用 設定 DPU 控制項 AWS CLI**
+ 使用 `update-work-group`命令來設定工作群組的 DPU 控制項：
```
aws athena update-work-group \
--work-group my_workgroup \
--configuration-updates '{
"EngineConfiguration": {
"Classifications": [
{
"Name": "athena-query-engine-properties",
"Properties": {
"max-dpu-count" : "24",
"min-dpu-count" : "12"
}
}
]
}}'
```
如果您將 `EnforceWorkGroupConfiguration` 設定為 `true`，工作群組設定會覆寫透過 [StartQueryExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartQueryExecution.html) 提交時在查詢層級指定的任何 DPU 控制項。這可確保工作群組中所有查詢的資源配置一致。
## 使用個別查詢設定 DPU 控制項
當您需要使用具有不同資源需求的查詢進行精細控制時，請設定查詢層級 DPU 控制。查詢層級 DPU 控制優先於工作群組層級設定，除非工作群組已啟用**覆寫用戶端設定**。
**使用主控台設定查詢的 DPU 控制項**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 在導覽窗格中，選擇 **Query Editor (查詢編輯器)**。
1. 選取使用容量保留的工作群組。
1. 選擇**查詢設定**索引標籤。
1. 在**執行控制項**區段中，選擇**編輯控制項**。
1. 設定下列項目：
+ 對於**每個查詢的最小 DPU**，以 4 為增量，輸入介於 4 到 124 之間的值。
+ 對於**每個查詢的最大 DPU**，以 4 為增量，輸入介於 4 到 124 之間的值。
1. 選擇**儲存**。
**使用 設定查詢的 DPU 控制項 AWS CLI**
+ 使用 `start-query-execution`命令搭配 `engine-configuration` 參數：
```
aws athena start-query-execution \
--query-string "SELECT * FROM my_table LIMIT 10" \
--work-group "my_workgroup" \
--engine-configuration '{
"Classifications": [ {
"Name": "athena-query-engine-properties",
"Properties": {
"max-dpu-count" : "32",
"min-dpu-count" : "8"
}
}
]}'
```
查詢層級和工作群組層級 DPU 設定之間的關係取決於您的工作群組組態：
+ 啟用**覆寫用戶端設定**時，工作群組層級 DPU 控制優先於任何查詢層級設定。這可確保指定工作群組中所有查詢的一致資源用量。
+ 未啟用**覆寫用戶端設定**時，查詢層級 DPU 控制優先於工作群組層級設定。這可讓個別查詢最佳化的彈性。
如果您未在任一層級指定 DPU 控制項，Athena 會根據查詢複雜性自動配置容量。
**注意**
對於 DDL 查詢，最小 DPUs的最大值為 4。為 DDL 查詢設定較高的最小值會導致錯誤。
## 監控 DPU 用量
查詢完成後，您可以檢視其 DPU 用量。Athena 透過主控台、API 操作和 CloudWatch 提供 DPU 用量指標。
**在主控台中檢視 DPU 使用量**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 在導覽窗格中，選擇 **Query Editor (查詢編輯器)**。
1. 查詢完成後，請在查詢結果容器中檢視其**已使用的 DPU **值。
1. 若要檢視過去查詢的 DPU 使用量：
1. 在導覽窗格中選擇**最近的查詢**。
1. 如果尚未顯示，請選取設定圖示，將**已使用的 DPU** 資料欄新增至資料表。
1. 檢閱每個已完成查詢的 DPU 使用量。
1. 或者，從**查詢編輯器**中，選擇**查詢統計資料**索引標籤，並檢閱**已使用的 DPU**。
**使用 API 擷取 DPU 耗用**
1. 使用下列 API 操作以程式設計方式擷取 DPU 耗用量：
+ `GetQueryExecution` - 傳回特定查詢的執行詳細資訊
+ `BatchGetQueryExecution` - 傳回多個查詢的執行詳細資訊
1. 使用 AWS CLI的範例：
```
aws athena get-query-execution \
--query-execution-id "123e4567-e89b-12d3-a456-426614174000"
```
回應包含 `Statistics` 物件中的 `DpuCount` 欄位：
```
{
"QueryExecution": {
"Statistics": {
"DpuCount": 8
}
}
}
```
**使用 CloudWatch 監控 DPU 用量**
+ Athena 會將查詢相關指標發佈至 CloudWatch，協助您監控容量使用率和其他效能資料。如需詳細資訊，請參閱 [使用 CloudWatch 監控 Athena 查詢指標](query-metrics-viewing.md)。
# 自動調整容量
您可以使用 Athena 的自動擴展解決方案自動調整保留的容量，以回應工作負載使用率。當使用率超過您設定的閾值時，它會自動新增容量，並在低使用率期間移除容量以降低成本。您可以透過設定不同的使用率閾值、最小和最大 DPU 數量、擴展增量和使用率評估頻率來自訂其行為。這可消除手動容量調整，同時協助您平衡效能需求與成本最佳化。
您可以使用 CloudFormation 範本部署此無伺服器解決方案。它建立 Step Functions 狀態機器，可監控使用率指標並做出擴展決策。您可以進一步自訂範本或狀態機器，以符合您的特定需求。
若要開始使用，請使用 Athena 主控台，然後選擇在容量保留詳細資訊頁面上**設定自動調整規模**，該頁面會使用預先載入的 CloudFormation 範本將您重新導向至 。或者，請遵循下列程序。
## 先決條件
+ 需要主動容量保留
+ 部署 CloudFormation 堆疊和建立 Step Functions 資源所需的 IAM 許可
## 啟動 CloudFormation 堆疊
此自動化 CloudFormation 範本會部署 Athena 容量保留自動擴展解決方案。您必須先完成 中的適用步驟，[先決條件](#capacity-management-auto-scaling-prerequisites)才能啟動堆疊。
[https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/new?&templateURL=https:%2F%2Fathena-downloads.s3.us-east-1.amazonaws.com%2F%2Ftemplates%2F%2Fcapacity-reservation-scaling%2F%2Fstate-machine%2F%2Fathena-capacity-reservation-scaling-template-v1.1.yaml](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/new?&templateURL=https:%2F%2Fathena-downloads.s3.us-east-1.amazonaws.com%2F%2Ftemplates%2F%2Fcapacity-reservation-scaling%2F%2Fstate-machine%2F%2Fathena-capacity-reservation-scaling-template-v1.1.yaml)
**啟動自動擴展解決方案**
1. 登入 [AWS 管理主控台](https://console.aws.amazon.com/)，然後選取按鈕以啟動`AWSAccelerator-InstallerStack` CloudFormation 範本。
1. 根據預設，範本會在美國東部 （維吉尼亞北部） 啟動。若要在不同的 中啟動解決方案 AWS 區域，請使用主控台導覽列中的區域選擇器。
1. 在**建立堆疊**頁面上，確認範本 URL 位於 **Amazon S3 URL** 文字方塊中，然後選擇**下一步**。
1. 在**指定堆疊詳細資訊**頁面上，為您的解決方案堆疊指派名稱。
1. 在**參數**下，檢閱此解決方案範本的參數，並視需要修改這些參數。此解決方案使用下列預設值。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/capacity-management-automatically-adjust-capacity.html)
**注意**
所有 DPU 值都必須是 4 的倍數，以符合 Athena 的容量保留要求。
1. 選擇**下一步**。
1. 在 **Configure stack options** (設定堆疊選項) 頁面，選擇 **Next** (下一步)。
1. 在**檢閱和建立**頁面上，檢閱並確認設定。選取確認範本可能會建立 IAM 資源的方塊。
1. 選擇**提交**以部署堆疊。
您可以在狀態欄的 CloudFormation 主控台中檢視堆疊**的狀態**。您應該會在幾分鐘內收到 `CREATE_COMPLETE` 狀態。
# 管理保留
您可以在**容量保留**頁面上檢視和管理您的容量保留。您可以執行管理任務，例如新增或減少 DPU、修改工作群組指派，以及標記或取消保留。
**若要檢視和管理容量保留**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 如果未顯示主控台的導覽窗格，請選擇左側的展開選單。
1. 選擇**管理**、**容量保留**。
1. 在容量保留頁面上，您可以執行下列任務：
+ 若要建立容量保留，請選擇**建立容量保留**。
+ 使用搜尋方塊，依名稱或 DPU 數目篩選保留。
+ 選擇狀態下拉式選單，依容量保留狀態進行篩選 (例如，**作用中**或**已取消**)。如需有關保留狀態的詳細資訊，請參閱 [了解保留狀態](#capacity-management-understanding-reservation-status)。
+ 若要檢視容量保留的詳細資訊，請選擇保留的連結。保留的詳細資訊頁面包括以下選項：[編輯容量](capacity-management-editing-capacity-reservations.md)、[新增工作群組](capacity-management-adding-workgroups-to-a-reservation.md)、[移除工作群組](capacity-management-removing-a-workgroup-from-a-reservation.md)以及[取消](capacity-management-cancelling-a-capacity-reservation.md)保留。
+ 若要編輯保留 (例如，透過新增或移除 DPU)，請選取保留的按鈕，然後選擇**編輯**。
+ 若要取消預留，請選取保留按鈕，然後選擇**取消**。
## 了解保留狀態
下表說明容量保留的可能狀態值。
****
| 狀態 | Description |
| --- | --- |
| 待定 | Athena 正在處理您的容量請求。容量尚未準備好執行查詢。 |
| Active (作用中) | 容量可用於執行查詢。 |
| 失敗 | 您的容量請求未成功完成。請注意，無法保證滿足容量請求。失敗的保留會計入您的帳戶 DPU 限制。若要釋出使用量，您必須取消保留。 |
| 更新待定 | Athena 正在處理保留的變更。例如，在您編輯保留以新增或移除 DPU 之後，就會發生此狀態。 |
| 取消 | Athena 正在處理取消保留的請求。仍在使用保留的工作群組中執行的查詢可以完成，但工作群組中的其他查詢將使用隨選 (未佈建的) 容量。 |
| 已取消 | 容量保留取消完成。已取消的保留會在主控台中保留 45 天。45 天後，Athena 將刪除保留。在這 45 天期間，您無法重新規劃或重複使用保留，但您可以參考其標籤並檢視其詳細資訊以供歷史參考。 無法保證可在未來日期重新保留取消的容量。容量無法轉移到另一個保留， AWS 帳戶 或 AWS 區域。 |
## 了解作用中 DPU 和目標 DPU
在 Athena 主控台的容量保留清單中，您的保留會顯示兩個 DPU 值：**作用中 DPU** 和**目標 DPU**。
+ **作用中 DPU** – 保留中可用來執行查詢的 DPU 數目。例如，如果您請求 100 個 DPU，且您的請求已滿足，則**作用中 DPU** 會顯示 **100**。
+ **目標 DPU** – 您的保留正在移至的 DPU 數目。在建立保留或待定增加或減少 DPU 數目時，**目標 DPU** 顯示的值會與**作用中 DPU** 不同。
例如，在您提交請求以建立具有 24 個 DPU 的保留之後，保留**狀態**將為**待定**，**作用中 DPU** 將為 **0**，而**目標 DPU** 將為 **24**。
如果您的保留有 100 個 DPU，並編輯您的保留以請求增加 20 個 DPU，則**狀態**將為**更新待定**，**作用中 DPU** 將為 **100**，而**目標 DPU** 將為 **120**。
如果您的保留有 100 個 DPU，並編輯您的保留以請求減少 20 個 DPU，則**狀態**將為**更新待定**，**作用中 DPU** 將為 **100**，而**目標 DPU** 將為 **80**。
在這些轉換期間，Athena 會根據您的請求積極獲取或減少 DPU 數目。當**作用中 DPU** 等於**目標 DPU** 時，則達到目標數目，且沒有任何待定變更。
若要以程式設計方式擷取這些值，您可以呼叫 [GetCapacityReservation](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetCapacityReservation.html) API 動作。該 API 將**作用中 DPU** 和**目標 DPU** 稱為 `AllocatedDpus` 和 `TargetDpus`。
**Topics**
+ [了解保留狀態](#capacity-management-understanding-reservation-status)
+ [了解作用中 DPU 和目標 DPU](#capacity-management-understanding-dpu-status)
+ [編輯容量保留](capacity-management-editing-capacity-reservations.md)
+ [將工作群組新增至保留](capacity-management-adding-workgroups-to-a-reservation.md)
+ [從保留中移除工作群組](capacity-management-removing-a-workgroup-from-a-reservation.md)
+ [取消容量保留](capacity-management-cancelling-a-capacity-reservation.md)
+ [刪除容量保留](capacity-management-deleting-a-capacity-reservation.md)
# 編輯容量保留
建立容量保留後，您可以調整其 DPU 數目，以及新增或移除其自訂標籤。
**若要編輯容量保留**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 如果未顯示主控台的導覽窗格，請選擇左側的展開選單。
1. 選擇**管理**、**容量保留**。
1. 在容量保留清單中，執行下列任意一項：
+ 選取保留旁邊的按鈕，然後選擇**編輯**。
+ 選擇保留連結，然後選擇**編輯**。
1. 針對 **DPU**，選擇或輸入您想要的資料處理單位數量。如需詳細資訊，請參閱[了解 DPU](capacity-management.md#capacity-management-understanding-dpus)。
**注意**
您可以隨時請求將 DPUs 新增至作用中容量保留。
當保留變為作用中或上次新增 DPUs後已超過 1 分鐘時，您可以請求從作用中容量保留減少 DPUs。
當您請求減少 DPUs 時，Athena 會優先移除閒置DPUs而非作用中DPUs。如果查詢正在使用標記為移除DPUs，Athena 會等待查詢完成，然後再移除 DPUs。
1. (選用) 針對**標籤**，選擇**移除**以移除標籤，或選擇**新增標籤**以新增標籤。
1. 選擇**提交**。保留詳細資訊頁面會顯示更新的組態。
# 將工作群組新增至保留
建立容量保留後，您最多可以將 20 個工作群組新增至保留。將工作群組新增至保留會告訴 Athena 應該在預留容量上執行哪些查詢。來自未與保留關聯的工作群組查詢，會繼續使用預設的每 TB 掃描定價模式執行。
當保留有兩個或多個工作群組時，來自這些工作群組的查詢可以使用保留的容量。您可以隨時新增和移除工作群組。新增或移除工作群組時，不會中斷正在執行的查詢。
當您的保留處於待定狀態時，來自您新增的工作群組的查詢會繼續使用預設的每 TB 掃描定價模式執行，直到保留變為作用中。
**若要將一或多個工作群組新增至您的容量保留**
1. 在容量保留的詳細資訊頁面上，選擇**新增工作群組**。
1. 在**新增工作群組**頁面上，選取要新增的工作群組，然後選擇**新增工作群組**。您不能將一個工作群組指派至多個預留。
容量保留的詳細資訊頁面會列出您新增的工作群組。在這些工作群組中執行的查詢，將使用您在保留處於作用中狀態時保留的容量。
# 從保留中移除工作群組
如果您不再需要工作群組專用容量，或想要將工作群組移至其自己的保留中，您可以隨時將其移除。從保留移除工作群組輕鬆簡單。從保留中移除工作群組後，從移除的工作群組查詢會使用隨需容量返回 ，並根據掃描的 TB (TB) 計費。
**若要從保留移除一或多個工作群組**
1. 在容量保留之詳細資料頁面上，選取您要移除的工作群組。
1. 選擇**移除工作群組**。**是否移除工作群組？**提示會通知您，在將工作群組從保留中移除之前，將會完成所有目前作用中的查詢。
1. 選擇**移除**。容量保留的詳細資訊頁面會顯示移除的工作群組不再存在。
# 取消容量保留
如果您不想再使用容量保留，則可將其取消。仍在使用保留的工作群組中執行的查詢將可完成，但工作群組中的其他查詢將不再使用保留。
**注意**
無法保證可在未來日期重新保留取消的容量。容量無法轉移至其他保留， AWS 帳戶 或 AWS 區域。
**若要取消容量保留**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 如果未顯示主控台的導覽窗格，請選擇左側的展開選單。
1. 選擇**管理**、**容量保留**。
1. 在容量保留清單中，執行下列任意一項：
+ 選取保留旁邊的按鈕，然後選擇**取消**。
+ 選擇容量連結，然後選擇**取消容量保留**。
1. 畫面出現**是否取消容量保留？**提示時，輸入**取消**，然後選擇**取消容量保留**。
保留的狀態會變更為**取消中**，且進度橫幅會通知您正在取消。
取消完成後，容量保留仍會保留，但其狀態會顯示為**已取消**。保留將在取消後 45 天刪除。在這 45 天期間，您無法重新規劃或重複使用已取消的保留，但您可以參考其標籤並檢視其詳細資訊以供歷史參考。
# 刪除容量保留
如果您要移除已取消的容量保留的所有參考，您可以刪除保留。必須先取消保留，然後才可將其刪除。刪除的保留會立即從您的帳戶中移除，且無法再參考，包括其 ARN。
**若要刪除容量保留**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 如果未顯示主控台的導覽窗格，請選擇左側的展開選單。
1. 選擇**管理**、**容量保留**。
1. 在容量保留清單中，執行下列任意一項：
+ 選取已取消的保留旁邊的按鈕，然後選擇**動作**、**刪除**。
+ 選擇保留連結，然後選擇**刪除**。
1. 畫面出現**是否刪除容量保留？**提示時，選擇**刪除**。
畫面會出現橫幅，通知您已成功刪除容量保留。刪除的保留不再出現在容量保留清單中。
# 容量保留的 IAM 政策
若要控制對容量保留的存取，請使用資源層級 IAM 許可或以身分為基礎的 IAM 政策。每當您使用 IAM 政策時，請務必遵循 IAM 最佳實務。如需詳細資訊，請參閱*《IAM 使用者指南》*中的 [IAM 中的安全性最佳實務](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)。
下列程序專用於 Athena。
如需 IAM 特定的資訊，請參閱本節最後列出的連結。如需有關範例 JSON 容量保留政策的資訊，請參閱 [容量保留政策範例](example-policies-capacity-reservations.md)。
**若要在 IAM 主控台中使用視覺化編輯器來建立容量保留政策**
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 在左邊的導覽窗格中，選擇 **Policies** (政策)，然後選擇 **Create policy** (建立政策)。
1. 在 **Visual editor** (視覺化編輯器) 標籤上，選擇 **Choose a service** (選擇一項服務)。接著選擇 Athena 以新增到政策。
1. 選擇 **Select actions** (選取動作)，然後選擇要新增到政策的動作。視覺化編輯器會顯示 Athena 中可用的動作。如需詳細資訊，請參閱《服務授權參考》**中的 [Amazon Athena 的動作、資源和條件索引鍵](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonathena.html)。
1. 選擇**新增動作**來輸入特定動作，或使用萬用字元 (\$1) 來指定多個動作。
預設情況下，您建立的政策允許執行選擇的操作。對於 Athena 中的 `capacity-reservation` 資源，如果您選擇的一個或多個動作支援資源層級許可，則編輯器會列出 `capacity-reservation` 資源。
1. 選擇**資源**來為您的政策指定特定容量保留。如需有關範例 JSON 容量保留政策的資訊，請參閱 [容量保留政策範例](example-policies-capacity-reservations.md)。
1. 如下所示指定 `capacity-reservation` 資源：
```
arn:aws:athena:::capacity-reservation/
```
1. 選擇 **Review policy** (檢閱政策)，然後為您正在建立的政策輸入 **Name** (名稱) 與 **Description** (描述) (選用)。檢閱政策摘要來確認您已授予想要的許可。
1. 選擇 **Create policy** (建立政策) 儲存您的新政策。
1. 將此基於身分的政策連接到使用者、群組或角色。
如需詳細資訊，請參閱《服務授權參考》**與《IAM 使用者指南》**中的下列主題：
+ [Amazon Athena 的操作、資料和條件索引鍵](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonathena.html)
+ [使用視覺化編輯器來建立政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-visual-editor)
+ [新增和移除 IAM 政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)
+ [控制資源的存取](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html#access_controlling-resources)
如需有關範例 JSON 容量保留政策的資訊，請參閱 [容量保留政策範例](example-policies-capacity-reservations.md)。
如需 Amazon Athena 動作的完整清單，請參閱《[Amazon Athena API 參考](https://docs.aws.amazon.com/athena/latest/APIReference/)》中的 API 動作名稱。
# 容量保留政策範例
本節包含可讓您在容量保留上用來啟用各種動作的範例政策。每當您使用 IAM 政策時，請務必遵循 IAM 最佳實務。如需詳細資訊，請參閱《IAM 使用者指南》**中的 [IAM 中的安全性最佳實務](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)。
容量保留是由 Athena 管理的 IAM 資源。因此，如果您的容量保留政策使用 `capacity-reservation` 做為輸入的動作，您必須指定容量保留的 ARN，如下所示：
```
"Resource": [arn:aws:athena:::capacity-reservation/]
```
其中 `` 為容量保留的名稱。例如，對於名為 `test_capacity_reservation` 的容量保留，將其指定為資源，如下所示：
```
"Resource": ["arn:aws:athena:us-east-1:123456789012:capacity-reservation/test_capacity_reservation"]
```
如需 Amazon Athena 動作的完整清單，請參閱《[Amazon Athena API 參考](https://docs.aws.amazon.com/athena/latest/APIReference/)》中的 API 動作名稱。如需有關 IAM 政策的詳細資訊，請參閱《IAM 使用者指南》**中的[使用視覺化編輯器來建立政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-visual-editor)。
**Example 適用於列出容量保留的政策範例**
以下政策允許所有使用者列出所有容量保留。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:ListCapacityReservations"
],
"Resource": "*"
}
]
}
```
**Example 適用於管理操作的政策範例**
下列政策可讓使用者建立、取消、取得詳細資訊，以及更新容量保留 `test_capacity_reservation`。該政策還允許使用者指派 `workgroupA` 和 `workgroupB` 給 `test_capacity_reservation`。
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect": "Allow",
"Action": [
"athena:CreateCapacityReservation",
"athena:GetCapacityReservation",
"athena:CancelCapacityReservation",
"athena:UpdateCapacityReservation",
"athena:GetCapacityAssignmentConfiguration",
"athena:PutCapacityAssignmentConfiguration"
],
"Resource": [
"arn:aws:athena:us-east-1:123456789012:capacity-reservation/test_capacity_reservation",
"arn:aws:athena:us-east-1:123456789012:workgroup/workgroupA",
"arn:aws:athena:us-east-1:123456789012:workgroup/workgroupB"
]
}
]
}
```
# Athena 容量保留 API
下列清單包含 Athena 容量保留 API 動作的參考連結。如需資料結構和其他 Athena API 動作，請參閱 [https://docs.aws.amazon.com/athena/latest/APIReference/](https://docs.aws.amazon.com/athena/latest/APIReference/)。
+ [CancelCapacityReservation](https://docs.aws.amazon.com/athena/latest/APIReference/API_CancelCapacityReservation.html)
+ [CreateCapacityReservation](https://docs.aws.amazon.com/athena/latest/APIReference/API_CreateCapacityReservation.html)
+ [DeleteCapacityReservation](https://docs.aws.amazon.com/athena/latest/APIReference/API_DeleteCapacityReservation.html)
+ [GetCapacityAssignmentConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetCapacityAssignmentConfiguration.html)
+ [GetCapacityReservation](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetCapacityReservation.html)
+ [ListCapacityReservations](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListCapacityReservations.html)
+ [PutCapacityAssignmentConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_PutCapacityAssignmentConfiguration.html)
+ [UpdateCapacityReservation](https://docs.aws.amazon.com/athena/latest/APIReference/API_UpdateCapacityReservation.html)
# 最佳化 Athena 效能
本主題就改善 Athena 查詢效能以及如何解決與限制和資源使用量相關的錯誤，提供了一般資訊和具體建議。
一般而言，最佳化可以分組成服務、查詢和資料結構類別。在服務層級就撰寫查詢的方式以及建構資料和資料表的方式所做的決策，都可能會影響效能。
**Topics**
+ [最佳化服務使用](performance-tuning-service-level-considerations.md)
+ [最佳化查詢](performance-tuning-query-optimization-techniques.md)
+ [最佳化資料](performance-tuning-data-optimization-techniques.md)
+ [使用單欄式儲存格式](columnar-storage.md)
+ [使用分割和歸納](ctas-partitioning-and-bucketing.md)
+ [分割您的資料](partitions.md)
+ [透過 Amazon Athena 使用分割區投影](partition-projection.md)
+ [防止 Amazon S3 限流](performance-tuning-s3-throttling.md)
+ [其他資源](performance-tuning-additional-resources.md)
# 最佳化服務使用
服務層級考量事項包括您每一帳戶執行的工作負載數量、不僅限於 Athena (而是所有服務) 的服務配額，以及思考如何減少「資源不足」錯誤。
**Topics**
+ [在同一帳戶中操作多個工作負載](#performance-tuning-service-quotas)
+ [減少「資源不足」錯誤](#performance-tuning-resource-limits)
## 在同一帳戶中操作多個工作負載
Athena 使用配額來限制帳戶層級的查詢並行和 API 請求率。超出這些配額可能會導致查詢在執行期間或提交時失敗。如需有關這些配額的詳細資訊，請參閱 [Service Quotas](service-limits.md)。
如果您在同一個 AWS 帳戶中操作多個工作負載，您的工作負載會爭奪相同的帳戶層級配額。例如，如果一個工作負載遇到未預期的查詢爆量，同一帳戶中執行的另一個工作負載可能會出現佇列時間增加，或在最壞的情況下，因限流而導致查詢提交失敗。
我們建議您使用 CloudWatch 透過圖表和儀表板監控您的服務用量。您也可以設定 CloudWatch 警示，在用量接近並行查詢的服務配額時提醒您，讓您能在達到配額限制之前採取動作。如需詳細資訊，請參閱[使用 CloudWatch 監控 Athena 用量指標](monitoring-athena-usage-metrics.md)。
若要控制查詢並行並隔離帳戶內的工作負載，請使用容量保留。容量保留可在單一帳戶內提供專用查詢處理容量。容量是以資料處理單位 (DPU) 為單位測量而得，並可透過新增來增加查詢並行或透過移除來減少查詢並行。容量保留讓您能夠將容量指派給一或多個工作群組，進而隔離帳戶內的工作負載。如需詳細資訊，請參閱[管理查詢處理容量](capacity-management.md)。
雖然您應該隔離不同 AWS 帳戶中不相關的工作負載 （例如隔離開發與生產環境），但此方法無法提供可擴展的方式來增加查詢並行。反之，請使用容量保留來管理和擴展單一帳戶內的查詢處理需求。
### 考慮其他服務中的配額
當 Athena 執行查詢時，它可以呼叫其他強制執行配額的服務。在查詢執行期間，Athena 可以對 AWS Glue Data Catalog、Amazon S3 和其他 AWS 服務進行 API 呼叫，例如 IAM 和 AWS KMS。如果您使用[聯合查詢](federated-queries.md)，Athena 也會呼叫 AWS Lambda。所有這些服務都有自己的限制和配額，可以超過。當查詢執行遇到來自這些服務的錯誤時，其便會失敗並包含來源服務的錯誤。重試可復原的錯誤，但如果問題無法及時自行解決，查詢仍可能失敗。請務必徹底閱讀錯誤訊息，以判斷其是來自 Athena 還是來自其他服務。此效能調校區段涵蓋一些相關錯誤。
如需有關解決 Amazon S3 Service Quotas 造成的錯誤的資訊，請參閱本文件稍後的 [避免檔案太多](performance-tuning-data-optimization-techniques.md#performance-tuning-avoid-having-too-many-files)。如需有關 Amazon S3 效能最佳化的詳細資訊，請參閱《Amazon S3 使用者指南》**中的[最佳實務設計模式：最佳化 Amazon S3 效能](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html)。
## 減少「資源不足」錯誤
Athena 會在分散式查詢引擎中執行查詢。當您提交查詢時，Athena 引擎查詢規劃程式會預估執行查詢所需的運算容量，並相應地準備運算節點叢集。某些查詢 (例如 DDL 查詢) 只在一個節點上執行。大型資料集的複雜查詢可在更大的叢集上執行。節點是統一的，具有相同的記憶體、CPU 和磁碟組態。Athena 透過橫向擴展 (而非向上擴展) 來處理要求更高的查詢。
有時候，查詢的需求會超過執行查詢的叢集的可用資源。發生這種情況時，查詢會失敗，並顯示錯誤在此擴展因數下查詢耗盡的資源。
最常耗盡的資源是記憶體，但在極少數情況下，也可以是磁碟空間。當引擎執行聯結或視窗函數時，通常會發生記憶體錯誤，但也可能發生在不同的計數和彙總中。
即使查詢失敗並出現「資源不足」錯誤一次，當您再次執行時，其可能會成功。查詢執行不是確定性的。載入資料所花費時間以及如何在節點上分配中繼資料集等因素，可能會導致資源使用量不同。例如，假設一個查詢聯結兩個資料表，並且聯結條件的值分佈存在很大偏差。這樣的查詢在大多數時間都可以成功，但是當最常見的值最終由相同節點處理時，偶爾會失敗。
若要避免查詢超出可用資源，請使用本文件中提及的效能調校秘訣。具體而言，有關如何最佳化會耗盡可用資源之查詢的秘訣，請參閱 [最佳化聯結](performance-tuning-query-optimization-techniques.md#performance-tuning-optimizing-joins)、[減少視窗函式的範圍，或將其移除](performance-tuning-query-optimization-techniques.md#performance-tuning-optimizing-window-functions) 和 [使用近似值最佳化查詢](performance-tuning-query-optimization-techniques.md#performance-tuning-optimizing-queries-by-using-approximations)。
# 最佳化查詢
使用本節中描述的查詢最佳化技術，可加快查詢執行速度，或做為 Athena 中超出資源限制的查詢解決方法。
## 最佳化聯結
在分散式查詢引擎中執行聯結的策略有很多。最常見的兩個是分散式雜湊聯結和具有複雜聯結條件的查詢。
### 在分散式雜湊聯結中，將大型資料表放在左側，小型資料表放在右側
最常見的聯結類型使用對等比較做為聯結條件。Athena 以分散式雜湊聯結的形式執行此類聯結。
在分散式雜湊聯結中，引擎會從聯結的一側建置一個查詢表 (雜湊資料表)。這一側稱為*建置端*。建置端的記錄分散在多個節點上。每個節點為其子集建置一個查詢表。接著，聯結的另一端稱為*探查端*，會透過節點進行串流。探查端的記錄以與建置端相同的方式分散在節點上。這樣會啟用每個節點，以透過在其自己的查詢表中查詢相符記錄來執行聯結。
當從聯結的建置端建立的查詢表不適合放入記憶體中時，查詢可能會失敗。即使建置端的總大小小於可用記憶體，如果記錄的分佈存在很大偏差，查詢也可能會失敗。在極端情況下，所有記錄可能具有相同的聯結條件值，並且必須放入單一節點上的記憶體中。如果將一組值傳送至相同節點，且值加起來超過可用記憶體，即使是查詢偏差較小，也可能會失敗。節點確實可以將記錄溢寫至磁碟，但溢出會降低查詢執行速度，並且可能不足以防止查詢失敗。
Athena 會嘗試重新排序聯結，以使用較大的關係做為探查端，而較小的關係做為建置端。不過，由於 Athena 不會管理資料表中的資料，所以資訊有限，而且通常必須假設第一個資料表較大，第二個資料表較小。
使用以等值為基礎的聯結條件撰寫聯結時，假設 `JOIN` 關鍵字左側的資料表是探查端，右側的資料表是建置端。確保正確的資料表 (建置端) 是較小的資料表。如果無法使聯結的建置端足夠小以放入記憶體中，請考慮執行多個聯結建置資料表子集的查詢。
### 使用 EXPLAIN 來分析具有複雜聯結的查詢
具有複雜聯結條件的查詢 (例如，使用 `LIKE`、`>` 或其他運算子的查詢) 通常運算要求較高。在最壞的情況下，聯結一端的每條記錄必須與聯結另一端的每條記錄進行比較。由於執行時間會隨著記錄數量的平方而增加，因此此類查詢會有超過最大執行時間的風險。
若要了解 Athena 將如何事先執行查詢，您可以使用 `EXPLAIN` 陳述式。如需詳細資訊，請參閱[在 Athena 使用 EXPLAIN 和 EXPLAIN ANALYZE](athena-explain-statement.md)及[了解 Athena EXPLAIN 陳述式結果](athena-explain-statement-understanding.md)。
## 減少視窗函式的範圍，或將其移除
由於視窗函數是資源密集型操作，所以它們可能會使查詢執行緩慢甚至失敗，並顯示在此擴展因數下查詢耗盡的資源。視窗函數將其操作的所有記錄保留在記憶體中，以便計算其結果。當視窗非常大時，視窗函數可能會耗盡記憶體。
為了確保您的查詢在可用的記憶體限制內執行，請減少視窗函數操作的視窗大小。為此，您可以新增 `PARTITIONED BY` 子句或縮小現有分割區子句的範圍。
### 使用非視窗函式
有時，具有視窗函數的查詢可以在沒有視窗函數的情況下重寫。例如，您可以使用 `ORDER BY` 和 `LIMIT`，而不是使用 `row_number` 來尋找前 `N` 個記錄。您可以使用彙總函數 (例如 [max\$1by](https://trino.io/docs/current/functions/aggregate.html#max_by)、[min\$1by](https://trino.io/docs/current/functions/aggregate.html#min_by) 和 [arbitrary](https://trino.io/docs/current/functions/aggregate.html#arbitrary))，而不是使用 `row_number` 或 `rank` 來重複記錄。
例如，假設您的資料集包含來自感應器的更新。感應器會定期報告其電池狀態，並包含一些中繼資料，例如位置。如果您想知道每個感應器及其位置的最新電池狀態，可以使用以下查詢：
```
SELECT sensor_id,
arbitrary(location) AS location,
max_by(battery_status, updated_at) AS battery_status
FROM sensor_readings
GROUP BY sensor_id
```
因為每筆記錄的中繼資料 (例如位置) 都相同，因此您可以使用 `arbitrary` 函數從群組中選擇任何值。
要獲取最新的電池狀態，您可以使用 `max_by` 函數。`max_by` 函數從找到另一個資料欄的最大值的記錄中選擇資料欄的值。在此範例中，它會傳回群組內上次更新時間的記錄的電池狀態。與具有視窗函數的對等查詢相比，此查詢執行速度更快，而且使用的記憶體更少。
## 最佳化彙總
當 Athena 執行彙總時，它會使用 `GROUP BY` 子句中的資料欄，跨不同的工作節點分佈記錄。為了使相符記錄與群組的任務盡可能有效率，節點會嘗試將記錄放入記憶體中，但必要時會將記錄溢寫至磁碟。
避免在 `GROUP BY` 子句中包含備援資料欄也是個不錯的主意。由於較少的資料欄需要較少的記憶體，因此使用較少資料欄描述群組的查詢會更有效率。數值資料欄使用的記憶體也少於字串。例如，當您彙總同時具有數值類別 ID 和類別名稱的資料集時，請僅使用 `GROUP BY` 子句中的類別 ID 資料欄。
有時候，查詢會在 `GROUP BY` 子句中包含資料欄，以解決資料欄必須是 `GROUP BY` 子句的一部分或彙總表達式的事實。如果未遵循此規則，您可能會收到以下錯誤訊息：
EXPRESSION\$1NOT\$1AGGREGATE：行 1:8：「類別」必須是一個彙總表達式或出現在 GROUP BY 子句
若要避免在 `GROUP BY` 子句中新增備援資料欄，您可以使用[任意](https://trino.io/docs/current/functions/aggregate.html#arbitrary)函數，如下列範例所示。
```
SELECT country_id,
arbitrary(country_name) AS country_name,
COUNT(*) AS city_count
FROM world_cities
GROUP BY country_id
```
`ARBITRARY` 函數會從群組中傳回任意值。當您知道群組中的所有記錄都具有相同的資料欄值，但該值無法識別群組時，此函數非常有用。
## 最佳化前 N 個查詢
`ORDER BY` 子句會以排序順序傳回查詢的結果。Athena 使用分散式排序，在多個節點上平行執行排序操作。
如果您並不需要對結果進行排序，請避免新增 `ORDER BY` 子句。另外，如果並非絕對必要，請避免新增 `ORDER BY` 到內部查詢。在許多情況下，查詢規劃程式可以移除備援排序，但不保證一定如此。此規則的例外是，如果內部查詢正在執行前 `N` 個操作，例如尋找最新的 `N` 個值或最常用的 `N` 個值。
當 Athena 發現 `ORDER BY` 與 `LIMIT` 時，就會明白您正在執行前 `N` 個查詢，並相應地使用專用操作。
**注意**
雖然 Athena 也經常可以偵測視窗函數 (例如使用前 `N` 個的 `row_number`)，但我們建議使用 `ORDER BY` 和 `LIMIT` 的較簡單版本。如需詳細資訊，請參閱[減少視窗函式的範圍，或將其移除](#performance-tuning-optimizing-window-functions)。
## 僅包含必填資料欄
如果您並不需要資料欄，請不要將其包含在查詢中。查詢必須處理的資料越少，執行速度就越快。這可以減少所需的記憶體數量，以及必須在節點之間傳送的資料量。如果您使用的是單欄式檔案格式，減少資料欄數量也會減少從 Amazon S3 讀取的資料量。
Athena 對結果中的資料欄數量沒有特定限制，但是執行查詢的方式會限制可能的資料欄合併大小。資料欄的合併大小包括它們的名稱和類型。
例如，下列錯誤是由超出關係描述項大小限制的關係造成的：
GENERIC\$1INTERNAL\$1ERROR: io.airlift.bytecode.CompilationException
若要解決此問題，請減少查詢中的資料欄數量或建立子查詢，並使用擷取較少量資料的 `JOIN`。如果您有在最外層查詢中執行 `SELECT *` 的查詢，則應將 `*` 變更為僅包含所需資料欄的清單。
## 使用近似值最佳化查詢
Athena 支援[近似彙總函數](https://trino.io/docs/current/functions/aggregate.html#appro)，用於計算獨特值、最常出現的值、百分位數 (包括近似中位數)，以及建立直方圖。每當不需要確切值時，請使用這些函數。
與 `COUNT(DISTINCT col)` 操作不同，[approx\$1distinct](https://trino.io/docs/current/functions/aggregate.html#approx_distinct) 使用的記憶體更少且執行速度更快。同樣，使用 [numeric\$1histogram](https://trino.io/docs/current/functions/aggregate.html#numeric_histogram) (而不是[直方圖](https://trino.io/docs/current/functions/aggregate.html#histogram)) 使用了近似方法，因此所需的記憶體更少。
## 最佳化 LIKE
您可以使用 `LIKE` 來查找相符字串，但對於長字串而言，此為計算密集型。[regexp\$1like](https://trino.io/docs/current/functions/regexp.html#regexp_like) 函數在大多數情況下是一個更快的替代方案，並且還提供了更多的靈活性。
通常，您可以透過錨定要尋找的子字串來最佳化搜尋。*例如，如果您正在尋找字首，最好使用 '*substr*%' 而不是 '%substr*%'。或者，如果您使用的是 `regexp_like`，則為 '^*substr*'。
## 使用 UNION ALL 而非 UNION
`UNION ALL` 和 `UNION` 是兩種將兩個查詢結果合併為一個結果的方法。`UNION ALL` 將第一個查詢中的記錄與第二個查詢中的記錄串連起來，且 `UNION` 會執行相同的操作，但也會移除重複項目。`UNION` 需要處理所有記錄並找到重複項目，此為記憶體和計算密集型，不過 `UNION ALL` 是一個相對快速的操作。除非您需要重複記錄，否則請使用 `UNION ALL` 以獲得最佳效能。
## 對大型結果集使用 UNLOAD
當查詢結果預期很大 (例如，數萬個資料列或更多) 時，請使用 UNLOAD 匯出結果。在大多數情況下，這比執行規則查詢更快，並且使用 `UNLOAD` 也可以讓您更好地控制輸出。
查詢完成執行後，Athena 會將結果以單一未壓縮的 CSV 檔案形式存放在 Amazon S3 上。這比 `UNLOAD` 需要更長的時間，不僅因為結果未壓縮，而且還因為操作無法平行化。相反地，`UNLOAD` 會直接從工作節點寫入結果，並充分利用運算叢集的平行處理。此外，您可以設定 `UNLOAD`，以壓縮格式和其他檔案格式 (例如 JSON 和 Parquet) 寫入結果。
如需詳細資訊，請參閱[UNLOAD](unload.md)。
## 使用 CTAS 或 Glue ETL 將常用的彙總具體化
「具體化」查詢是一種透過儲存預先計算的複雜查詢結果 (例如，彙總和聯結) 以便在後續查詢中重複使用，來加速查詢效能的方法。
如果您的許多查詢包含相同的聯結和彙總，您可以將通用子查詢具體化為新資料表，然後針對該資料表執行查詢。您可以使用 [從查詢結果建立資料表 (CTAS)](ctas.md) 或專用 ETL 工具 (例如 [Glue ETL](https://aws.amazon.com/glue)) 來建立新的資料表。
例如，假設您的儀表板中包含顯示訂單資料集的不同層面的小工具。每個小工具都有自己的查詢，但所有查詢會共用相同的聯結和篩選條件。訂單資料表會與明細項目資料表結合在一起，而且有一個篩選條件，可僅顯示過去三個月。如果您識別這些查詢的常用功能，您可以建立小工具可使用的新資料表。這樣可以減少重複並提高效能。缺點是您必須將資料表保持在最新狀態。
## 重複使用查詢結果
同一查詢在短時間內執行多次非常常見。例如，當多個人開啟相同的資料儀表板時，就會發生這種情況。執行查詢時，您可以告訴 Athena 重複使用先前計算的結果。您可以指定要重複使用的結果的最長期限。如果先前在該時間範圍內執行同一查詢，Athena 會傳回這些結果，而不是再次執行查詢。如需詳細資訊，請參閱此處《*Amazon Athena 使用者指南*》中的 [在 Athena 中重複使用查詢結果](reusing-query-results.md)，以及 *AWS 大數據部落格*中的[使用 Amazon Athena 查詢結果重複使用降低成本和提升查詢效能](https://aws.amazon.com/blogs/big-data/reduce-cost-and-improve-query-performance-with-amazon-athena-query-result-reuse/)。
# 最佳化資料
效能不僅取決於查詢，而且還取決於資料集的組織方式，以及資料集使用的檔案格式和壓縮。
## 分割您的資料
分割會將您的資料表分為多個部分，並根據日期、國家或地區等屬性將相關資料保留在一起。分割區索引鍵可可做為虛擬資料欄。您可以在建立資料表時定義分割區索引鍵，並使用它們來篩選查詢。當您篩選分割區索引鍵資料欄時，只會讀取相符分割區中的資料。例如，如果您的資料集依日期進行分割，而您的查詢具有僅符合上週的篩選條件，則只會讀取上週的資料。如需有關分割區的詳細資訊，請參閱 [分割您的資料](partitions.md)。
## 選擇將支援您查詢的分割區索引鍵
由於分割會對查詢效能產生重大影響，因此在設計資料集和資料表時，請務必仔細考慮分割的方式。分割區索引鍵太多可能會導致資料集分段為過多的檔案且各個檔案過小。相反地，分割區索引鍵太少或完全沒有分割，會導致查詢掃描的資料超過必要的資料。
### 避免最佳化罕見查詢
一個好的策略是針對最常見的查詢進行最佳化，並避免針對罕見查詢進行最佳化。例如，如果您的查詢瀏覽時間跨度 (天數)，即使某些查詢會篩選至該級別，也不要按小時進行分割。如果您的資料具有精確的時間戳記資料欄，則依小時篩選的罕見查詢可以使用時間戳記資料欄。即使極少數情況掃描的資料超過必要的資料，為了極少數情況而降低整體效能通常不是一種很好的權衡。
若要減少查詢必須掃描的資料量，進而改善效能，請使用單欄式檔案格式，並保持記錄排序。請依時間戳記排序記錄，而不是依小時分割。對於在較短時間視窗上進行查詢，按時間戳記排序的效率幾乎與依小時分割一樣有效。此外，依時間戳記排序通常不會損害時間視窗上的查詢效能 (以天數計算)。如需詳細資訊，請參閱[使用單欄式檔案格式](#performance-tuning-use-columnar-file-formats)。
請注意，如果所有分割區索引鍵都有述詞，則對具有數萬個分割區的資料表進行查詢的效果會更好。這是為最常見的查詢設計分割結構的另一個原因。如需詳細資訊，請參閱[依等式查詢分割區](#performance-tuning-query-partitions-by-equality)。
## 使用分割區投影
分割區投影是一種 Athena 功能，可儲存不在 中的分割區資訊 AWS Glue Data Catalog，但做為 資料表屬性中的規則 AWS Glue。當 Athena 在設定了分割區投影的資料表上計劃查詢時，其會讀取資料表的分割區投影規則。Athena 會根據查詢和規則，計算要在記憶體中讀取的分割區，而不是在 AWS Glue Data Catalog中查找分割區。
除了簡化分割區管理之外，分割區投影還可以改善具有大量分割區的資料集的效能。當查詢包含範圍而不是分割區索引鍵的特定值時，在目錄中查找相符分割區所花費的時間越長，所需的分割區就越多。使用分割區投影，可以在記憶體中計算篩選條件而無需進入目錄，並且速度可以更快。
在某些情況下，分割區投影可能會導致效能變差。一個範例就是當資料表為「稀疏」時。稀疏資料表沒有分割區投影組態所描述的分割區索引鍵值的每個排列資料。使用稀疏資料表時，從查詢和分割區投影組態計算的一組分區都會列在 Amazon S3 上，即使它們沒有資料也一樣。
當您使用分割區投影時，請務必在所有分割區索引鍵上包含述詞。縮小可能值的範圍，以避免不必要的 Amazon S3 清單。假設一個分割區索引鍵的範圍包含一百萬個值，以及查詢在該分割區索引鍵上沒有任何篩選條件。若要執行查詢，Athena 必須執行至少一百萬個 Amazon S3 清單操作。查詢特定值時，無論您是使用分割區投影還是將分割區資訊儲存在目錄中，查詢速度都是最快的。如需詳細資訊，請參閱[依等式查詢分割區](#performance-tuning-query-partitions-by-equality)。
當您設定分割區投影的資料表時，請確定您指定的範圍是合理的。如果查詢不包含分割區索引鍵的述詞，則會使用該索引鍵範圍內的所有值。如果您的資料集是在特定日期建立的，請使用該日期做為任何日期範圍的起點。使用 `NOW` 作為日期範圍的結束。避免使用具有大量值的數值範圍，並考慮改用[注入](partition-projection-dynamic-id-partitioning.md#partition-projection-injection)類型。
如需有關分割區投影的詳細資訊，請參閱[透過 Amazon Athena 使用分割區投影](partition-projection.md)。
## 使用分割區索引
分割區索引是 中的一項功能 AWS Glue Data Catalog ，可改善具有大量分割區之資料表的分割區查詢效能。
目錄中的分割區清單就像是關聯式資料庫中的資料表。此資料表包含分割區索引鍵的資料欄，以及分割區位置的其他資料欄。當您查詢分割區資料表時，會掃描此資料表來查詢分割區位置。
就像關聯式資料庫一樣，您可以透過新增索引來提高查詢的效能。您可以新增多個索引，以支援不同的查詢模式。 AWS Glue Data Catalog 分割區索引支援等式運算子和比較運算子`>`，例如 `>=`、 和 與運算`AND`子`<`結合。如需詳細資訊，請參閱《 *AWS Glue 開發人員指南*》中的[在 中使用分割區索引 AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/partition-indexes.html)，以及《 *AWS 大數據部落格*》中的[使用 AWS Glue Data Catalog 分割區索引改善 Amazon Athena 查詢效能](https://aws.amazon.com/blogs/big-data/improve-amazon-athena-query-performance-using-aws-glue-data-catalog-partition-indexes/)。
## 始終使用 STRING 做為分割區索引鍵類型
當您查詢分割區索引鍵時，請記住 Athena 要求分割區索引鍵為類型 `STRING`，才能將分割區篩選下推至 AWS Glue。如果分割區數目不小，使用其他類型可能會導致效能變差。如果您的分割區索引鍵值為 date-like 或 number-like，請將它們轉換為查詢中的適當類型。
## 移除舊的和空的分割區
如果您從 Amazon S3 上的分割區移除資料 (例如，使用 Amazon S3 [生命週期](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html))，您也應該從 AWS Glue Data Catalog中移除分割區項目。在查詢規劃期間，與查詢相符的任何分割區都會列在 Amazon S3 上。如果您有許多空的分割區，列出這些分割區的負荷可能會產生不利影響。
此外，如果您有數千個分割區，請考慮移除不再相關的舊資料的分割區中繼資料。例如，如果查詢從未查看超過一年的資料，您可以定期移除舊分割區的分割區中繼資料。如果分割區數目增加到數萬個，移除未使用的分割區可以加速查詢，其中這些查詢不包含所有分割區索引鍵的述詞。如需有關在查詢中包含所有分割區索引鍵的述詞的資訊，請參閱 [依等式查詢分割區](#performance-tuning-query-partitions-by-equality)。
## 依等式查詢分割區
在所有分割區索引鍵上包含等式述詞的查詢執行速度更快，因為可以直接載入分割區中繼資料。避免查詢中一個或多個分割區索引鍵沒有述詞，或述詞選擇了範圍值。對於此類查詢，必須篩選所有分割區的清理，以找到相符的值。對於大多數資料表而言，負荷會降至最低，但對於具有數萬個或更多分割區的資料表而言，負荷可能會變得很大。
如果無法重寫查詢以透過等式篩選分割區，則可以嘗試分割區投影。如需詳細資訊，請參閱[使用分割區投影](#performance-tuning-use-partition-projection)。
## 避免使用 MSCK REPAIR TABLE 進行分割區維護
由於 `MSCK REPAIR TABLE` 可能需要很長的時間才能執行，並且僅會新增分割區，而不會移除舊的分割區，因此不是管理分割區的有效方法 (請參閱 [考量和限制](msck-repair-table.md#msck-repair-table-considerations))。
使用 [AWS Glue Data Catalog API](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-catalog.html)、[ALTER TABLE ADD PARTITION](alter-table-add-partition.md) 或 [AWS Glue 爬蟲程式](https://docs.aws.amazon.com/glue/latest/dg/crawler-running.html)可以更好地手動管理分割區。或者，您也可以使用分割區投影，這樣就不需要完全管理分割區。如需詳細資訊，請參閱[透過 Amazon Athena 使用分割區投影](partition-projection.md)。
## 驗證您的查詢是否與分割結構相容
您可以使用 [`EXPLAIN`](athena-explain-statement.md) 陳述式預先檢查查詢將掃描的分割區。使用 `EXPLAIN` 關鍵字作為查詢字首，然後在 `EXPLAIN` 輸出底部附近查找每個資料表的來源片段 (例如，`Fragment 2 [SOURCE]`)。查找右側被定義為分割區索引鍵的指派。下方的列包含一份清單，列出執行查詢時將要掃描的該分割區索引鍵的所有值。
例如，假設您對具有 `dt` 分割區索引鍵的資料表進行查詢，並使用 `EXPLAIN` 作為查詢字首。如果查詢中的值是日期，並且篩選條件選取了三天的範圍，則 `EXPLAIN` 輸出可能如下所示：
```
dt := dt:string:PARTITION_KEY
:: [[2023-06-11], [2023-06-12], [2023-06-13]]
```
`EXPLAIN` 輸出顯示，規劃程式找到了此分割區索引鍵的三個值，且其與查詢相符。它還顯示了這些值是什麼。如需有關使用 `EXPLAIN` 的詳細資訊，請參閱 [在 Athena 使用 EXPLAIN 和 EXPLAIN ANALYZE](athena-explain-statement.md) 和 [了解 Athena EXPLAIN 陳述式結果](athena-explain-statement-understanding.md)。
## 使用單欄式檔案格式
專為分散式分析工作負載而設計的單欄式檔案格式，例如 Parquet 和 ORC。它們依資料欄而非資料列整理資料。以單欄式格式整理資料具有下列優點：
+ 僅會載入查詢所需的資料欄
+ 減少需要載入的整體資料量
+ 資料欄值會一起存放，因此可以有效地壓縮資料
+ 檔案可以包含允許引擎略過載入不需要的資料的中繼資料
做為如何使用檔案中繼資料的範例，檔案中繼資料可以包含有關資料頁面中最小值和最大值的資訊。如果查詢的值不在中繼資料中註明的範圍內，則可以略過該頁面。
使用此中繼資料提高效能的一種方法是，確定對檔案中的資料進行排序。例如，假設您有查詢會尋找 `created_at` 項目在短時間範圍內的記錄。如果您的資料依 `created_at` 資料欄排序，Athena 可以使用檔案中繼資料中的最小值和最大值來略過資料檔案中不需要的部分。
使用單欄式檔案格式時，請確定檔案不會太小。如 [避免檔案太多](#performance-tuning-avoid-having-too-many-files) 中所述，含有許多小型檔案的資料集會造成效能問題。對於單欄式檔案格式而言，尤其如此。對於小型檔案，單欄式檔案格式的負荷超過優勢。
請注意，Parquet 和 ORC 在內部依資料列群組 (Parquet) 和條紋 (ORC) 進行整理。資料列群組的預設大小為 128 MB，而條紋的預設大小則為 64 MB。如果您有許多資料欄，您可以增加資料列群組和條紋大小，以提升效能。不建議將資料列群組或條紋大小減少至小於其預設值。
若要將其他資料格式轉換為 Parquet 或 ORC，您可以使用 AWS Glue ETL 或 Athena。如需詳細資訊，請參閱[轉換為單欄式格式](columnar-storage.md#convert-to-columnar)。
## 壓縮資料
Athena 支援各種壓縮格式。查詢壓縮資料的速度更快，也更便宜，因為您需要為解壓縮前掃描的位元組數量進行支付。
[gzip](https://www.gnu.org/software/gzip/) 格式提供了良好的壓縮比，並且在其他工具和服務中具有廣泛的支援。[zstd](https://facebook.github.io/zstd/) (Zstandard) 格式是一種較新的壓縮格式，可使效能和壓縮比之間達到良好的平衡。
壓縮文字檔案 (例如 JSON 和 CSV 資料) 時，請嘗試在檔案數量和檔案大小之間取得平衡。大多數壓縮格式都要求讀者從頭開始讀取檔案。這表示一般而言，壓縮的文字檔案無法平行處理。大型未壓縮的檔案通常會在工作者之間分割，以在查詢處理期間達到更高的平行處理能力，但大多數壓縮格式無法執行這項操作。
如 [避免檔案太多](#performance-tuning-avoid-having-too-many-files) 中所述，檔案最好不要太多也不宜過少。由於檔案數目是可處理查詢的工作者數量限制，因此對於壓縮檔案而言，此規則尤其如此。
如需有關在 Athena 中使用壓縮的詳細資訊，請參閱 [在 Athena 中使用壓縮](compression-formats.md)。
## 使用歸納來查詢具有高基數的索引鍵
歸納是一種技術，可根據其中一個資料欄的值，將記錄分佈至個別檔案中。這能確保具有相同值的所有記錄都位於同一個檔案中。當您擁有高基數的索引鍵，而且許多查詢都會查詢索引鍵的特定值時，歸納功能非常有用。
例如，假設您查詢特定使用者的一組記錄。如果資料是依使用者 ID 歸納，Athena 會事先知道哪些檔案包含特定 ID 的記錄，哪些檔案不包含。這可讓 Athena 僅讀取包含 ID 的檔案，進而大幅減少讀取的資料量。這同意也可減少在資料中搜尋特定 ID 所需的運算時間。
### 當查詢頻繁搜尋資料欄中的多個值時，請避免使用歸納
當查詢經常在資料歸納的資料欄中搜尋多個值時，歸納的價值就不太重要。查詢的值越多，必須讀取所有或大部分檔案的可能性就越高。例如，如果您有三個儲存貯體，而查詢會尋找三個不同的值，則可能必須讀取所有檔案。當查詢在查找單一值時，歸納效果最佳。
如需詳細資訊，請參閱[使用分割和歸納](ctas-partitioning-and-bucketing.md)。
## 避免檔案太多
由許多小型檔案組成的資料集會導致整體查詢效能不佳。Athena 計劃查詢時，會列出所有分割區位置，而這需要花費一些時間。處理和請求每個檔案也會產生運算負載。因此，從 Amazon S3 載入單一較大的檔案比從許多較小的檔案載入相同記錄更快。
在極端情況下，您可能會遇到 Amazon S3 服務限制。針對單一索引分割區，Amazon S3 每秒最多可支援 5,500 個請求。最初，儲存貯體會被視為單一索引分割區，但隨著請求載入的增加，它可以分割成多個索引分割區。
Amazon S3 會根據索引鍵字首查詢請求模式和分割。如果您的資料集包含數千個檔案，則來自 Athena 的請求可能會超出請求的配額。即使檔案較少，如果對同一個資料集進行多個並行查詢，則可能會超過配額。存取相同檔案的其他應用程式可能會增加請求總數。
當超出請求率 `limit` 時，Amazon S3 會傳回下列錯誤。此錯誤已包含在 Athena 查詢的狀態資訊中。
SlowDown：請降低請求率
若要進行疑難排解，請先判斷錯誤是由單一查詢還是由可讀取相同檔案的多個查詢造成的。如果是後者，請協調查詢的執行，以便它們不會同時執行。為此，請在應用程式中新增佇列機制，甚至是重試。
如果執行單一查詢觸發錯誤，請嘗試合併資料檔案或修改查詢，以讀取較少的檔案。合併小型檔案的最佳時間是在將其寫入之前。為此，請考慮下列技巧：
+ 變更寫入檔案的程序，以寫入較大的檔案。例如，您可以在寫入記錄之前緩衝一段較長的時間。
+ 將檔案放在 Amazon S3 上的某個位置，然後使用 Glue ETL 等工具將其合併為較大的檔案。然後，將較大的檔案移至資料表所指向的位置。如需詳細資訊，請參閱《 *AWS Glue 開發人員指南*》中的[讀取較大群組中的輸入檔案](https://docs.aws.amazon.com/glue/latest/dg/grouping-input-files.html)，以及[如何在 re：Post 知識中心中設定 AWS Glue ETL 任務以輸出較大的檔案？](https://repost.aws/knowledge-center/glue-job-output-large-files)。 *AWS *
+ 減少分割區索引鍵的數量。當您的分割區索引鍵太多時，每個分割區可能只有少數記錄，因此會產生過多的小型檔案。如需有關決定要建立哪些分割區的資訊，請參閱 [選擇將支援您查詢的分割區索引鍵](#performance-tuning-pick-partition-keys-that-will-support-your-queries)。
## 避免分割區以外的其他儲存體階層
若要避免查詢規劃負荷，請將檔案儲存在每個分割區位置的單層式結構中。請勿使用任何其他目錄階層。
Athena 計劃查詢時，會列出與查詢相符的所有分割區中的所有檔案。雖然 Amazon S3 本身沒有目錄，但慣例是將 `/` 斜線解譯為目錄分隔符號。當 Athena 列出分割區位置時，其會遞歸列出找到的任何目錄。當分割區內的檔案整理成階層時，會出現多輪清單。
當所有檔案都直接位於分割區位置時，大多數情況下只需執行一個清單操作。但是，如果一個分割區中有 1000 個以上的檔案，則需要多個連續清單操作，因為 Amazon S3 每個清單操作只會傳回 1000 個物件。分區中有 1000 多個檔案也可能會導致其他更嚴重的效能問題。如需詳細資訊，請參閱[避免檔案太多](#performance-tuning-avoid-having-too-many-files)。
## 僅在必要時使用 SymlinkTextInputFormat
使用 [https://athena.guide/articles/stitching-tables-with-symlinktextinputformat](https://athena.guide/articles/stitching-tables-with-symlinktextinputformat) 技術可以是一種解決相關情況的方法，當資料表的檔案沒有整齊地整理到分割區中時。例如，當所有檔案都使用相同的字首，或是具有不同結構描述的檔案位於相同位置時，符號連結可能很有用。
但是，使用符號連結會為查詢執行增加間接層級。這些間接層級會影響整體效能。必須讀取符號連結檔案，並且必須列出它們定義的位置。如此會新增至 Amazon S3 的多次往返，而這並非常見 Hive 資料表所需的。總之，只有當沒有更好的選項 (例如整理檔案) 可用時，您才應使用 `SymlinkTextInputFormat`。
# 使用單欄式儲存格式
[Apache Parquet](https://parquet.apache.org) 和 [ORC](https://orc.apache.org/) 是經過最佳化的單欄式儲存格式，可快速擷取資料並用於 AWS 分析應用程式。
單欄式儲存格式具有以下特點，使其適用於 Athena：
+ *針對資料欄資料類型選擇壓縮演算法來壓縮欄*，可以節省 Amazon S3 中的儲存空間，並在查詢處理期間降低磁碟空間和輸入/輸出。
+ Parquet 和 ORC 中的*述詞下推*，可讓 Athena 查詢僅擷取需要的區塊，進而提高查詢效能。當 Athena 查詢從您的資料中取得特定資料欄值時，它會使用資料區塊述詞 (例如上限/下限值) 的統計資料，判斷要讀取或略過該區塊。
+ Parquet 和 ORC 中的*資料分割*，可讓 Athena 將資料的讀取分割給多個讀取器，在其查詢處理期間增加平行處理。
若要將您現有的原始資料從其他儲存格式轉換為 Parquet 或 ORC，您可以在 Athena 中執行 [CREATE TABLE AS SELECT (CTAS)](ctas.md) 查詢，並將資料儲存格式指定為 Parquet 或 ORC，或使用 AWS Glue 爬蟲程式。
## 在 Parquet 與 ORC 之間進行選擇
ORC (優化列單欄式) 和 Parquet 之間的選擇取決於您的特定使用需求。
Apache Parquet 提供高效的資料壓縮和編碼機制，非常適合用於執行複雜查詢和處理大量資料。為與 [Apache Arrow](https://arrow.apache.org/) 搭配使用，Parquet 進行了優化，因此如果您使用與 Arrow 相關的工具，Parquet 可能比較有利。
ORC 可以很有效率地存放 Hive 資料。ORC 檔案通常比 Parquet 檔案要小，因此 ORC 索引可以加快查詢速度。此外，ORC 支援複雜類型，例如結構、映射和清單。
在 Parquet 或 ORC 間選擇時，請考慮以下因素：
**查詢效能** – 由於 Parquet 能夠支援更廣泛的查詢類型，因此，如果您打算執行複雜的查詢，則 Parquet 可能是更好的選擇。
**複雜的資料類型** – 如果您使用的是複雜的資料類型，那麼 ORC 可能是更好的選擇，因為它能支援更廣泛的複雜資料類型。
**檔案大小** – 如果需要考慮磁碟空間，ORC 通常可產生較小的檔案，進而降低儲存成本。
**壓縮** – Parquet 和 ORC 均可提供良好的壓縮，但最適合您的最佳格式主要取決於您的特定使用案例。
**演進** – Parquet 和 ORC 均可支援支持結構描述變化，這意味著您可以隨時間新增、刪除或修改資料欄。
對於大數據應用程式來說，Parquet 和 ORC 都是不錯的選擇，但在選擇之前，請考慮您的案例需求。您可能希望對資料和查詢執行基準測試，以查看哪種格式更適合您的使用案例。
## 轉換為單欄式格式
將 JSON 或 CSV 等來源資料輕鬆轉換為單欄式格式的選項，包括使用 [CREATE TABLE AS](ctas.md) 查詢或執行 AWS Glue中的任務。
+ 使用 `CREATE TABLE AS` (CTAS) 查詢，只需一個步驟即可將資料轉換為 Parquet 或 ORC。如需範例，請參閱 [CTAS 查詢的範例](ctas-examples.md) 頁面上的[範例：將查詢結果寫為不同格式](https://docs.aws.amazon.com/athena/latest/ug/ctas-examples.html#ctas-example-format)。
+ 如需有關使用 Athena for ETL 將資料從 CSV 轉換為 Parquet 的詳細資訊，請參閱 [使用 CTAS 和 INSERT INTO 以進行 ETL 和資料分析](ctas-insert-into-etl.md)。
+ 如需有關執行 AWS Glue 任務以將 CSV 資料轉換為 Parquet 的資訊，請參閱 AWS 大數據部落格文章中的「將資料從 CSV 轉換為 Parquet 格式」一節[使用 AWS Glue 和 Amazon S3 建置資料湖基礎](https://aws.amazon.com/blogs/big-data/build-a-data-lake-foundation-with-aws-glue-and-amazon-s3/)。 AWS Glue 支援使用相同的技術將 CSV 資料轉換為 ORC，或 JSON 資料轉換為 Parquet 或 ORC。
# 使用分割和歸納
分割和歸納是減少執行查詢時 Athena 必須掃描的資料量的兩種方法。分割和歸納互為補充，且可搭配使用。減少掃描的資料量可改善查詢效能並降低成本。如需有關 Athena 查詢效能的一般指導方針，請參閱 [Amazon Athena 的十大效能調校秘訣](https://aws.amazon.com/blogs/big-data/top-10-performance-tuning-tips-for-amazon-athena/)。
**Topics**
+ [什麼是分割？](ctas-partitioning-and-bucketing-what-is-partitioning.md)
+ [什麼是歸納？](ctas-partitioning-and-bucketing-what-is-bucketing.md)
+ [其他資源](ctas-partitioning-and-bucketing-additional-resources.md)
# 什麼是分割？
分割表示根據資料的特定屬性，將資料整理到 Amazon S3 上的目錄 (或「字首」)。這類屬性稱為分割區索引鍵。常見的分割區索引鍵是日期或一些其他時間單位，例如年份或月份。不過，資料集可以依多個索引鍵進行分割。例如，有關產品銷售的資料可能依日期、產品類別和市場進行分割。
## 決定如何分割
分割區索引鍵的理想候選者是始終或經常在查詢中使用且具有低基數的屬性。分割區過多和分割區過少之間需要取得權衡。由於分割區過多，檔案數增加會產生負荷。篩選分割區本身也有一些負荷。如果分割區太少，查詢通常需要掃描更多資料。
## 建立分割的資料表
分割資料集後，您可以在 Athena 建立分割的資料表。分割的資料表是具有分割區索引鍵的資料表。使用 `CREATE TABLE` 時，您可以將分割區新增至資料表中。使用 `CREATE TABLE AS` 時，在 Amazon S3 上建立的分割區會自動新增至資料表。
在 `CREATE TABLE` 陳述式中，您可以在 `PARTITIONED BY (column_name data_type)` 子句中指定分割區索引鍵。在 `CREATE TABLE AS` 陳述式中，您可以在 `WITH (partitioned_by = ARRAY['partition_key'])` 子句或 Iceberg 資料表的 `WITH (partitioning = ARRAY['partition_key'])` 中指定分割區索引鍵。出於效能考量，分割區索引鍵應始終是類型 `STRING`。如需詳細資訊，請參閱[使用字串做為分割區索引鍵的資料類型](data-types-timestamps.md#data-types-timestamps-partition-key-types)。
如需其他 `CREATE TABLE` 和 `CREATE TABLE AS` 語法詳細資訊，請參閱 [CREATE TABLE](create-table.md) 和 [CTAS 資料表屬性](create-table-as.md#ctas-table-properties)。
## 查詢分割的資料表
當您查詢分割區資料表時，Athena 會使用查詢中的述詞來篩選分割區的清單。然後，其會使用相符分割區的位置來處理找到的檔案。Athena 只要不讀取與查詢述詞不相符的分割區中的資料，就能有效減少掃描的資料量。
### 範例
假設您有一個依 `sales_date` 和 `product_category` 分割的資料表，並且想知道特定類別中一周的總收入。您可以在 `sales_date` 和 `product_category` 資料欄上加入述詞，以確保 Athena 只掃描最少量的資料，如下列範例所示。
```
SELECT SUM(amount) AS total_revenue
FROM sales
WHERE sales_date BETWEEN '2023-02-27' AND '2023-03-05'
AND product_category = 'Toys'
```
假設您有依日期分割的資料集，但也有精細的時間戳記。
使用 Iceberg 資料表，您可以宣告分割區索引鍵與資料欄之間的關係，但是使用 Hive 資料表時，查詢引擎對資料欄和分割區索引鍵之間的關係一無所知。因此，您必須在查詢中包含資料欄和分割區索引鍵的述詞，以確保查詢掃描的資料不會超過必要數目。
例如，假設上一個範例中的 `sales` 資料表也有 `TIMESTAMP` 資料類型的 `sold_at` 資料欄。如果您只想在特定時間範圍內獲得收入，則可以像這樣寫入查詢：
```
SELECT SUM(amount) AS total_revenue
FROM sales
WHERE sales_date = '2023-02-28'
AND sold_at BETWEEN TIMESTAMP '2023-02-28 10:00:00' AND TIMESTAMP '2023-02-28 12:00:00'
AND product_category = 'Toys'
```
如需有關查詢 Hive 和 Iceberg 資料之間的差異的詳細資訊，請參閱 [如何寫入同樣按時間分割的時間戳記欄位的查詢](data-types-timestamps.md#data-types-timestamps-how-to-write-queries-for-timestamp-fields-that-are-also-time-partitioned)。
# 什麼是歸納？
歸納是一種將資料集的記錄整理至稱為儲存貯體的類別的方法。
儲存貯體和歸納的含義與 Amazon S3 儲存貯體不同，且不應與 Amazon S3 儲存貯體混淆。在資料歸納中，具有相同屬性值的記錄會進入同一個儲存貯體。記錄會盡可能在儲存貯體之間平均分配，因此每個儲存貯體的資料量大致相同。
實際上，儲存貯體是檔案，而雜湊函數可確定記錄進入的儲存貯體。歸納的資料集在每個分割區的每個儲存貯體中會有一或多個檔案。檔案所屬的儲存貯體會以檔案名稱編碼。
## 歸納益處
當資料集依特定屬性進行歸納，而且您想要擷取該屬性具有特定值的記錄時，歸納功能非常有用。由於資料是歸納性質的，Athena 可以使用此值來判斷要查看的檔案。例如，假設資料集依 `customer_id` 進行歸納，而您想要尋找特定客戶的所有記錄。Athena 會判斷包含這些記錄的儲存貯體，而且只會讀取該儲存貯體中的檔案。
當您的資料欄具有高基數 (也就是，有許多不同的值)、平均分散，以及您經常查詢特定值的資料欄時，就會發生歸納的適當候選項。
**注意**
Athena 不支援使用 `INSERT INTO` 將新記錄新增至歸納的資料表。
## 支援依據已歸納資料欄進行篩選的資料類型
您可以在具有某些資料類型的歸納資料欄上新增篩選條件。Athena 支援對具有下列資料類型的已歸納資料欄進行篩選：
+ BOOLEAN
+ BYTE
+ DATE
+ DOUBLE
+ FLOAT
+ INT
+ LONG
+ SHORT
+ STRING
+ VARCHAR
## Hive 和 Spark 支援
Athena 引擎版本 2 支援使用 Hive 儲存貯體演算法歸納的資料集，而 Athena 引擎版本 3 也支援 Apache Spark 歸納演算法。預設為 Hive 歸納。如果您的資料集是使用 Spark 演算法歸納，請使用 `TBLPROPERTIES` 子句將 `bucketing_format` 屬性值設定為 `spark`。
**注意**
Athena 在每個 `CREATE TABLE AS SELECT` ([CTAS](ctas.md)) 查詢的分割區限制為 100 個。同樣地，您僅可以使用 [INSERT INTO](insert-into.md) 陳述式將最多 100 個分割區新增至目的地資料表。
如果您超出此限制，您可能會收到錯誤訊息 HIVE\$1TOO\$1MANY\$1OPEN\$1PARTITIONS: Exceeded limit of 100 open writers for partitions/buckets (HIVE\$1TOO\$1MANY\$1OPEN\$1PARTITIONS：超過分割區／儲存貯體 100 個開啟寫入器的限制)。若要避開此限制，您可以使用 CTAS 陳述式和一系列的 `INSERT INTO` 陳述式，每個陳述式可建立或插入最多 100 個分割區。如需詳細資訊，請參閱[使用 CTAS 和 INSERT INTO 來解決 100 個分割區限制](ctas-insert-into.md)。
## 歸納 CREATE TABLE 範例
若要為現有歸納的資料集建立資料表，請使用 `CLUSTERED BY (column)` 子句，後面接著 `INTO N BUCKETS` 子句。`INTO N BUCKETS` 子句指定了資料要歸納到的儲存貯體數量。
在下列 `CREATE TABLE` 範例中，使用 Spark 演算法，依 `customer_id` 將 `sales` 資料集歸納成 8 個儲存貯體。`CREATE TABLE` 陳述式會使用 `CLUSTERED BY` 和 `TBLPROPERTIES` 子句來設定相應的屬性。
```
CREATE EXTERNAL TABLE sales (...)
...
CLUSTERED BY (`customer_id`) INTO 8 BUCKETS
...
TBLPROPERTIES (
'bucketing_format' = 'spark'
)
```
## 歸納 CREATE TABLE AS (CTAS) 範例
若要使用 `CREATE TABLE AS` 指定歸納，請使用 `bucketed_by` 和 `bucket_count` 參數，如下列範例所示。
```
CREATE TABLE sales
WITH (
...
bucketed_by = ARRAY['customer_id'],
bucket_count = 8
)
AS SELECT ...
```
## 歸納查詢範例
下列範例查詢會尋找特定客戶在一週內購買的產品名稱。
```
SELECT DISTINCT product_name
FROM sales
WHERE sales_date BETWEEN '2023-02-27' AND '2023-03-05'
AND customer_id = 'c123'
```
如果此資料表依 `sales_date` 進行分割並依 `customer_id` 歸納，則 Athena 可以計算客戶記錄所在的儲存貯體。Athena 每個分割區最多只能讀取一個檔案。
# 其他資源
+ 有關建立歸納和分割資料表的 `CREATE TABLE AS` 範例，請參閱[範例：建立歸納和分割的資料表](https://docs.aws.amazon.com/athena/latest/ug/ctas-examples.html#ctas-example-bucketed)。
+ 如需在 AWS 資料湖實作儲存貯體的資訊，包括使用 Athena CTAS 陳述式、 AWS Glue 適用於 Apache Spark 的儲存貯體，以及適用於 Apache Iceberg 資料表的儲存貯體，請參閱 AWS 大數據部落格文章[使用 Amazon Athena 儲存貯體最佳化資料配置 AWS Glue ，並加速下游查詢](https://aws.amazon.com/blogs/big-data/optimize-data-layout-by-bucketing-with-amazon-athena-and-aws-glue-to-accelerate-downstream-queries/)。
# 分割您的資料
您可以分割資料，以限制每個查詢所掃描的資料量，從而提高效能和降低成本。您可透過任何索引鍵來分割您的資料。常見做法是根據時間來分割資料，這通常會產生多層級的分割機制。例如，每小時都有資料傳入的客戶可能決定依年、月、日、小時來分割。另一個客戶的資料來自許多不同來源，且每天只載入一次，則可能依資料來源識別符和日期來分割。
Athena 可以使用 Apache Hive 樣式的分割區，其資料路徑包含由等號連接的鍵值對 (例如 `country=us/...` 或 `year=2021/month=01/day=26/...`)。因此，路徑會包含分割區索引鍵的名稱，以及每個路徑所代表的值。若要將新的 Hive 分割區載入已分割的資料表，您可以使用 [MSCK REPAIR TABLE](msck-repair-table.md) 命令，其只適用於 Hive 樣式的分割區。
Athena 也可以使用非 Hive 樣式的分割區結構描述。例如，CloudTrail 日誌和 Firehose 交付串流對日期部分使用不同的路徑元件，例如 `data/2021/01/26/us/6fc7845e.json`。對於這類非 Hive 樣式的分割區，您可以使用 [ALTER TABLE ADD PARTITION](alter-table-add-partition.md) 手動新增分割區。
## 考量和限制
使用分割區時，請謹記以下幾點：
+ 若您查詢已分割的資料表並在 `WHERE` 子句中指定分割區，Athena 便只會掃描該分割區中的資料。
+ 如果您對 Amazon S3 儲存貯體發出具有大量物件的查詢，並且未將資料分割，這類查詢可能會影響 Amazon S3 中的 `GET` 請求率限制，並導致 Amazon S3 例外狀況。若要避免錯誤，請分割您的資料。此外，請考慮調校您的 Amazon S3 請求率。如需詳細資訊，請參閱[最佳實務設計模式：最佳化 Amazon S3 效能](https://docs.aws.amazon.com/AmazonS3/latest/userguide/request-rate-perf-considerations.html)。
+ 要搭配 Athena 使用的分割區位置必須使用 `s3` 通訊協定 (例如，`s3://amzn-s3-demo-bucket/folder/`)。在 Athena 中，當在包含的資料表上執行 `MSCK REPAIR TABLE` 查詢時，使用其他通訊協定的位置 (例如 `s3a://amzn-s3-demo-bucket/folder/`) 會導致查詢失敗。
+ 請確定 Amazon S3 路徑是小寫而不是小駝峰式命名法 (camel case) (例如，`userid` 而非 `userId`)。如果 S3 路徑是小駝峰式命名法 (camel case)，則 `MSCK REPAIR TABLE` 不會將分割區新增到 AWS Glue Data Catalog。如需詳細資訊，請參閱 [MSCK REPAIR TABLE](msck-repair-table.md)。
+ 由於 `MSCK REPAIR TABLE` 會同時掃描資料夾及其子資料夾，以尋找相符的分割區配置，請務必將個別資料表的資料留在不同的資料夾階層中。例如，假設您在 `s3://amzn-s3-demo-bucket1` 中有資料表 1 的資料，在 `s3://amzn-s3-demo-bucket1/table-2-data` 中有資料表 2 的資料。如果兩個資料表都以字串分割，`MSCK REPAIR TABLE` 會將資料表 2 的分割區新增至資料表 1 中。為避免此情況，請改用單獨的資料夾結構，如 `s3://amzn-s3-demo-bucket1` 和 `s3://amzn-s3-demo-bucket2`。請注意，此行為與 Amazon EMR 和 Apache Hive 一致。
+ 如果您將 AWS Glue Data Catalog 與 Athena 搭配使用，請參閱每個帳戶[AWS Glue 和每個資料表分割區上服務配額的端點](https://docs.aws.amazon.com/general/latest/gr/glue.html)和配額。
+ 雖然 Athena 支援查詢具有 1，000 萬個分割區的 AWS Glue 資料表，但 Athena 無法在單一掃描中讀取超過 100 萬個分割區。在這種情況下，分割區索引可能有利。如需詳細資訊，請參閱 AWS 大數據部落格文章[使用 AWS Glue Data Catalog 分割區索引改善 Amazon Athena 查詢效能](https://aws.amazon.com/blogs/big-data/improve-amazon-athena-query-performance-using-aws-glue-data-catalog-partition-indexes/)。
+ 若要在使用 時請求增加分割區配額 AWS Glue Data Catalog，請造訪 [Service Quotas 主控台 AWS Glue](https://console.aws.amazon.com/servicequotas/home?region=us-east-1#!/services/glue/quotas)。
## 建立和載入含有分割資料的資料表
若要建立使用分割區的資料表，請在 [CREATE TABLE](create-table.md) 陳述式中使用 `PARTITIONED BY` 子句。`PARTITIONED BY` 子句定義對資料進行分割區的索引鍵，如下列範例所示。`LOCATION` 子句指定已分割的資料的根位置。
```
CREATE EXTERNAL TABLE users (
first string,
last string,
username string
)
PARTITIONED BY (id string)
STORED AS parquet
LOCATION 's3://amzn-s3-demo-bucket'
```
建立資料表之後，您可以在分割區中載入要查詢的資料。對於 Hive 樣式的分割區，您可以執行 [MSCK REPAIR TABLE](msck-repair-table.md)。對於非 Hive 樣式的分割區，您可以使用 [ALTER TABLE ADD PARTITION](alter-table-add-partition.md) 手動新增分割區。
## 準備 Hive 樣式和非 Hive 樣式資料進行查詢
下列區段說明如何準備 Hive 樣式和非 Hive 樣式資料，以便在 Athena 中進行查詢。
### 案例 1：以 Hive 格式存放在 Amazon S3 上的資料
在此案例中，分割區存放在 Amazon S3 中的單獨資料夾。例如，以下是 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/ls.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/ls.html) 命令輸出的廣告曝光範例的部分清單，其中列出了指定字首下的 S3 物件：
```
aws s3 ls s3://elasticmapreduce/samples/hive-ads/tables/impressions/
PRE dt=2009-04-12-13-00/
PRE dt=2009-04-12-13-05/
PRE dt=2009-04-12-13-10/
PRE dt=2009-04-12-13-15/
PRE dt=2009-04-12-13-20/
PRE dt=2009-04-12-14-00/
PRE dt=2009-04-12-14-05/
PRE dt=2009-04-12-14-10/
PRE dt=2009-04-12-14-15/
PRE dt=2009-04-12-14-20/
PRE dt=2009-04-12-15-00/
PRE dt=2009-04-12-15-05/
```
在此，存放的日誌將欄名稱 (dt) 設為等於日期、小時和分鐘增量。當您在 DDL 中提供父資料夾的位置、結構描述和分割欄的名稱時，Athena 就能在這些子資料夾中查詢資料。
#### 建立資料表
若要使用此資料建立資料表，請沿著 'dt' 建立分割區，如下列 Athena DDL 陳述式所示：
```
CREATE EXTERNAL TABLE impressions (
requestBeginTime string,
adId string,
impressionId string,
referrer string,
userAgent string,
userCookie string,
ip string,
number string,
processId string,
browserCookie string,
requestEndTime string,
timers struct,
threadId string,
hostname string,
sessionId string)
PARTITIONED BY (dt string)
ROW FORMAT serde 'org.apache.hive.hcatalog.data.JsonSerDe'
LOCATION 's3://elasticmapreduce/samples/hive-ads/tables/impressions/' ;
```
此資料表使用 Hive 的原生 JSON 序列化程式-還原序列化程式，讀取存放在 Amazon S3 中的 JSON 資料。如需支援格式的詳細資訊，請參閱[為您的資料選擇 SerDe](supported-serdes.md)。
#### 執行 MSCK REPAIR TABLE
在您執行 `CREATE TABLE` 查詢後，在 Athena 查詢編輯器中執行 `MSCK REPAIR TABLE` 命令以載入分割區，如下列範例所示。
```
MSCK REPAIR TABLE impressions
```
執行此命令後，即可對資料進行查詢。
#### 查詢資料
使用分割區欄位查詢 impressions 資料表的資料。範例如下：
```
SELECT dt,impressionid FROM impressions WHERE dt<'2009-04-12-14-00' and dt>='2009-04-12-13-00' ORDER BY dt DESC LIMIT 100
```
此查詢應該會顯示類似下列的資料：
```
2009-04-12-13-20 ap3HcVKAWfXtgIPu6WpuUfAfL0DQEc
2009-04-12-13-20 17uchtodoS9kdeQP1x0XThKl5IuRsV
2009-04-12-13-20 JOUf1SCtRwviGw8sVcghqE5h0nkgtp
2009-04-12-13-20 NQ2XP0J0dvVbCXJ0pb4XvqJ5A4QxxH
2009-04-12-13-20 fFAItiBMsgqro9kRdIwbeX60SROaxr
2009-04-12-13-20 V4og4R9W6G3QjHHwF7gI1cSqig5D1G
2009-04-12-13-20 hPEPtBwk45msmwWTxPVVo1kVu4v11b
2009-04-12-13-20 v0SkfxegheD90gp31UCr6FplnKpx6i
2009-04-12-13-20 1iD9odVgOIi4QWkwHMcOhmwTkWDKfj
2009-04-12-13-20 b31tJiIA25CK8eDHQrHnbcknfSndUk
```
### 案例 2：資料未分割 (Hive 格式)
在下列範例中，`aws s3 ls` 命令顯示存放在 Amazon S3 中的 [ELB](elasticloadbalancer-classic-logs.md) 日誌。請注意，資料配置如何不使用 `key=value` 對，因此不屬於 Hive 格式。(`aws s3 ls` 命令的 `--recursive` 選項指定列出指定目錄或字首下的所有檔案或物件。)
```
aws s3 ls s3://athena-examples-myregion/elb/plaintext/ --recursive
2016-11-23 17:54:46 11789573 elb/plaintext/2015/01/01/part-r-00000-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:46 8776899 elb/plaintext/2015/01/01/part-r-00001-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:46 9309800 elb/plaintext/2015/01/01/part-r-00002-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:47 9412570 elb/plaintext/2015/01/01/part-r-00003-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:47 10725938 elb/plaintext/2015/01/01/part-r-00004-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:46 9439710 elb/plaintext/2015/01/01/part-r-00005-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:47 0 elb/plaintext/2015/01/01_$folder$
2016-11-23 17:54:47 9012723 elb/plaintext/2015/01/02/part-r-00006-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:47 7571816 elb/plaintext/2015/01/02/part-r-00007-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:47 9673393 elb/plaintext/2015/01/02/part-r-00008-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:48 11979218 elb/plaintext/2015/01/02/part-r-00009-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:48 9546833 elb/plaintext/2015/01/02/part-r-00010-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:48 10960865 elb/plaintext/2015/01/02/part-r-00011-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:48 0 elb/plaintext/2015/01/02_$folder$
2016-11-23 17:54:48 11360522 elb/plaintext/2015/01/03/part-r-00012-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:48 11211291 elb/plaintext/2015/01/03/part-r-00013-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:48 8633768 elb/plaintext/2015/01/03/part-r-00014-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:49 11891626 elb/plaintext/2015/01/03/part-r-00015-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:49 9173813 elb/plaintext/2015/01/03/part-r-00016-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:49 11899582 elb/plaintext/2015/01/03/part-r-00017-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:49 0 elb/plaintext/2015/01/03_$folder$
2016-11-23 17:54:50 8612843 elb/plaintext/2015/01/04/part-r-00018-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:50 10731284 elb/plaintext/2015/01/04/part-r-00019-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:50 9984735 elb/plaintext/2015/01/04/part-r-00020-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:50 9290089 elb/plaintext/2015/01/04/part-r-00021-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:50 7896339 elb/plaintext/2015/01/04/part-r-00022-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:51 8321364 elb/plaintext/2015/01/04/part-r-00023-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:51 0 elb/plaintext/2015/01/04_$folder$
2016-11-23 17:54:51 7641062 elb/plaintext/2015/01/05/part-r-00024-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:51 10253377 elb/plaintext/2015/01/05/part-r-00025-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:51 8502765 elb/plaintext/2015/01/05/part-r-00026-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:51 11518464 elb/plaintext/2015/01/05/part-r-00027-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:51 7945189 elb/plaintext/2015/01/05/part-r-00028-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:51 7864475 elb/plaintext/2015/01/05/part-r-00029-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:51 0 elb/plaintext/2015/01/05_$folder$
2016-11-23 17:54:51 11342140 elb/plaintext/2015/01/06/part-r-00030-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:51 8063755 elb/plaintext/2015/01/06/part-r-00031-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:52 9387508 elb/plaintext/2015/01/06/part-r-00032-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:52 9732343 elb/plaintext/2015/01/06/part-r-00033-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:52 11510326 elb/plaintext/2015/01/06/part-r-00034-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:52 9148117 elb/plaintext/2015/01/06/part-r-00035-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:52 0 elb/plaintext/2015/01/06_$folder$
2016-11-23 17:54:52 8402024 elb/plaintext/2015/01/07/part-r-00036-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:52 8282860 elb/plaintext/2015/01/07/part-r-00037-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:52 11575283 elb/plaintext/2015/01/07/part-r-00038-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:53 8149059 elb/plaintext/2015/01/07/part-r-00039-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:53 10037269 elb/plaintext/2015/01/07/part-r-00040-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:53 10019678 elb/plaintext/2015/01/07/part-r-00041-ce65fca5-d6c6-40e6-b1f9-190cc4f93814.txt
2016-11-23 17:54:53 0 elb/plaintext/2015/01/07_$folder$
2016-11-23 17:54:53 0 elb/plaintext/2015/01_$folder$
2016-11-23 17:54:53 0 elb/plaintext/2015_$folder$
```
#### 執行 ALTER TABLE ADD PARTITION
因為資料不是 Hive 格式，您無法在建立資料表後，使用 `MSCK REPAIR TABLE` 命令將分割區新增至該資料表。相反，您可以使用 [ALTER TABLE ADD PARTITION](alter-table-add-partition.md) 命令以手動新增每個分割區。例如，如需載入 s3://athena-examples-*myregion*/elb/plaintext/2015/01/01/ 中的資料，您可以執行下列查詢：請注意，每個 Amazon S3 資料夾不需要單獨的分割區資料欄，且分割區鍵值可與 Amazon S3 索引鍵不同。
```
ALTER TABLE elb_logs_raw_native_part ADD PARTITION (dt='2015-01-01') location 's3://athena-examples-us-west-1/elb/plaintext/2015/01/01/'
```
如果已具有分割區，您會收到 Partition already exists (分割區已存在) 錯誤。若要避免發生此錯誤，您可以使用 `IF NOT EXISTS` 子句。如需詳細資訊，請參閱[ALTER TABLE ADD PARTITION](alter-table-add-partition.md)。如需移除分割區，請使用 [ALTER TABLE DROP PARTITION](alter-table-drop-partition.md)。
## 考慮分割區投影
若要避免必須自行管理分割區，您可以使用分割區投影。分割區投影是高度已分割的資料表，其結構是提前已知的選項。在分割區投影中，分割區的值和位置是以您所設定的資料表屬性計算，而不是從中繼資料儲存庫所讀取到的來計算。因為記憶體中的計算是比遠端查詢更快，分割區投影的使用可以大幅減少查詢執行時間。
如需詳細資訊，請參閱[透過 Amazon Athena 使用分割區投影](partition-projection.md)。
## 其他資源
+ 如需有關 Firehose 資料分割選項的資訊，請參閱 [Amazon Data Firehose 範例](partition-projection-kinesis-firehose-example.md)。
+ 您可以使用 [JDBC 驅動程式](connect-with-jdbc.md)來自動新增分割區。
+ 您可以使用 CTAS 和 INSERT INTO 來分割資料集。如需詳細資訊，請參閱[使用 CTAS 和 INSERT INTO 以進行 ETL 和資料分析](ctas-insert-into-etl.md)。
# 透過 Amazon Athena 使用分割區投影
您可以使用 Athena 中的分割區投影來加速高度分割資料表的查詢處理，以及自動化分割區管理。
在分割區投影中，Athena 會使用您直接在 AWS Glue中的資料表設定的資料表屬性來計算分割區的值和位置。資料表屬性可讓 Athena「投影」或判斷必要的分割區資訊，而不必在 AWS Glue Data Catalog中執行耗時的中繼資料查詢。因為記憶體內操作通常比遠端操作更快，所以分割區投影可以減少對高度分割資料表的查詢執行期。取決於查詢和基礎資料的特定特性，分割區投影可能大幅減少受限於分割區中繼資料擷取的查詢執行期。
## 了解分割區剔除與分割區投影
分割區清除會收集中繼資料，並將它「修剪」至只限適用於查詢的分割區。這通常可加快查詢速度。Athena 會對所有具有分割區資料欄的資料表使用分割區剔除，包括為分割區投影設定的資料表。
一般而言，在處理查詢時，Athena 會`GetPartitions`先呼叫 ， AWS Glue Data Catalog 再執行分割區剔除。如果資料表有大量分割區，使用 `GetPartitions` 可能會對效能造成負面影響。若要避免這種情況，您可以使用分割區投影。分割區投影讓 Athena 可以避免呼叫 `GetPartitions`，因為分割區投影組態可提供 Athena 建置分割區本身的全部所需資訊。
## 如何使用分割區投影
若要使用分割區投影，請在 AWS Glue Data Catalog 或[外部 Hive 中繼存放](connect-to-data-source-hive.md)區中的資料表屬性中指定每個分割區欄的分割區值和投影類型範圍。資料表上的這些自訂屬性可讓 Athena 知道在資料表上執行查詢時預期的分割區模式。在查詢執行期間，Athena 會使用此資訊投影分割區值，而不是從 AWS Glue Data Catalog 或外部 Hive 中繼存放區擷取它們。這不僅可以減少查詢執行期，還可以自動化分割區管理，因為它不需要在 Athena、 AWS Glue或外部 Hive 中繼存放區中手動建立分割區。
**重要**
在資料表上啟用分割區投影會導致 Athena 忽略註冊到 AWS Glue Data Catalog 或 Hive 中繼存放區中資料表的任何分割區中繼資料。
## 一些使用案例
適合使用分割區投影的案例包括下列：
+ 針對高度分割資料表的查詢無法如您所願的那麼快完成。
+ 隨著在資料中建立新的日期或時間分割區，您定期將分割區新增至資料表。使用分割區投影，您可以設定相對日期範圍，以便在新資料到達時使用。
+ 您在 Amazon S3 中有高度分割的資料。資料在 AWS Glue Data Catalog 或 Hive 中繼存放區中建立模型並不切實際，您的查詢只會讀取其中的一小部分。
### 可投影的分割區結構
當您的分割區遵循可預測的模式 (例如，但不限於下列項目) 時，分割區投影最容易設定：
+ **整數** – 任何連續的整數序列，例如 `[1, 2, 3, 4, ..., 1000]` 或 `[0500, 0550, 0600, ..., 2500]`。
+ **日期** – 任何連續的日期或日期時間序列，例如 `[20200101, 20200102, ..., 20201231]` 或 `[1-1-2020 00:00:00, 1-1-2020 01:00:00, ..., 12-31-2020 23:00:00]`。
+ **列舉值** – 一組有限的列舉值，例如機場代碼或 AWS 區域。
+ **AWS 服務 日誌** – AWS 服務 日誌通常具有已知的結構，您可以在其中指定分割區配置 AWS Glue ，因此 Athena 可以用於分割區投影。
### 如何自訂分割區路徑範本
依預設，Athena 會使用格式 `s3://amzn-s3-demo-bucket//partition-col-1=/partition-col-2=/` 建置分割區位置，但如果您的資料以不同的方式組織，Athena 也提供自訂此路徑範本的機制。如需這些步驟，請參閱 [如何指定自訂 S3 儲存位置](partition-projection-setting-up.md#partition-projection-specifying-custom-s3-storage-locations)。
## 考量和限制
適用下列注意事項：
+ 分割區投影無須在 AWS Glue 或外部 Hive 中繼存放區手動指定分割區。
+ 當您在資料表上啟用分割區投影時，Athena 會忽略該資料表的 AWS Glue Data Catalog 或外部 Hive 中繼存放區中的任何分割區中繼資料。
+ 如果投影的分割區不存在於 Amazon S3 中，Athena 仍會投影該分割區。Athena 不會擲回錯誤，但也不會傳回任何資料。不過，如果太多分割區是空的，效能可能會比傳統 AWS Glue 分割區慢。如果超過一半的投影分割區是空的，建議您使用傳統分割區。
+ 如果數值超過分割區投影定義的範圍邊界，查詢不會傳回錯誤。查詢反而會執行，但不會傳回任何資料行。例如，如果您擁有自 2020 年起並定義為 `'projection.timestamp.range'='2020/01/01,NOW'` 的時間相關資料，如 `SELECT * FROM table-name WHERE timestamp = '2019/02/02'` 等的查詢將成功完成，但不會傳回任何資料行。
+ 分割區投影只適用於透過 Athena 查詢資料表時。如果透過其他服務 (例如 Amazon Redshift Spectrum、Athena for Spark 或 Amazon EMR) 讀取相同的資料表，則會使用標準的分割區中繼資料。
+ 由於分割區投影是僅限 DML 的功能， `SHOW PARTITIONS` 不會列出 Athena 投影但未在 AWS Glue 目錄或外部 Hive 中繼存放區中註冊的分割區。
+ Athena 未將檢視的資料表屬性作為分割區投影的組態。若要解決此限制，請在檢視參照之資料表的資料表屬性中設定並啟用分割區投影。
## 影片
以下影片展示如何使用分割區投影，改善在 Athena 中的查詢效能。
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/iUD5pPpcyZk)
**Topics**
+ [了解分割區剔除與分割區投影](#partition-projection-pruning-vs-projection)
+ [如何使用分割區投影](#partition-projection-using)
+ [一些使用案例](#partition-projection-use-cases)
+ [考量和限制](#partition-projection-considerations-and-limitations)
+ [影片](#partition-projection-video)
+ [設定分割區投影](partition-projection-setting-up.md)
+ [支援的分割區投影類型](partition-projection-supported-types.md)
+ [使用動態 ID 分割](partition-projection-dynamic-id-partitioning.md)
+ [Amazon Data Firehose 範例](partition-projection-kinesis-firehose-example.md)
# 設定分割區投影
在資料表屬性中設定分割區投影共有兩個步驟：
1. 為每個分割區資料欄指定資料範圍和相關模式，或使用自訂範本。
1. 啟用資料表的分割區投影。
**注意**
在您將分割區投影屬性新增至現有的資料表之前，您要設定分割區投影屬性的分割區資料欄必須已經存在於資料表結構描述中。如果分割區資料欄尚不存在，您必須手動將分割區資料欄新增至現有資料表。 AWS Glue 不會自動為您執行此步驟。
本節說明如何設定 的資料表屬性 AWS Glue。若要設定它們，您可以使用 AWS Glue 主控台、Athena [CREATE TABLE](create-table.md)查詢或 [AWS Glue API](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api.html)操作。下列程序說明如何在 AWS Glue 主控台中設定屬性。
**使用 AWS Glue 主控台設定和啟用分割區投影**
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/) 開啟 AWS Glue 主控台。
1. 選擇 **Tables** (資料表) 索引標籤。
在 **Tables** (資料表) 索引標籤上，您可以編輯現有資料表，或選擇 **Add tables** (新增資料表) 以建立新的資料表。如需有關手動或使用爬蟲程式新增資料表的資訊，請參閱《AWS Glue 開發人員指南》**中的 [在 AWS Glue 主控台上使用資料表。](https://docs.aws.amazon.com/glue/latest/dg/console-tables.html)
1. 在資料表清單中，選擇您要編輯之資料表的連結。
![\[在 AWS Glue 主控台中，選擇要編輯的資料表。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/partition-projection-1.png)
1. 選擇 **Actions** (動作)、**Edit table** (編輯資料表)。
1. 在 **Edit table** (編輯資料表) 頁面的 **Table properties** (資料表屬性) 區段中，針對每個分割的資料欄新增下列索引鍵/值組：
1. 對於 **Key** (索引鍵)，新增 `projection.columnName.type`。
1. 對於 **Value** (值)，新增其中一個支援的類型：`enum`、`integer`、`date` 或 `injected`。如需詳細資訊，請參閱[支援的分割區投影類型](partition-projection-supported-types.md)。
1. 遵循[支援的分割區投影類型](partition-projection-supported-types.md)中的指導，根據您的組態需求新增額外的索引鍵/值組。
下列範例資料表組態會設定分割區投影的 `year` 資料欄，限制可傳回值的範圍為 2010 年到 2016 年。
![\[在 AWS Glue 主控台資料表屬性中為分割區資料欄設定分割區投影。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/partition-projection-3.png)
1. 新增索引鍵/值組以啟用分割區投影。對於 **Key** (索引鍵)，輸入 `projection.enabled`，對於其 **Value** (值)，輸入 `true`。
**注意**
您可以透過將 `projection.enabled` 設定為 `false`，隨時停用此資料表上的分割區投影。
1. 完成時，請選擇 **Save (儲存)**。
1. 在 Athena 查詢編輯器中，測試查詢您為資料表設定的資料欄。
下列範例查詢使用 `SELECT DISTINCT` 從 `year` 資料欄傳回唯一值。資料庫包含 1987 年到 2016 年的資料，但 `projection.year.range` 屬性將傳回的值限制為 2010 年到 2016 年。
![\[查詢使用分割區投影的資料欄。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/partition-projection-5.png)
**注意**
如果您將 `projection.enabled` 設定為 `true` 但無法設定一或多個分割區資料欄，您會收到如下所示的錯誤訊息：
`HIVE_METASTORE_ERROR: Table database_name.table_name is configured for partition projection, but the following partition columns are missing projection configuration: [column_name] (table database_name.table_name)`.
## 如何指定自訂 S3 儲存位置
在 中編輯資料表屬性時 AWS Glue，您也可以為投影的分割區指定自訂 Amazon S3 路徑範本。自訂範本可讓 Athena 將分割區值正確地對應到不遵循典型 `.../column=value/...` 模式的自訂 Amazon S3 檔案位置。
使用自訂範本是選擇性的。不過，如果您使用自訂範本，則範本必須包含每個分割區資料欄的預留位置。範本位置必須以正斜線結尾，以便分割的資料檔案存在於每個分割區的「資料夾」中。
**指定自訂分割區位置範本**
1. 依照[使用 AWS Glue 主控台設定和啟用分割區投影](#partition-projection-setting-up-procedure)的步驟，新增額外的鍵/值對，指定自訂範本，如下所示：
1. 在 **Key** (索引鍵) 欄位，輸入 `storage.location.template`。
1. 對於 **Value** (值)，指定包含每個分割區資料欄之預留位置的位置。請確定每個預留位置 (及 S3 路徑本身) 是以單一正斜線結尾。
下列範例範本值假設資料表具有分割區資料欄 `a`、`b` 和 `c`。
```
s3://amzn-s3-demo-bucket/table_root/a=${a}/${b}/some_static_subdirectory/${c}/
```
```
s3://amzn-s3-demo-bucket/table_root/c=${c}/${b}/some_static_subdirectory/${a}/${b}/${c}/${c}/
```
對於相同的資料表，下列範例範本值無效，因為它不包含資料欄 `c` 的預留位置。
```
s3://amzn-s3-demo-bucket/table_root/a=${a}/${b}/some_static_subdirectory/
```
1. 選擇 **Apply** (套用)。
# 支援的分割區投影類型
資料表可以具有 `enum`、`integer`、`date,` 或 `injected` 分割區資料欄類型的任意組合。
## 列舉類型
將 `enum`類型用於值為列舉集合成員的分割區資料欄 （例如，機場代碼 或 AWS 區域)。
在資料表中定義分割區屬性，如下所示：
****
| 屬性名稱 | 範例值 | Description |
| --- | --- | --- |
| projection.columnName.type | `enum` | 必要。用於資料欄 columnName 的投影類型。該值必須是 enum (不區分大小寫) 以表示使用列舉類型。允許開頭和結尾空格。 |
| projection.columnName.values | `A,B,C,D,E,F,G,Unknown` | 必要. 用於資料欄 columnName 之以逗號分隔的列舉分割區值清單。任何空格都會被視為列舉值的一部分。 |
**注意**
建議的最佳實務是將 `enum` 型分割區投影的使用限制成幾十個或以下。雖然`enum`投影沒有特定限制，但 gzip 壓縮時，資料表中繼資料的總大小不得超過約 1 MB AWS Glue 的限制。請注意，您資料表的主要部分會共用此限制，例如資料欄名稱、位置、儲存格式等。如果您發現自己在 `enum` 投影中使用幾十個以上的唯一 ID，請考慮使用替代方法，例如歸納為代理欄位中較少數的唯一數值。您可以透過取捨基數的方式，控制 `enum` 欄位中唯一數值的數量。
## 整數類型
對於其可能值會被解譯為定義範圍內整數的分割區資料欄，請使用整數類型。投影整數資料欄目前限制為帶正負號的 Java 長整數範圍 (-263 至 263-1，含)。
****
| 屬性名稱 | 範例值 | Description |
| --- | --- | --- |
| projection.columnName.type | `integer` | 必要。用於資料欄 columnName 的投影類型。該值必須是 integer (不區分大小寫) 以表示使用整數類型。允許開頭和結尾空格。 |
| projection.columnName.range | `0,10` `-1,8675309` `0001,9999` | 必要. 以逗號分隔的雙元素清單，提供資料欄 columnName 上的查詢要傳回的最小和最大範圍值。請注意，值必須以逗號分隔，而非連字號。這些值包含在內，可以是負的，也可以以零開頭。允許開頭和結尾空格。 |
| projection.columnName.interval | `1` `5` | 選用。正整數，指定用於資料欄 columnName 之連續分割區值之間的間隔。例如，range 值 "1,3" 具有 "1" 的 interval 值，會產生 1、2 和 3 的值。range 值相同但 interval 值為 "2" 會產生 1 和 3 的值，略過 2。允許開頭和結尾空格。預設為 1。 |
| projection.columnName.digits | `1` `5` | 選用。正整數，指定用於資料欄 columnName 之分割區值最終表示法中要包含的位數。例如，range 值 "1,3" 具有 "1" 的 digits 值，會產生 1、2 和 3 的值。range 值相同但 digits 值為 "2" 會產生 01、02 和 03 的值。允許開頭和結尾空格。預設值是非靜態位數，且不以零開頭。 |
## 日期類型
對於其值會被解譯為定義範圍內之日期 (以及選用的時間) 的分割區資料欄，請使用整數類型。
**重要**
投影的日期資料欄會在查詢執行期以國際標準時間 (UTC) 產生。
****
| 屬性名稱 | 範例值 | Description |
| --- | --- | --- |
| projection.columnName.type | `date` | 必要。用於資料欄 columnName 的投影類型。該值必須是 date (不區分大小寫) 以表示使用日期類型。允許開頭和結尾空格。 |
| projection.columnName.range | `201701,201812` `01-01-2010,12-31-2018` `NOW-3YEARS,NOW` `201801,NOW+1MONTH` | 必要. 以逗號分隔的雙元素清單，提供資料欄 *columnName* 的最小和最大 `range` 值。這些數值包含在內，可以使用與 Java `java.time.*` 日期類型相容的任何格式。最小值和最大值都必須使用相同的格式。`.format` 屬性中指定的格式必須是用於這些值的格式。 此資料欄也可以包含相對日期字串，格式化為此規則運算式模式： `\s*NOW\s*(([\+\-])\s*([0-9]+)\s*(YEARS?\|MONTHS?\|WEEKS?\|DAYS?\|HOURS?\|MINUTES?\|SECONDS?)\s*)?` 允許使用空格，但在日期常值中會被視為日期字串本身的一部分。 |
| projection.columnName.format | `yyyyMM` `dd-MM-yyyy` `dd-MM-yyyy-HH-mm-ss` | 必要. 根據 Java 日期格式 [DateTimeFormatter](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html) 的日期格式字串。可以是任何支援的 Java.time.\$1 類型。 |
| projection.columnName.interval | `1` `5` | 正整數，指定用於資料欄 *columnName* 之連續分割區值之間的間隔。例如，`range` 值為 `2017-01,2018-12` 搭配 `interval` 值為 `1` 以及 `interval.unit` 值為 `MONTHS`，會產生值 2017-01、2017-02、2017-03 等。相同的 `range` 值搭配 `interval` 值為 `2` 且 `interval.unit` 值為 `MONTHS`，會產生值 2017-01、2017-03、2017-05 等。允許開頭和結尾空格。 如果提供的日期採用單日或單月精確度，則 `interval` 是選用的，並且分別預設為 1 天或 1 個月。否則，`interval` 是必要的。 |
| projection.columnName.interval.unit | `YEARS` `MONTHS` `WEEKS` `DAYS` `HOURS` `MINUTES` `SECONDS` `MILLIS` | 時間單位，代表 [ChronoUnit](https://docs.oracle.com/javase/8/docs/api/java/time/temporal/ChronoUnit.html) 的序列化格式。可能值為 `YEARS`、`MONTHS`、`WEEKS`、`DAYS`、`HOURS`、`MINUTES`、`SECONDS` 或 `MILLIS`。這些值不區分大小寫。 如果提供的日期採用單日或單月精確度，則 `interval.unit` 是選用的，並且分別預設為 1 天或 1 個月。否則，`interval.unit` 是必要的。 |
**Example – 按月份分割**
下列範例資料表組態會按月份分割 2015 年至今的資料。
```
'projection.month.type'='date',
'projection.month.format'='yyyy-MM',
'projection.month.interval'='1',
'projection.month.interval.unit'='MONTHS',
'projection.month.range'='2015-01,NOW',
...
```
## 注入類型
注入類型適用於其可能值不能在某個邏輯範圍內依程序產生，但可在查詢的 `WHERE` 子句中作為單一值提供的分割區資料欄。
請務必牢記以下幾點：
+ 如果未為每個注入的資料欄提供篩選條件表達式，則注入資料欄上的查詢會失敗。
+ 只有當值為分離值時，才能成功在注入資料欄上針對篩選條件表達式查詢多個值。
+ 僅支援 `string` 類型的資料欄。
+ 當您使用具有注入的分割區資料欄的 `WHERE IN` 子句時，您可在 `IN` 清單中指定的值的限制為 1,000 個。若要查詢的資料集包含的注入資料欄具有超過 1,000 個分割區，則請將查詢分割為多個較小的查詢，每個查詢的 `WHERE IN` 子句中最多可以包含 1,000 個值，然後彙總結果。
****
| 屬性名稱 | Value | Description |
| --- | --- | --- |
| projection.columnName.type | `injected` | 必要. 用於資料欄 columnName 的投影類型。僅支援 string 類型。指定的值必須是 injected (不區分大小寫)。允許開頭和結尾空格。 |
如需詳細資訊，請參閱[何時使用 `injected` 投影類型](partition-projection-dynamic-id-partitioning.md#partition-projection-injection)。
# 使用動態 ID 分割
當您的資料以高基數屬性分割，或者無法事先知道這些值時，您可使用 `injected` 投影類型。此類屬性的範例包括使用者名稱，以及裝置或產品的 ID。當您使用 `injected` 投影類型來設定分割區索引鍵時，Athena 會使用查詢本身的值來計算將要讀取的分割區集。
對於具有使用 `injected` 投影類型設定的分割區索引鍵的資料表，若要讓 Athena 能夠在此類資料表上執行查詢，必須符合下列條件：
+ 您的查詢必須包含至少一個分割區索引鍵值。
+ 值必須是文字或運算式，可在不讀取任何資料的情況下進行評估。
如果不滿足上述任何條件，您的查詢會失敗，並出現下列錯誤：
CONSTRAINT\$1VIOLATION：對於注入的投影分割區資料欄 *column\$1name*，WHERE 子句必須僅包含靜態等式條件，且必須至少存在一個此類條件。
## 何時使用 `injected` 投影類型
假設您有一個資料集，其中包含 IoT 裝置的事件，並根據裝置的 ID 進行分割。此資料集具有下列特性：
+ 裝置 ID 隨機產生。
+ 新裝置會經常進行佈建。
+ 目前有數十萬部裝置，未來將會有數百萬部裝置。
使用傳統的中繼儲存難以管理此資料集。在資料儲存與中繼儲存之間難以保持分割區同步，並且在查詢規劃期間篩選分割區可能較慢。但是，如果您將資料表設定為使用分割區投影，並使用 `injected` 投影類型，則有兩項優勢：您不必管理中繼儲存中的分割區，並且您的查詢也不必查詢分割區中繼資料。
下列 `CREATE TABLE` 範例會針對剛才描述的裝置事件資料集來建立資料表。該資料表使用注入的投影類型。
```
CREATE EXTERNAL TABLE device_events (
event_time TIMESTAMP,
data STRING,
battery_level INT
)
PARTITIONED BY (
device_id STRING
)
LOCATION "s3://amzn-s3-demo-bucket/prefix/"
TBLPROPERTIES (
"projection.enabled" = "true",
"projection.device_id.type" = "injected",
"storage.location.template" = "s3://amzn-s3-demo-bucket/prefix/${device_id}"
)
```
下列範例查詢會查詢 12 小時內，從三個特定裝置接收的事件數目。
```
SELECT device_id, COUNT(*) AS events
FROM device_events
WHERE device_id IN (
'4a770164-0392-4a41-8565-40ed8cec737e',
'f71d12cf-f01f-4877-875d-128c23cbde17',
'763421d8-b005-47c3-ba32-cc747ab32f9a'
)
AND event_time BETWEEN TIMESTAMP '2023-11-01 20:00' AND TIMESTAMP '2023-11-02 08:00'
GROUP BY device_id
```
當您執行此查詢時，Athena 會看到 `device_id` 分割區索引鍵的三個值，並使用這些值來計算分割區位置。Athena 會使用 `storage.location.template` 屬性的值來產生下列位置：
+ `s3://amzn-s3-demo-bucket/prefix/4a770164-0392-4a41-8565-40ed8cec737e`
+ `s3://amzn-s3-demo-bucket/prefix/f71d12cf-f01f-4877-875d-128c23cbde17`
+ `s3://amzn-s3-demo-bucket/prefix/763421d8-b005-47c3-ba32-cc747ab32f9a`
如果您從分割區投影組態中省略 `storage.location.template` 屬性，Athena 會根據 `LOCATION` 中的值 (例如 `s3://amzn-s3-demo-bucket/prefix/device_id=4a770164-0392-4a41-8565-40ed8cec737e`)，使用 HIVE 樣式的分割區來投影分割區位置。
# Amazon Data Firehose 範例
當您使用 Firehose 將資料交付到 Amazon S3 時，預設組態會使用下列範例所示的索引鍵來寫入物件：
```
s3://amzn-s3-demo-bucket/prefix/yyyy/MM/dd/HH/file.extension
```
若要建立 Athena 資料表，在查詢時間自動尋找分割區，而不必在新資料送達 AWS Glue Data Catalog 時將其新增至 ，您可以使用分割區投影。
下列 `CREATE TABLE` 範例使用的是預設的 Firehose 組態。
```
CREATE EXTERNAL TABLE my_ingested_data (
...
)
...
PARTITIONED BY (
datehour STRING
)
LOCATION "s3://amzn-s3-demo-bucket/prefix/"
TBLPROPERTIES (
"projection.enabled" = "true",
"projection.datehour.type" = "date",
"projection.datehour.format" = "yyyy/MM/dd/HH",
"projection.datehour.range" = "2021/01/01/00,NOW",
"projection.datehour.interval" = "1",
"projection.datehour.interval.unit" = "HOURS",
"storage.location.template" = "s3://amzn-s3-demo-bucket/prefix/${datehour}/"
)
```
`CREATE TABLE` 陳述式中的 `TBLPROPERTIES` 子句告訴 Athena 以下內容：
+ 查詢資料表時使用分割區投影
+ 分割區索引鍵 `datehour` 的類型為 `date` (其中包括可選時間)
+ 將日期格式化的方式
+ 日期時間的範圍。請注意，值必須以逗號分隔，而非連字號。
+ 可尋找 Amazon S3 上資料的位置。
當您查詢資料表時，Athena 會計算 `datehour` 的值，並使用儲存位置範本來產生分割區位置的清單。
**Topics**
+ [如何使用 `date` 類型](partition-projection-kinesis-firehose-example-using-the-date-type.md)
+ [如何選擇分割區索引鍵](partition-projection-kinesis-firehose-example-choosing-partition-keys.md)
+ [如何使用自訂字首和動態分割](partition-projection-kinesis-firehose-example-using-custom-prefixes-and-dynamic-partitioning.md)
# 如何使用 `date` 類型
當您將 `date` 類型用於投影分割區索引鍵時，您必須指定範圍。因為您在建立 Firehose 交付串流之前沒有日期資料，您可以使用建立日期作為開始日期。並且因為您沒有未來日期的資料，您可以使用特殊字符 `NOW` 作為結束。
在 `CREATE TABLE` 範例中，開始日期指定為世界協調時間 (UTC) 2021 年 1 月 1 日午夜。
**注意**
設定與您的資料盡可能相符的範圍，以便 Athena 僅查詢現有分割區。
在範例資料表上執行查詢時，Athena 將 `datehour` 分割區索引鍵上的條件與範圍結合使用來產生值。請考處下列查詢：
```
SELECT *
FROM my_ingested_data
WHERE datehour >= '2020/12/15/00'
AND datehour < '2021/02/03/15'
```
`SELECT` 查詢中的第一個條件會使用日期，該日期會在 `CREATE TABLE` 陳述句指定的日期範圍開始之前。由於分割區投影組態沒有為 2021 年 1 月 1 日之前的日期指定分割區，因此 Athena 僅在以下位置查詢資料，並忽略查詢中較早的日期。
```
s3://amzn-s3-demo-bucket/prefix/2021/01/01/00/
s3://amzn-s3-demo-bucket/prefix/2021/01/01/01/
s3://amzn-s3-demo-bucket/prefix/2021/01/01/02/
...
s3://amzn-s3-demo-bucket/prefix/2021/02/03/12/
s3://amzn-s3-demo-bucket/prefix/2021/02/03/13/
s3://amzn-s3-demo-bucket/prefix/2021/02/03/14/
```
同樣地，如果在 2021 年 2 月 3 日 15:00 之前的日期和時間執行查詢，則最後一個分割區會反映目前的日期和時間，而不是在查詢條件中的日期和時間。
如果要查詢最新資料，您可以利用 Athena 不產生未來日期並僅指定開頭 `datehour` 的事實，如下列範例所示。
```
SELECT *
FROM my_ingested_data
WHERE datehour >= '2021/11/09/00'
```
# 如何選擇分割區索引鍵
您可以指定分割區投影將分割區位置映射至分割區索引鍵的方式。在前一部份的 `CREATE TABLE` 範例中，日期和小時被合併成一個名為 datehour 的分割區索引鍵，但也可以使用其他結構描述。例如，您也可以針對年份、月份、日期及小時，設定個別分割區索引鍵的資料表。
但是，將日期分割為年、月和日，表示無法使用 `date` 分割區投影類型。另一種方法是將日期與小時分開，即可仍然利用 `date` 分割區投影類型，但讓指定小時範圍的查詢更易於閱讀。
請記住，以下 `CREATE TABLE` 範例將日期與小時分開。由於 `date` 是 SQL 中的保留字詞，因此此範例會用 `day` 表示日期之分割區索引鍵的名稱。
```
CREATE EXTERNAL TABLE my_ingested_data2 (
...
)
...
PARTITIONED BY (
day STRING,
hour INT
)
LOCATION "s3://amzn-s3-demo-bucket/prefix/"
TBLPROPERTIES (
"projection.enabled" = "true",
"projection.day.type" = "date",
"projection.day.format" = "yyyy/MM/dd",
"projection.day.range" = "2021/01/01,NOW",
"projection.day.interval" = "1",
"projection.day.interval.unit" = "DAYS",
"projection.hour.type" = "integer",
"projection.hour.range" = "0,23",
"projection.hour.digits" = "2",
"storage.location.template" = "s3://amzn-s3-demo-bucket/prefix/${day}/${hour}/"
)
```
在範例 `CREATE TABLE` 陳述式中，小時是個別的分割區索引鍵並設定為整數。小時分割區索引鍵的組態會指定範圍 0 到 23，而當 Athena 產生分割區位置時，小時應該格式化為兩位數。
對 `my_ingested_data2` 資料表的查詢可能如下所示：
```
SELECT *
FROM my_ingested_data2
WHERE day = '2021/11/09'
AND hour > 3
```
## 了解分割區索引鍵和分割區投影資料類型
請注意，第一個 `CREATE TABLE` 範例中的 `datehour` 索引鍵在分割區投影組態中設定為 `date`，但是分割區索引鍵的類型為 `string`。第二個範例中的 `day` 也是如此。分割區投影組態中的類型只會告訴 Athena 在產生分割區位置時如何將值格式化。您指定的類型不會變更分割區索引鍵的類型；在查詢中，`datehour` 和 `day` 為 `string` 類型。
當查詢包含類似 `day = '2021/11/09'` 的條件時，Athena 會使用分割區投影組態中指定的日期格式剖析表達式右側的字串。在 Athena 確認日期是否位於所設定範圍後，它會再次使用日期格式將日期作為字串插入儲存位置範本。
同樣，對於像 `day > '2021/11/09'` 的查詢條件，Athena 會剖析右側並產生設定範圍內所有相符日期的清單。然後，它會使用日期格式將每個日期插入儲存位置範本，以建立分割區位置的清單。
寫入與 `day > '2021-11-09'` 或 `day > DATE '2021-11-09'` 相同的條件不起作用。在第一種情況下，日期格式不相符 (請注意連字號而不是正斜線)，而在第二種情況下，資料類型不相符。
# 如何使用自訂字首和動態分割
可以使用[自訂字首](https://docs.aws.amazon.com/firehose/latest/dev/s3-prefixes.html)和[動態分割](https://docs.aws.amazon.com/firehose/latest/dev/dynamic-partitioning.html)設定 Firehose。使用這些功能，您可以設定 Amazon S3 索引鍵，並設定能對您使用案例提供更佳支援的分割區結構描述。您還可以將分割區投影與這些分割結構描述搭配使用並相應地設定它們。
例如，您可以使用自訂字首功能來取得具有 ISO 格式化日期的 Amazon S3 索引鍵，而不是預設 `yyyy/MM/dd/HH` 結構描述。
您還可以將自訂字首與動態分割結合，從 Firehose 訊息中擷取類似於 `customer_id` 的內容，如下列範例所示。
```
prefix/!{timestamp:yyyy}-!{timestamp:MM}-!{timestamp:dd}/!{partitionKeyFromQuery:customer_id}/
```
使用 Amazon S3 字首，Firehose 交付串流會將物件寫入索引鍵，例如 `s3://amzn-s3-demo-bucket/prefix/2021-11-01/customer-1234/file.extension`。對於像 `customer_id` 的屬性，其中值並未事先知道，您可以使用分割區投影類型 `injected` 並使用 `CREATE TABLE` 陳述式，如下所示：
```
CREATE EXTERNAL TABLE my_ingested_data3 (
...
)
...
PARTITIONED BY (
day STRING,
customer_id STRING
)
LOCATION "s3://amzn-s3-demo-bucket/prefix/"
TBLPROPERTIES (
"projection.enabled" = "true",
"projection.day.type" = "date",
"projection.day.format" = "yyyy-MM-dd",
"projection.day.range" = "2021-01-01,NOW",
"projection.day.interval" = "1",
"projection.day.interval.unit" = "DAYS",
"projection.customer_id.type" = "injected",
"storage.location.template" = "s3://amzn-s3-demo-bucket/prefix/${day}/${customer_id}/"
)
```
當您查詢具有類型 `injected` 的分割區索引鍵的資料表時，您的查詢必須包含該分割區索引鍵的值。對 `my_ingested_data3` 資料表的查詢可能如下所示：
```
SELECT *
FROM my_ingested_data3
WHERE day BETWEEN '2021-11-01' AND '2021-11-30'
AND customer_id = 'customer-1234'
```
## 使用 DATE 類型作為日期分割區索引鍵
因為 `day` 分割區索引鍵的值是 ISO 格式化，所以您也可以使用 `DATE` 類型而不是 `STRING` 來做為日期分割區索引鍵，如下列範例所示：
```
PARTITIONED BY (day DATE, customer_id STRING)
```
當您查詢時，此策略可讓您在分割區索引鍵上使用日期函數，而不需要剖析或轉換，如下列範例所示：
```
SELECT *
FROM my_ingested_data3
WHERE day > CURRENT_DATE - INTERVAL '7' DAY
AND customer_id = 'customer-1234'
```
**注意**
指定 `DATE` 類型的分割區索引鍵，假設您已使用[自訂字首](https://docs.aws.amazon.com/firehose/latest/dev/s3-prefixes.html)功能建立具有 ISO 格式化日期的 Amazon S3 索引鍵。如果您使用預設的 Firehose 格式 `yyyy/MM/dd/HH`，即使對應的資料表屬性為類型 `date`，您仍必須將分割區索引鍵指定為類型 `string`，如下列範例所示：
```
PARTITIONED BY (
`mydate` string)
TBLPROPERTIES (
'projection.enabled'='true',
...
'projection.mydate.type'='date',
'storage.location.template'='s3://amzn-s3-demo-bucket/prefix/${mydate}')
```
# 防止 Amazon S3 限流
限流是限制您使用服務、應用程式或系統的速率的程序。在 中 AWS，您可以使用限流來防止過度使用 Amazon S3 服務，並提高所有使用者的 Amazon S3 可用性和回應能力。但是，由於限流限制了資料傳輸到 Amazon S3 或從 Amazon S3 傳輸的速率，因此請務必考慮防止您的互動受到限流。
正如[效能調校](performance-tuning.md)章節所述，最佳化取決於您的服務層級決策、您建構資料表和資料的方式，以及您寫入查詢的方式。
**Topics**
+ [減少服務層級的限流](performance-tuning-s3-throttling-reduce-throttling-at-the-service-level.md)
+ [最佳化您的資料表](performance-tuning-s3-throttling-optimizing-your-tables.md)
+ [最佳化您的查詢](performance-tuning-s3-throttling-optimizing-queries.md)
# 減少服務層級的限流
若要避免 Amazon S3 在服務層級的限流，您可以監控您的用量並調整[服務配額](https://docs.aws.amazon.com/general/latest/gr/s3.html#limits_s3)，或者使用分割等特定技術。以下某些條件可能導致限流：
+ **超出帳戶的 API 請求限制** – Amazon S3 具有基於帳戶類型和用量的預設 API 請求限制。如果您超過單一字首每秒的請求數目上限，則您的請求可能會受到限流，以防止 Amazon S3 服務多載。
+ **資料分割不足** – 如果您沒有正確地分割資料並傳輸大量資料，Amazon S3 可能會對您的請求限流。如需有關分割的詳細資訊，請參閱本文件中的 [使用分割區](performance-tuning-s3-throttling-optimizing-your-tables.md#performance-tuning-s3-throttling-use-partitioning) 部分。
+ **大量小型物件** – 如果可能，請避免擁有大量小型檔案。Amazon S3 每個分割的字首具有每秒 [5500 個 GET 請求](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html)的限制，而您的 Athena 查詢也共用此相同限制。如果您在單一查詢中掃描數百萬個小型物件，您的查詢將很容易受到 Amazon S3 限流。
若要避免過度掃描，您可以使用 AWS Glue ETL 定期壓縮檔案，或分割資料表並新增分割區索引鍵篩選條件。如需詳細資訊，請參閱下列資源。
+ [如何設定 AWS Glue ETL 任務以輸出較大的檔案？](https://aws.amazon.com/premiumsupport/knowledge-center/glue-job-output-large-files/) (*AWS 知識中心*)
+ [讀取較大群組中的輸入檔案](https://docs.aws.amazon.com/glue/latest/dg/grouping-input-files.html) *AWS Glue （開發人員指南*)
# 最佳化您的資料表
如果遇到限流問題，建構資料很重要。雖然 Amazon S3 可以處理大量資料，但有時會因為資料的建構方式而發生限流。
下列各節就如何在 Amazon S3 中建構資料以避免限流問題提供了一些建議。
## 使用分割區
您可以限制在任何指定時間內存取的資料量，使用分割來減少限流。藉由分割特定資料欄上的資料，您可以將請求平均分散至多個物件，並減少單一物件的請求數目。減少必須掃描的資料量會改善查詢效能並降低成本。
您可以在建立資料表時，定義可做為虛擬資料欄的分割區。若要在 `CREATE TABLE` 陳述式中建立含有分割區的資料表，您可以使用 `PARTITIONED BY (column_name data_type)` 子句來定義分割資料的索引鍵。
若要限制查詢掃描的分割區，您可以在查詢的 `WHERE` 子句中將其指定為述詞。因此，經常用作篩選器的資料欄是分割的理想候選者。常見做法是根據時間間隔來分割資料，這通常會產生多層級的分割機制。
請注意，分割也有成本。當您增加資料表中的分割區數目時，擷取和處理分割區中繼資料所需的時間也會增加。因此，過度分割會消除您透過更明智分區而獲得的益處。如果您的資料明顯集中於一個分割區值，並且大多數查詢使用該值，則可能會產生額外開銷。
如需有關在 Athena 中分割的詳細資訊，請參閱 [什麼是分割？](ctas-partitioning-and-bucketing-what-is-partitioning.md)
## 歸納您的資料
分割資料的另一個方法是將資料歸納在單一分割區內。使用歸納功能時，您可以指定一或多個資料欄，其中包含要組合在一起的資料列。然後，將這些資料列放入多個儲存貯體中。如此一來，您只會查詢必須讀取的儲存貯體，從而減少必須掃描的資料列數目。
當您選取要用於歸納的資料欄時，請選取具有高基數 (亦即，具有許多不同值)、均勻分散且經常用來篩選資料的資料欄。主索引鍵 (例如 ID 資料欄) 是用來歸納的良好資料欄範例。
如需有關在 Athena 中歸納的詳細資訊，請參閱 [什麼是歸納？](ctas-partitioning-and-bucketing-what-is-bucketing.md)。
## 使用 AWS Glue 分割區索引
您可以使用 AWS Glue 分割區索引，根據一或多個分割區的值整理資料表中的資料。 AWS Glue 分割區索引可減少資料傳輸的數量、資料處理量，以及查詢的處理時間。
AWS Glue 分割區索引是中繼資料檔案，其中包含資料表中分割區的相關資訊，包括分割區索引鍵及其值。分割區索引存放在 Amazon S3 儲存貯體中，當新的分割區新增至資料表 AWS Glue 時， 會自動更新分割區索引。
當 AWS Glue 分割區索引存在時，查詢會嘗試擷取分割區的子集，而不是載入資料表中的所有分割區。查詢只會在與查詢相關的資料子集上執行。
在 中建立資料表時 AWS Glue，您可以在資料表上定義的任意分割區索引鍵組合上建立分割區索引。在資料表上建立一或多個分割區索引之後，您必須將屬性新增至啟用分割區篩選的資料表。然後，您可以從 Athena 查詢資料表。
如需有關在 中建立分割區索引的資訊 AWS Glue，請參閱《 *AWS Glue 開發人員指南*》中的[在 中使用分割區索引 AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/partition-indexes.html)。如需有關新增資料表屬性以啟用分割區篩選的資訊，請參閱 [使用 AWS Glue 分割區索引和篩選來最佳化查詢](glue-best-practices-partition-index.md)。
## 使用資料壓縮和檔案分割
如果檔案處於最佳大小，或可以將檔案分割成邏輯群組，則資料壓縮可以大幅加快查詢速度。一般而言，較高的壓縮比需要更多的 CPU 週期來壓縮和解壓縮資料。對於 Athena，建議您使用 Apache Parquet 或 Apache ORC，因為其預設會壓縮資料。如需有關 Athena 中資料壓縮的資訊，請參閱[在 Athena 中使用壓縮](compression-formats.md)。
分割檔案可讓 Athena 將讀取單一檔案的任務分散至多個讀取器，藉此提高平行處理能力。如果單一檔案不可分割，則只有一個讀取器可以讀取檔案，而其他讀取器則處於閒置狀態。Apache Parquet 和 Apache ORC 還支援可分割的檔案。
## 使用優化單欄式資料存放區
如果您將資料轉換為單欄式格式，則 Athena 查詢效能會大幅提升。當您產生單欄式檔案時，需要考量的一種優化技術是根據資料分割區索引鍵排序資料。
Apache Parquet 和 Apache ORC 是常用的開放原始碼單欄式資料存放區。如需有關將現有 Amazon S3 資料來源轉換為其中一種格式的資訊，請參閱 [轉換為單欄式格式](columnar-storage.md#convert-to-columnar)。
### 使用較大的 Parquet 區塊大小或 ORC 條紋大小
Parquet 和 ORC 具有資料儲存參數，您可以調整以進行優化。在 Parquet 中，您可以優化區塊大小。在 ORC 中，您可以優化條紋大小。區塊或條紋越大，您可以在其中儲存的資料列就越多。依預設，Parquet 區塊大小為 128 MB，而 ORC 條紋大小為 64 MB。
如果 ORC 條紋小於 8 MB (預設值為 `hive.orc.max_buffer_size`)，則 Athena 會讀取整個 ORC 條紋。對於較小的條紋，這是 Athena 在資料欄選取性和每秒輸入/輸出操作之間進行的權衡。
如果您的資料表包含大量資料欄，則較小的區塊或條紋大小可能會導致掃描的資料超過必要的數量。在這些情況下，較大的區塊大小可能會更有效率。
### 對複雜類型使用 ORC
目前，當您查詢存放在 Parquet 中且具有複雜資料類型 (例如，`array`、`map` 或 `struct`) 的資料欄時，Athena 會讀取整個資料列，而不是只選擇性地讀取指定的資料欄。這是 Athena 的已知問題。解決方法是考慮使用 ORC。
### 選擇壓縮演算法
您可以設定的另一個參數是資料區塊上的壓縮演算法。如需有關 Athena 中 Parquet 和 ORC 支援的壓縮演算法的資訊，請參閱 [Athena 壓縮支援](https://docs.aws.amazon.com/athena/latest/ug/compression-formats.html)。
如需 Athena 中單欄式儲存格式最佳化的詳細資訊，請參閱 AWS 大數據部落格文章 [Amazon Athena 的前 10 個效能調校秘訣](https://aws.amazon.com/blogs/big-data/top-10-performance-tuning-tips-for-amazon-athena/)中的「最佳化單欄式資料存放區產生」一節。
## 使用 Iceberg 資料表
Apache Iceberg 是開放式的資料表格式，專用於非常大型的分析資料集，旨在優化 Amazon S3 上的用量。您可以使用 Iceberg 資料表來協助減少 Amazon S3 中的限流。
Iceberg 資料表可為您提供下列優點：
+ 您可以在一或多個資料欄上對 Iceberg 資料表進行分割。這樣可優化資料存取，並減少查詢必須掃描的資料量。
+ 由於 Iceberg 物件儲存模式可將 Iceberg 資料表優化以與 Amazon S3 搭配使用，因此其可以處理大量資料和繁重的查詢工作負載。
+ 物件儲存模式中的 Iceberg 資料表具備可擴展性、容錯能力和耐用性，有助於減少限流。
+ ACID 交易支援意味著，多個使用者可以以原子方式新增和刪除 Amazon S3 物件。
如需有關 Apache Iceberg 的詳細資訊，請參閱 [Apache Iceberg](https://iceberg.apache.org/)。如需有關在 Athena 中使用 Apache Iceberg 資料表的詳細資訊，請參閱[使用 Iceberg 資料表](https://docs.aws.amazon.com/athena/latest/ug/querying-iceberg.html)。
# 最佳化您的查詢
使用本節中的建議優化 Athena 中的 SQL 查詢。
## 使用 LIMIT 與 ORDER BY 子句
`ORDER BY` 子句會以排序順序傳回資料。這需要 Athena 將所有資料列傳送至單一工作節點，然後排序資料列。這種查詢類型可以執行很長一段時間，甚至失敗。
為了提高查詢的效率，請查看頂部或底部的 *N* 個值，然後使用 `LIMIT` 子句。這樣可以將排序和限制推送至個別工作節點，而不是單一工作節點，進而大幅降低排序的成本。
## 優化 JOIN 子句
當您聯結兩個資料表時，Athena 會將右側的資料表分散至工作節點，然後串流左側的資料表以執行聯結。
因此，請在聯結左側指定較大的資料表，並在聯結的右側指定較小的資料表。如此一來，Athena 會使用較少的記憶體，並以較低的延遲執行查詢。
另外，請注意以下重點：
+ 當您使用多個 `JOIN` 命令時，請按從最大到最小的順序指定資料表。
+ 除非查詢需要交叉聯結，否則請予以避免。
## 優化 GROUP BY 子句
`GROUP BY` 運算子會根據 `GROUP BY` 資料欄將資料列分散至工作節點。我們會在記憶體中引用這些資料欄，並在擷取資料列時比較這些值。當 `GROUP BY` 資料欄相符時，這些值彙總在一起。考慮到此程序的運作方式，建議按從最高基數到最低基數的順序排序資料欄。
## 使用數字而不是字串
由於相較於字串，數字需要的記憶體較少，而且處理速度更快，因此請盡可能使用數字而不是字串。
## 限制資料欄的數目
若要減少儲存資料所需的記憶體總量，請限制 `SELECT` 陳述式中指定的資料欄數。
## 使用規則表達式而不是 LIKE
包含子句 (例如大型字串上的 `LIKE '%string%'`) 的查詢可能需要非常大量的運算。當您篩選字串資料欄上的多個值時，請改用 [regexp\$1like()](https://trino.io/docs/current/functions/regexp.html#regexp_like) 函數和規則表達式。當您比較一長串值時，這特別有用。
## 使用 LIMIT 子句
當您執行查詢時，請不要選取所有資料欄，而是使用 `LIMIT` 子句，以只傳回您需要的資料欄。這樣做可減少透過查詢執行管道處理的資料集大小。當您查詢具有大量字串型資料欄的資料表時，`LIMIT` 子句會更有幫助。當您對任何查詢執行多個聯結或彙總時，`LIMIT` 子句也很有用。
# 其他資源
如需 Athena 效能調校的其他相關資訊，請參閱下列資源：
+ AWS 大數據部落格文章：[Amazon Athena 的前 10 大效能調校秘訣](https://aws.amazon.com/blogs/big-data/top-10-performance-tuning-tips-for-amazon-athena/)。
+ AWS 大數據部落格文章：*AWS 大數據部落格*中[的最新 Amazon Athena 引擎，以 3 倍的速度執行查詢，節省高達 70% 的成本](https://aws.amazon.com/blogs/big-data/run-queries-3x-faster-with-up-to-70-cost-savings-on-the-latest-amazon-athena-engine/)。
+ AWS 大數據部落格文章：[在 Amazon Athena 中使用述詞下推來改善聯合查詢](https://aws.amazon.com/blogs/big-data/improve-federated-queries-with-predicate-pushdown-in-amazon-athena/)。
+ 《Amazon Simple Storage Service 使用者指南》：[最佳實務設計模式：最佳化 Amazon S3 效能](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html)。
+ AWS 巨量資料部落格中的其他 [Athena 文章](https://aws.amazon.com/blogs/big-data/tag/amazon-athena/)。
+ 使用 **Amazon Athena** 標籤在 [AWS re:Post](https://repost.aws/tags/TA78iVOM7gR62_QqDe2-CmiA/amazon-athena) 上詢問問題。
+ 請參閱[AWS 知識中心的 Athena 主題](https://aws.amazon.com/premiumsupport/knowledge-center/#Amazon_Athena)。
+ Contact AWS 支援 （在 中 AWS 管理主控台，按一下 **Support**、**Support Center**)
# 在 Athena 中使用壓縮
Athena 支援各種壓縮格式來讀取和寫入資料，包括從使用多種壓縮格式的資料表讀取。例如，當某些 Parquet 檔案使用 Snappy 壓縮而其他 Parquet 檔案使用 GZIP 壓縮時，Athena 可以成功讀取使用 Parquet 檔案格式的資料表中的資料。相同的原則適用於 ORC、文字檔案和 JSON 儲存格式。
## 支援的壓縮格式
Athena 支援以下壓縮格式：
+ **BZIP2** – 使用 Burrows-Wheeler 演算法的格式。
+ **DEFLATE** – 基於 [LZSS](https://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Storer%E2%80%93Szymanski) 和 [Huffman 編碼](https://en.wikipedia.org/wiki/Huffman_coding)的壓縮演算法。[Deflate](https://en.wikipedia.org/wiki/Deflate) 僅適用於 Avro 檔案格式。
+ **GZIP** – 以 Deflate 為基礎的壓縮演算法。對於 Athena 引擎版本 2 和 3 中的 Hive 資料表，以及 Athena 引擎版本 2 中的 Iceberg 資料表，GZIP 是採用 Parquet 格式和文字檔案存儲格式之檔案的預設寫入壓縮格式。不支援 `tar.gz` 格式的檔案。
+ **LZ4** – Lempel-Ziv 77 (LZ7) 系列的這個成員也著重於壓縮和解壓縮速度，而不是資料的最大壓縮。LZ4 具有以下框架格式：
+ **LZ4 原始/無框架** – LZ4 區塊壓縮格式的無框架標準實作。如需詳細資訊，請參閱 GitHub 上的 [LZ4 區塊格式說明](https://github.com/lz4/lz4/blob/dev/doc/lz4_Block_format.md)。
+ **LZ4 框架** – LZ4 的一般框架實作。如需詳細資訊，請參閱 GitHub 上的 [LZ4 框架格式說明](https://github.com/lz4/lz4/blob/dev/doc/lz4_Frame_format.md)。
+ **LZ4 Hadoop 相容** – LZ4 的 Apache Haddop 實作。這個實作使用 [BlockCompressorStream.java](https://github.com/apache/hadoop/blob/f67237cbe7bc48a1b9088e990800b37529f1db2a/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/compress/BlockCompressorStream.java) 類別包裝 LZ4 壓縮。
+ **LZO** – 使用 Lempel–Ziv–Oberhumer 演算法的格式，該演算法著重於高壓縮和解壓縮速度，而不是資料的最大壓縮。LZO 有兩種實作：
+ **標準 LZO** – 如需詳細資訊，請參閱 Oberhumer 網站上的 LZO [摘要](http://www.oberhumer.com/opensource/lzo/#abstract)。
+ **LZO Hadoop 相容** – 這個實作使用 [BlockCompressorStream.java](https://github.com/apache/hadoop/blob/f67237cbe7bc48a1b9088e990800b37529f1db2a/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/compress/BlockCompressorStream.java) 類別包裝 LZO 演算法。
+ **SNAPPY** – 屬於 Lempel-Ziv 77 (LZ7) 系列的壓縮演算法。Snappy 著重於高壓縮和解壓縮速度，而不是資料的最大壓縮。
+ **ZLIB** – 根據 Deflate，ZLIB 是 ORC 資料儲存格式中檔案的預設寫入壓縮格式。如需詳細資訊，請參閱 GitHub 上的 [zlib](https://github.com/madler/zlib) 頁面。
+ **ZSTD** – [Zstandard 即時資料壓縮演算法](http://facebook.github.io/zstd/)是一種提供高壓縮比的快速壓縮演算法。Zstandard (ZSTD) 程式庫是使用 BSD 授權作為開放原始碼所提供。ZSTD 是 Iceberg 資料表的預設壓縮。寫入 ZSTD 壓縮資料時，Athena 預設使用 ZSTD 壓縮級別 3。如需有關在 Athena 中使用 ZSTD 壓縮級別的詳細資訊，請參閱 [使用 ZSTD 壓縮級別](compression-support-zstd-levels.md)。
**注意**
Athena 不支援寫入以 LZ4 或 LZO 格式壓縮的 Parquet 檔案。支援讀取這些壓縮格式。
## 指定壓縮格式
當您寫入 CREATE TABLE 或 CTAS 陳述式時，您可以指定壓縮屬性，以指定 Athena 寫入這些資料表時要使用的壓縮類型。
+ 如需 CTAS 的資訊，請參閱 [CTAS 資料表屬性](create-table-as.md#ctas-table-properties)。如需範例，請參閱 [CTAS 查詢的範例](ctas-examples.md)。
+ 如需 CREATE TABLE 的資訊，請參閱 [ALTER TABLE SET TBLPROPERTIES](alter-table-set-tblproperties.md) 以取得壓縮資料表屬性的清單。
## 指定未壓縮
CREATE TABLE 陳述式支援寫入未壓縮的檔案。若要編寫未壓縮檔案，請使用下列語法：
+ CREATE TABLE (文字檔案或 JSON) – 在 `TBLPROPERTIES` 中，指定 `write.compression = NONE`。
+ CREATE TABLE (Parquet) – 在 `TBLPROPERTIES` 中，指定 `parquet.compression = UNCOMPRESSED`。
+ CREATE TABLE (ORC) – 在 `TBLPROPERTIES` 中，指定 `orc.compress = NONE`。
## 備註和資源
+ 目前 Athena 無法識別大寫的副檔名，諸如 `.GZ` 或 `.BZIP2`。避免使用大寫副檔名的資料集，或將資料副檔名重新以小寫字母命名。
+ 若為 CSV、TSV 和 JSON 的資料，Athena 會根據副檔名決定壓縮類型。如果不存在任何副檔名，Athena 會將資料視為未壓縮的純文字。如果您的資料已壓縮，請確定檔案名稱包含副檔名，例如 `gz`。
+ 不支援 ZIP 檔案格式。
+ 如需從 Athena 查詢 Amazon Data Firehose 日誌，支援的格式包括 GZIP 壓縮或具有 SNAPPY 壓縮的 ORC 檔案。
+ 如需使用壓縮的詳細資訊，請參閱 Amazon Athena AWS 大數據部落格文章前 10 大效能調校秘訣的第 3 節 (「壓縮和分割檔案」)。 [ Amazon Athena](https://aws.amazon.com/blogs/big-data/top-10-performance-tuning-tips-for-amazon-athena/)
**Topics**
+ [指定壓縮格式](#compression-support-specifying-compression-formats)
+ [指定未壓縮](#compression-support-specifying-no-compression)
+ [備註和資源](#compression-support-notes-and-resources)
+ [Hive 資料表壓縮](compression-support-hive.md)
+ [Iceberg 資料表壓縮](compression-support-iceberg.md)
+ [ZSTD 壓縮級別](compression-support-zstd-levels.md)
# 使用 Hive 資料表壓縮
Athena 中 Hive 資料表的壓縮選項會隨引擎版本和檔案格式而異。
## Athena 引擎版本 3 中的 Hive 壓縮支援
下列資料表摘要說明 Athena 引擎版本 3 對 Apache Hive 中的儲存檔案格式的壓縮格式支援。文字檔案格式包括 TSV、CSV、JSON 和文字的自訂 SerDes。儲存格中的「是」或「否」同樣適用於讀取和寫入操作，除非另有註明。基於本資料表的用途，CREATE TABLE、CTAS 和 INSERT INTO 會被視為寫入操作。如需有關在 Athena 中使用 ZSTD 壓縮級別的詳細資訊，請參閱 [使用 ZSTD 壓縮級別](compression-support-zstd-levels.md)。
****
| | Avro | Ion | ORC | Parquet | 文字檔案 |
| --- | --- | --- | --- | --- | --- |
| BZIP2 | 是 | 是 | 否 | 否 | 是 |
| DEFLATE | 是 | 否 | 否 | 否 | 否 |
| GZIP | 否 | 是 | 否 | 是 | 是 |
| LZ4 | 否 | 是 | 是 | 寫入 - 否 讀取 - 是 | 是 |
| LZO | 否 | 寫入 - 否 讀取 - 是 | 否 | 寫入 - 否 讀取 - 是 | 寫入 - 否 讀取 - 是 |
| SNAPPY | 是 | 是 | 是 | 是 | 是 |
| ZLIB | 否 | 否 | 是 | 否 | 否 |
| ZSTD | 是 | 是 | 是 | 是 | 是 |
| NONE | 是 | 是 | 是 | 是 | 是 |
# 使用 Iceberg 資料表壓縮
Athena 中 Iceberg 資料表的壓縮選項會隨引擎版本和檔案格式而異。
## Athena 引擎版本 3 中的 Iceberg 壓縮支援
下列資料表摘要說明 Athena 引擎版本 3 對 Apache Iceberg 中的儲存檔案格式的壓縮格式支援。儲存格中的「是」或「否」同樣適用於讀取和寫入操作，除非另有註明。基於本資料表的用途，CREATE TABLE、CTAS 和 INSERT INTO 會被視為寫入操作。Athena 引擎版本 3 中的 Iceberg 的預設儲存格式是 Parquet。Athena 引擎版本 3 中的 Iceberg 的預設壓縮格式是 ZSTD。如需有關在 Athena 中使用 ZSTD 壓縮級別的詳細資訊，請參閱 [使用 ZSTD 壓縮級別](compression-support-zstd-levels.md)。
****
| | Avro | ORC | Parquet (預設) |
| --- | --- | --- | --- |
| BZIP2 | 否 | 否 | 否 |
| GZIP | 是 | 否 | 是 |
| LZ4 | 否 | 是 | 否 |
| SNAPPY | 是 | 是 | 是 |
| ZLIB | 否 | 是 | 否 |
| ZSTD | 是 | 是 | 是 (預設) |
| NONE | 是 (指定 None 或 Deflate) | 是 | 是 (指定 None 或 Uncompressed) |
# 使用 ZSTD 壓縮級別
[Zstandard 即時資料壓縮演算法](http://facebook.github.io/zstd/)是一種提供高壓縮比的快速壓縮演算法。Zstandard (ZSTD) 程式庫是開放原始碼軟體，使用 BSD 授權。Athena 支援讀取和寫入 ZStandard 壓縮的 ORC、Parquet 和文字檔案資料。
您可以使用 ZSTD 壓縮級別根據自己的要求調整壓縮比和速度。ZSTD 庫支援從 1 到 22 的壓縮級別。Athena 預設使用 ZSTD 壓縮級別 3。
壓縮級別在壓縮速度和達到的壓縮量之間提供了細微的權衡。壓縮級別越低，速度越快，但檔案大小更大。例如，如果速度最重要，則可以使用級別 1，如果大小最重要，則可以使用級別 22。級別 3 適用於許多使用案例，且為預設值。請謹慎使用大於 19 的級別，因為這些級別需要更多的記憶體。ZSTD 庫還提供負壓縮級別，其可擴展壓縮速度和比率的範圍。如需詳細資訊，請參閱 [Zstandard 壓縮 RFC](https://datatracker.ietf.org/doc/html/rfc8478)。
豐富的壓縮級別為微調提供了大量機會。但是，請確保在決定壓縮級別時測量資料並考慮權衡。建議使用預設級別 3，或 6 到 9 之間的級別，以便在壓縮速度與壓縮資料大小之間取得合理的權衡。對於大小最重要且壓縮速度不是問題的情況，預留級別 20 或更高。
## 考量和限制
在 Athena 中使用 ZSTD 壓縮級別時，請考慮下列幾點。
+ 只有 Athena 引擎版本 3 中才支援 ZSTD `compression_level` 屬性。
+ `ALTER TABLE`、`CREATE TABLE`、`CREATE TABLE AS` (CTAS) 以及 `UNLOAD` 陳述式支援 ZSTD `compression_level` 屬性。
+ `compression_level` 屬性是選用屬性。
+ 只有 ZSTD 壓縮才支援 `compression_level` 屬性。
+ 可能的壓縮級別為 1 到 22。
+ 預設壓縮級別為 3。
如需有關 Athena 中 Apache Hive ZSTD 壓縮支援的資訊，請參閱 [使用 Hive 資料表壓縮](compression-support-hive.md)。如需有關 Athena 中 Apache Iceberg ZSTD 壓縮支援的資訊，請參閱 [使用 Iceberg 資料表壓縮](compression-support-iceberg.md)。
## 指定 ZSTD 壓縮級別
若要指定 `ALTER TABLE`、`CREATE TABLE`、`CREATE TABLE AS` 和 `UNLOAD` 陳述式的 ZSTD 壓縮級別，請使用 `compression_level` 屬性。若要指定 ZSTD 壓縮本身，您必須使用陳述式語法所使用的單獨壓縮屬性。
### ALTER TABLE SET TBLPROPERTIES
在 [ALTER TABLE SET TBLPROPERTIES](alter-table-set-tblproperties.md) 陳述式 `SET TBLPROPERTIES` 子句中，使用 `'write.compression' = ' ZSTD'` 或 `'parquet.compression' = 'ZSTD'` 指定 ZSTD 壓縮。然後使用 `compression_level` 屬性來指定 1 到 22 之間的值 (例如，'`compression_level' = '5'`)。如果您沒有指定壓縮級別屬性，則壓縮級別會預設為 3。
#### 範例
下列範例會修改資料表 `existing_table`，以使用具有 ZSTD 壓縮和 ZSTD 壓縮級別 4 的 Parquet 檔案格式。請注意，在 `TBLPROPERTIES` 子句中，壓縮級別值必須輸入為字串而不是整數，因此必須用單引號或雙引號括住。
```
ALTER TABLE existing_table
SET TBLPROPERTIES ('parquet.compression' = 'ZSTD', 'compression_level' = '4')
```
### CREATE TABLE
在 [CREATE TABLE](create-table.md) 陳述式 `TBLPROPERTIES` 子句中，指定 '`write.compression' = 'ZSTD'` 或 `'parquet.compression' = 'ZSTD'`，然後使用 `compression_level = compression_level` 並指定介於 1 到 22 之間的字串值。如果未指定 `compression_level` 屬性，則預設壓縮級別為 3。
#### 範例
下列範例使用 ZSTD 壓縮和 ZSTD 壓縮級別 4 建立 Parquet 檔案格式的資料表。
```
CREATE EXTERNAL TABLE new_table (
`col0` string COMMENT '',
`col1` string COMMENT ''
)
STORED AS PARQUET
LOCATION 's3://amzn-s3-demo-bucket/'
TBLPROPERTIES ('write.compression' = 'ZSTD', 'compression_level' = '4')
```
### CREATE TABLE AS (CTAS)
在 [CREATE TABLE AS](create-table-as.md) 陳述式 `WITH` 子句中，指定 `write_compression = 'ZSTD'` 或 `parquet_compression = 'ZSTD'`，然後使用 `compression_level = compression_level` 並指定介於 1 到 22 之間的整數值。如果未指定 `compression_level` 屬性，則預設壓縮級別為 3。
#### 範例
下列 CTAS 範例使用 ZSTD 壓縮和 ZSTD 壓縮級別 4，將 Parquet 指定為檔案格式。請注意，在 `WITH` 子句中，壓縮級別值必須指定為整數而不是字串。
```
CREATE TABLE new_table
WITH ( format = 'PARQUET', write_compression = 'ZSTD', compression_level = 4)
AS SELECT * FROM old_table
```
### UNLOAD
在 [UNLOAD](unload.md) 陳述式 `WITH` 子句中，指定 `compression = 'ZSTD'`，然後使用 `compression_level = compression_level` 並指定介於 1 到 22 之間的整數值。如果未指定 `compression_level` 屬性，則預設壓縮級別為 3。
#### 範例
下列範例會使用 Parquet 檔案格式、ZSTD 壓縮和 ZSTD 壓縮級別 4，將查詢結果卸載到指定的位置。
```
UNLOAD (SELECT * FROM old_table)
TO 's3://amzn-s3-demo-bucket/'
WITH (format = 'PARQUET', compression = 'ZSTD', compression_level = 4)
```
# 標記 Athena 資源
每個標記皆包含由您定義的金鑰和值。標記 Athena 資源時，您可以將自訂中繼資料指派給該資源。您可以使用標籤以不同方式分類 AWS 資源，例如依用途、擁有者或環境。在 Athena 中，工作群組、資料目錄和容量保留等資源都是可標記的資源。例如，您可以為帳戶中的工作群組建立一組標籤，以協助您追蹤工作群組擁有者，或依用途來識別工作群組。如果您也在 Billing and Cost Management 主控台中啟用標籤作為成本分配標籤，則與執行查詢相關聯的成本會顯示在「成本和用量報告」中，並含有該成本分配標籤。我們建議您使用 AWS [ 標記最佳實務](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/tagging-best-practices.html)來建立一組一致的標籤，以滿足您組織的需求。
您可以使用 Athena 主控台或 API 操作來處理標籤。
**Topics**
+ [標籤基本概念](#tag-basics)
+ [標籤限制](#tag-restrictions)
+ [使用工作群組的標籤](tags-console.md)
+ [使用 API 和 AWS CLI 標籤操作](tags-operations.md)
+ [使用標籤型 IAM 存取控制政策](tags-access-control.md)
## 標籤基本概念
標籤是您指派給 Athena 資源的標籤。每個標籤皆包含由您定義的一個金鑰與一個選用值。
標籤可讓您以不同的方式分類 AWS 資源。例如，您可以為您帳戶的工作群組定義一組標籤，以協助您追蹤每個工作群組擁有者或用途。
您可以在建立新的 Athena 工作群組或資料目錄時新增標籤，或從中新增、編輯或移除標籤。您可以在主控台編輯標籤。如果您使用 API 操作來編輯標籤，請移除舊標籤，再加入新標籤。如果您刪除資源，也會刪除任何該資源所使用的標籤。
Athena 不會自動為您的資源指派標籤。您可以編輯標籤索引鍵和值，也可以隨時從資源中移除標籤。您可以將標籤的值設為空白字串，但您無法將標籤的值設為 Null。請勿將重複的標籤鍵新增至相同的資源。如果這樣做，Athena 會發出錯誤訊息。如果您使用 **TagResource** 動作來標記使用現有標籤鍵的資源，則新標籤值會覆寫舊值。
在 IAM 中，您可以控制 Amazon Web Services 帳戶中的哪些使用者具有建立、編輯、移除或列出標籤的許可。如需詳細資訊，請參閱[使用標籤型 IAM 存取控制政策](tags-access-control.md)。
如需 Amazon Athena 標籤動作的完整清單，請參閱 [Amazon Athena API 參考](https://docs.aws.amazon.com/athena/latest/APIReference/)中的 API 動作名稱。
您可以使用標籤來計費。如需詳細資訊，請參閱《AWS 帳單與成本管理 使用者指南》**中的[使用標籤計費](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/custom-tags.html)。
如需詳細資訊，請參閱[標籤限制](#tag-restrictions)。
## 標籤限制
標籤有以下限制：
+ 在 Athena 中，您可以標記工作群組、資料目錄和容量保留。您無法標記查詢。
+ 每一資源標籤數最多為 50。若要保持在限制內，請檢閱和刪除未使用的標籤。
+ 針對每一個資源，每個標籤鍵必須是唯一的，且每個標籤鍵只能有一個值。請勿將重複的標籤鍵同時新增到相同的工作群組。如果這樣做，Athena 會發出錯誤訊息。如果您在個別的 `TagResource` 動作中使用現有的標籤鍵來標記資源，新標籤值會覆寫舊值。
+ 標籤索引鍵長度為 1-128 個 UTF-8 Unicode 字元。
+ 標籤值長度為 0-256 個 UTF-8 Unicode 字元。
您需要指定工作群組資源的 ARN，才能執行標記操作，例如新增、編輯、移除或列出標籤。
+ Athena 可讓您使用字母、數字、以 UTF-8 表示的空格，以及下列字元：\$1 – = . \$1 : / @。
+ 標籤鍵與值皆區分大小寫。
+ 標籤索引鍵中的`"aws:"`字首保留供 AWS 使用。您無法編輯或刪除含有此字首的標籤索引鍵。含有此字首的標籤不算在每一資源的標籤限制內。
+ 您指派的標籤僅供 Amazon Web Services 帳戶使用。
# 使用工作群組的標籤
您可以使用 Athena 主控台，查看您帳戶中每個工作群組正在使用的標籤。您只能依工作群組來檢視標籤。Athena 主控台也可讓您一次在一個工作群組中套用、編輯或移除標籤。
您可以使用您建立的標籤來搜尋工作群組。
**Topics**
+ [顯示個別工作群組的標籤](#tags-display)
+ [在個別工作群組上新增和刪除標籤](#tags-add-delete)
## 顯示個別工作群組的標籤
**在 Athena 主控台中顯示個別工作群組的標籤**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 如果未顯示主控台的導覽窗格，請選擇左側的展開選單。
![\[選擇展開選單。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/nav-pane-expansion.png)
1. 在導覽選單上，選擇 **Workgroups** (工作群組)，然後選擇您要的工作群組。
1. 執行以下任意一項：
+ 選擇 **Tags** (標籤) 索引標籤。如果標籤清單很長，請使用搜尋方塊。
+ 選擇 **Edit** (編輯)，然後向下捲動到 **Tags** (標籤) 區段。
## 在個別工作群組上新增和刪除標籤
您可以直接從 **Workgroups** (工作群組) 索引標籤來管理個別工作群組的標籤。
**注意**
如果您希望使用者在主控台中建立工作群組時新增標籤，或在使用 **CreateWorkGroup** 動作時傳入標籤，請確定您授予使用者進行 **TagResource** 和 **CreateWorkGroup** 動作的 IAM 許可。
**在建立新的工作群組時新增標籤**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 在導覽選單中，選擇 **Workgroups** (工作群組)。
1. 選擇 **Create workgroup** (建立工作群組)，並視需要填寫值。如需詳細步驟，請參閱[建立工作群組](creating-workgroups.md)。
1. 在 **Tags** (標籤) 區段中，指定索引鍵和值來新增一或多個標籤。請勿將重複的標籤索引鍵同時新增到相同的工作群組。如果這樣做，Athena 會發出錯誤訊息。如需詳細資訊，請參閱[標籤限制](tags.md#tag-restrictions)。
1. 完成時，選擇 **Create Workgroup** (建立工作群組)。
**在現有的工作群組中新增或編輯標籤**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 在導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 選擇您想要修改的工作群組。
1. 執行以下任意一項：
+ 選擇 **Tags** (標籤) 索引標籤，然後選擇 **Manage tags** (管理標籤)。
+ 選擇 **Edit** (編輯)，然後向下捲動到 **Tags** (標籤) 區段。
1. 指定每個標籤的索引鍵和數值。如需詳細資訊，請參閱[標籤限制](tags.md#tag-restrictions)。
1. 選擇 **Save** (儲存)。
**從個別工作群組中刪除標籤**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 在導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 選擇您想要修改的工作群組。
1. 執行以下任意一項：
+ 選擇 **Tags** (標籤) 索引標籤，然後選擇 **Manage tags** (管理標籤)。
+ 選擇 **Edit** (編輯)，然後向下捲動到 **Tags** (標籤) 區段。
1. 在標籤清單中，選取您要刪除標籤的 **Remove** (移除)，然後選擇 **Save** (儲存)。
# 使用 API 和 AWS CLI 標籤操作
使用下列標籤操作來新增、移除或列出資源上的標籤。
****
| API | CLI | 動作描述 |
| --- | --- | --- |
| TagResource | tag-resource | 在具有指定 ARN 的資源上新增或覆寫一或多個標籤。 |
| UntagResource | untag-resource | 從具有指定 ARN 的資源中刪除一個或多個標籤。 |
| ListTagsForResource | list‑tags‑for‑resource | 列出具有指定 ARN 之資源的一個或多個標籤。 |
**在建立資源時新增標籤**
若要在建立工作群組或資料目錄時新增標籤，請使用 `tags` 參數搭配 `CreateWorkGroup`或 `CreateDataCatalog` API 操作，或搭配 AWS CLI `create-work-group`或 `create-data-catalog`命令。
## 使用 API 動作管理標籤
下列範例說明如何使用標籤 API 操作來管理工作群組和資料目錄上的標籤。這些範例使用 Java 程式語言。
### 範例 – TagResource
下列範例將兩個標籤新增至工作群組 `workgroupA`：
```
List tags = new ArrayList<>();
tags.add(new Tag().withKey("tagKey1").withValue("tagValue1"));
tags.add(new Tag().withKey("tagKey2").withValue("tagValue2"));
TagResourceRequest request = new TagResourceRequest()
.withResourceARN("arn:aws:athena:us-east-1:123456789012:workgroup/workgroupA")
.withTags(tags);
client.tagResource(request);
```
下列範例將兩個標籤新增至資料目錄 `datacatalogA`：
```
List tags = new ArrayList<>();
tags.add(new Tag().withKey("tagKey1").withValue("tagValue1"));
tags.add(new Tag().withKey("tagKey2").withValue("tagValue2"));
TagResourceRequest request = new TagResourceRequest()
.withResourceARN("arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA")
.withTags(tags);
client.tagResource(request);
```
**注意**
請勿將重複的標籤鍵新增至相同的資源。如果這樣做，Athena 會發出錯誤訊息。如果您在個別的 `TagResource` 動作中使用現有的標籤鍵來標記資源，新標籤值會覆寫舊值。
### 範例 – UntagResource
下列範例將 `tagKey2` 從工作群組 `workgroupA` 中移除：
```
List tagKeys = new ArrayList<>();
tagKeys.add("tagKey2");
UntagResourceRequest request = new UntagResourceRequest()
.withResourceARN("arn:aws:athena:us-east-1:123456789012:workgroup/workgroupA")
.withTagKeys(tagKeys);
client.untagResource(request);
```
下列範例將 `tagKey2` 從資料目錄 `datacatalogA` 中移除：
```
List tagKeys = new ArrayList<>();
tagKeys.add("tagKey2");
UntagResourceRequest request = new UntagResourceRequest()
.withResourceARN("arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA")
.withTagKeys(tagKeys);
client.untagResource(request);
```
### 範例 – ListTagsForResource
下列範例列出工作群組 `workgroupA` 的標籤：
```
ListTagsForResourceRequest request = new ListTagsForResourceRequest()
.withResourceARN("arn:aws:athena:us-east-1:123456789012:workgroup/workgroupA");
ListTagsForResourceResult result = client.listTagsForResource(request);
List resultTags = result.getTags();
```
下列範例列出資料目錄 `datacatalogA` 的標籤：
```
ListTagsForResourceRequest request = new ListTagsForResourceRequest()
.withResourceARN("arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA");
ListTagsForResourceResult result = client.listTagsForResource(request);
List resultTags = result.getTags();
```
## 使用 管理標籤 AWS CLI
下列範例示範如何使用 AWS CLI 來建立和管理資料目錄上的標籤。
### 新增標籤至資源：tag-resource
`tag-resource` 命令將一或多個標籤新增到指定的資源。
**語法**
`aws athena tag-resource --resource-arn arn:aws:athena:region:account_id:datacatalog/catalog_name --tags Key=string,Value=string Key=string,Value=string`
`--resource-arn` 參數會指定要新增標籤的資源。`--tags` 參數會指定以空格分隔的鍵值組清單，以做為標籤新增至資源。
**Example**
下列範例會將標籤新增至 `mydatacatalog` 資料目錄。
```
aws athena tag-resource --resource-arn arn:aws:athena:us-east-1:111122223333:datacatalog/mydatacatalog --tags Key=Color,Value=Orange Key=Time,Value=Now
```
若要顯示結果，請使用 `list-tags-for-resource` 命令。
如需使用 `create-data-catalog` 命令時新增標籤的相關資訊，請參閱[註冊目錄：Create-data-catalog](datastores-hive-cli.md#datastores-hive-cli-registering-a-catalog)。
### 列出資源的標籤：list-tags-for-resource
`list-tags-for-resource` 命令會列出指定資源的標籤。
**語法**
`aws athena list-tags-for-resource --resource-arn arn:aws:athena:region:account_id:datacatalog/catalog_name`
`--resource-arn` 參數會指定列出標籤的資源。
下列範例列出 `mydatacatalog` 資料目錄的標籤。
```
aws athena list-tags-for-resource --resource-arn arn:aws:athena:us-east-1:111122223333:datacatalog/mydatacatalog
```
以下樣本結果為 JSON 格式。
```
{
"Tags": [
{
"Key": "Time",
"Value": "Now"
},
{
"Key": "Color",
"Value": "Orange"
}
]
}
```
### 從資源移除標籤：untag-resource
`untag-resource` 命令會從指定的資源中刪除指定的標籤鍵及其關聯的數值。
**語法**
`aws athena untag-resource --resource-arn arn:aws:athena:region:account_id:datacatalog/catalog_name --tag-keys key_name [key_name ...]`
`--resource-arn` 參數會指定要從中移除標籤的資源。`--tag-keys` 參數會取得以空格分隔的索引鍵名稱清單。對於指定的每個索引鍵名稱，`untag-resource` 命令會同時移除索引鍵及其數值。
下列範例會從 `mydatacatalog` 目錄資源中移除 `Color` 和 `Time` 索引鍵及其數值。
```
aws athena untag-resource --resource-arn arn:aws:athena:us-east-1:111122223333:datacatalog/mydatacatalog --tag-keys Color Time
```
# 使用標籤型 IAM 存取控制政策
使用標籤可讓您撰寫包含 `Condition` 區塊的 IAM 政策，以根據資源的標籤來控制對資源的存取。本節包含工作群組和資料目錄資源的標籤政策範例。
## 工作群組的標籤政策範例
### 範例 – 基本標籤政策
以下 IAM 政策可讓您執行查詢，並與名為 `workgroupA` 的工作群組的標籤互動：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:ListWorkGroups",
"athena:ListEngineVersions",
"athena:ListDataCatalogs",
"athena:ListDatabases",
"athena:GetDatabase",
"athena:ListTableMetadata",
"athena:GetTableMetadata"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"athena:GetWorkGroup",
"athena:TagResource",
"athena:UntagResource",
"athena:ListTagsForResource",
"athena:StartQueryExecution",
"athena:GetQueryExecution",
"athena:BatchGetQueryExecution",
"athena:ListQueryExecutions",
"athena:StopQueryExecution",
"athena:GetQueryResults",
"athena:GetQueryResultsStream",
"athena:CreateNamedQuery",
"athena:GetNamedQuery",
"athena:BatchGetNamedQuery",
"athena:ListNamedQueries",
"athena:DeleteNamedQuery",
"athena:CreatePreparedStatement",
"athena:GetPreparedStatement",
"athena:ListPreparedStatements",
"athena:UpdatePreparedStatement",
"athena:DeletePreparedStatement"
],
"Resource": "arn:aws:athena:us-east-1:123456789012:workgroup/workgroupA"
}
]
}
```
------
### 範例 – 根據標籤索引鍵和標籤值配對在工作群組上拒絕動作的政策區塊
與資源 (如工作群組) 相關聯的標籤稱為資源標籤。資源標籤可讓您編寫政策區塊，如以下項目在以鍵值組所標記的任何工作群組上拒絕列出的動作，例如 `stack`、`production`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"athena:GetWorkGroup",
"athena:UpdateWorkGroup",
"athena:DeleteWorkGroup",
"athena:TagResource",
"athena:UntagResource",
"athena:ListTagsForResource",
"athena:StartQueryExecution",
"athena:GetQueryExecution",
"athena:BatchGetQueryExecution",
"athena:ListQueryExecutions",
"athena:StopQueryExecution",
"athena:GetQueryResults",
"athena:GetQueryResultsStream",
"athena:CreateNamedQuery",
"athena:GetNamedQuery",
"athena:BatchGetNamedQuery",
"athena:ListNamedQueries",
"athena:DeleteNamedQuery",
"athena:CreatePreparedStatement",
"athena:GetPreparedStatement",
"athena:ListPreparedStatements",
"athena:UpdatePreparedStatement",
"athena:DeletePreparedStatement"
],
"Resource": "arn:aws:athena:us-east-1:123456789012:workgroup/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/stack": "production"
}
}
}
]
}
```
------
### 範例 – 限制對指定的標籤提出標籤變更動作請求的政策區塊
做為參數傳入至變更標籤之操作的標籤 (例如帶有標籤的 `TagResource`、`UntagResource` 或 `CreateWorkGroup`) 稱為請求標籤。下列範例政策區塊只有在傳遞的其中一個標籤具有索引鍵 `costcenter` 和數值 `1`、`2` 或 `3` 時，才允許 `CreateWorkGroup` 操作。
**注意**
如果您想要允許 IAM 角色在 `CreateWorkGroup` 操作中傳入標籤，請確定您授予角色進行 `TagResource` 和 `CreateWorkGroup` 動作的許可。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:CreateWorkGroup",
"athena:TagResource"
],
"Resource": "arn:aws:athena:us-east-1:123456789012:workgroup/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/costcenter": [
"1",
"2",
"3"
]
}
}
}
]
}
```
------
## 資料目錄的標籤政策範例
### 範例 – 基本標籤政策
以下 IAM 政策可讓您與名為 `datacatalogA` 的資料目錄的標籤互動：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:ListWorkGroups",
"athena:ListEngineVersions",
"athena:ListDataCatalogs",
"athena:ListDatabases",
"athena:GetDatabase",
"athena:ListTableMetadata",
"athena:GetTableMetadata"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"athena:GetWorkGroup",
"athena:TagResource",
"athena:UntagResource",
"athena:ListTagsForResource",
"athena:StartQueryExecution",
"athena:GetQueryExecution",
"athena:BatchGetQueryExecution",
"athena:ListQueryExecutions",
"athena:StopQueryExecution",
"athena:GetQueryResults",
"athena:GetQueryResultsStream",
"athena:CreateNamedQuery",
"athena:GetNamedQuery",
"athena:BatchGetNamedQuery",
"athena:ListNamedQueries",
"athena:DeleteNamedQuery"
],
"Resource": [
"arn:aws:athena:us-east-1:123456789012:workgroup/*"
]
},
{
"Effect": "Allow",
"Action": [
"athena:CreateDataCatalog",
"athena:GetDataCatalog",
"athena:UpdateDataCatalog",
"athena:DeleteDataCatalog",
"athena:ListDatabases",
"athena:GetDatabase",
"athena:ListTableMetadata",
"athena:GetTableMetadata",
"athena:TagResource",
"athena:UntagResource",
"athena:ListTagsForResource"
],
"Resource": "arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA"
}
]
}
```
------
### 範例 – 根據標籤索引鍵和標籤值組在資料目錄上拒絕動作的政策區塊
您可以使用資源標籤撰寫政策區塊，以拒絕針對以特定標籤鍵值組標記的資料目錄上的特定動作。下列範例政策會拒絕具有標籤鍵值組 `stack`、`production` 的資料目錄上的動作。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"athena:CreateDataCatalog",
"athena:GetDataCatalog",
"athena:UpdateDataCatalog",
"athena:DeleteDataCatalog",
"athena:GetDatabase",
"athena:ListDatabases",
"athena:GetTableMetadata",
"athena:ListTableMetadata",
"athena:StartQueryExecution",
"athena:TagResource",
"athena:UntagResource",
"athena:ListTagsForResource"
],
"Resource": "arn:aws:athena:us-east-1:123456789012:datacatalog/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/stack": "production"
}
}
}
]
}
```
------
### 範例 – 限制對指定的標籤提出標籤變更動作請求的政策區塊
做為參數傳入至變更標籤之操作的標籤 (例如帶有標籤的 `TagResource`、`UntagResource` 或 `CreateDataCatalog`) 稱為請求標籤。下列範例政策區塊只有在傳遞的其中一個標籤具有索引鍵 `costcenter` 和數值 `1`、`2` 或 `3` 時，才允許 `CreateDataCatalog` 操作。
**注意**
如果您想要允許 IAM 角色在 `CreateDataCatalog` 操作中傳入標籤，請確定您授予角色進行 `TagResource` 和 `CreateDataCatalog` 動作的許可。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:CreateDataCatalog",
"athena:TagResource"
],
"Resource": "arn:aws:athena:us-east-1:123456789012:datacatalog/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/costcenter": [
"1",
"2",
"3"
]
}
}
}
]
}
```
------
# Service Quotas
**注意**
Service Quotas 主控台提供有關 Amazon Athena 配額的資訊。您也可以使用 Service Quotas 主控台，針對可調整的配額[請求提高配額](https://console.aws.amazon.com/servicequotas/home?region=us-east-1#!/services/athena/quotas)。如需 AWS Glue 相關的結構描述限制，請參閱 [AWS Glue 端點和配額](https://docs.aws.amazon.com/general/latest/gr/glue.html)頁面。如需 AWS 服務配額的一般資訊，請參閱 中的[AWS 服務配額](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html)*AWS 一般參考*。
## 查詢
您的帳戶於 Amazon Athena 有下列查詢相關的配額：如需詳細資訊，請參閱 AWS 一般參考的 [Amazon Athena 端點和配額](https://docs.aws.amazon.com/general/latest/gr/athena.html#amazon-athena-limits)頁面。
+ **Active DDL queries** (作用中 DDL 查詢) - 作用中 DDL 查詢的數量。DDL 查詢包括 `CREATE TABLE` 和 `ALTER TABLE ADD PARTITION` 查詢。
+ **DDL query timeout** (DDL 查詢逾時) - DDL 查詢在取消之前可以執行的時間上限，以分鐘為單位。
+ **Active DML queries** (作用中 DML 查詢) - 作用中 DML 查詢的數量。DML 查詢包括 `SELECT`、`CREATE TABLE AS` (CTAS)和 `INSERT INTO` 查詢。具體配額因 AWS 區域而異。
+ **DML query timeout** (DML 查詢逾時) - DML 查詢在取消之前可以執行的時間上限，以分鐘為單位。您可以請求將此逾時增加最多 240 分鐘。
若要請求增加配額，可使用 [Athena Service Quotas](https://console.aws.amazon.com/servicequotas/home?region=us-east-1#!/services/athena/quotas) 主控台。
Athena 會根據整體服務負載和傳入請求數量，以指派資源來處理查詢。系統可能會在執行您的查詢之前，先將其暫時排入佇列。非同步處理會從佇列中接收查詢，並在資源可用且帳戶設定允許的情況下，立即在實體資源上執行查詢。
Active DML 查詢和 Active DDL 查詢配額包括正在執行中和已排入佇列的查詢。例如，如果您的 Active DML 查詢配額為 25，而正在執行中和佇列的查詢總數為 26，則查詢 26 會出現 TooManyRequestsException 的錯誤。
**注意**
若您要直接控制在 Athena 中執行的查詢的並行，則可以使用容量保留。如需詳細資訊，請參閱[管理查詢處理容量](capacity-management.md)。
### 查詢字串長度
允許的查詢字串長度上限是 262144 位元組，其中字串以 UTF-8 編碼。這不是可調整的配額。不過，您可以將長查詢分割成多個較小的查詢，以解決這項限制。如需詳細資訊，請參閱 AWS 知識中心中的[如何在 Athena 中增加最大查詢字串長度？](https://aws.amazon.com/premiumsupport/knowledge-center/athena-query-string-length/)。
## 工作群組
使用 Athena 工作群組時，請記住以下幾點：
+ Athena Service Quotas 會在帳戶中的所有工作群組之間共用。
+ 可以在帳戶中為每個區域建立的工作群組數量上限為 1000 個。
+ 工作群組中預備陳述式的數量上限為 1000。
+ 每一工作階段的標籤數上限為 50。如需詳細資訊，請參閱[標籤限制](tags.md#tag-restrictions)。
## 資料庫、資料表和分割區
Athena 使用 AWS Glue Data Catalog。如需了解資料表、資料庫和分割區的服務配額 (例如，每個帳戶的資料庫或資料表數量上限)，請參閱 [AWS Glue 端點和配額](https://docs.aws.amazon.com/general/latest/gr/glue.html)。請注意，雖然 Athena 支援查詢具有 1，000 萬個分割區的 AWS Glue 資料表，但 Athena 無法在單一掃描中讀取超過 100 萬個分割區。
## Amazon S3 儲存貯體
在您使用 Amazon S3 儲存貯體時，請記住以下幾點：
+ Amazon S3 預設的服務配額為每個帳戶 10，000 個儲存貯體。
+ Athena 需有一個單獨的儲存貯體來記錄結果。
+ 您可以要求每個 AWS 帳戶增加最多 100 萬個 Amazon S3 儲存貯體的配額。
## 每個帳戶 API 呼叫配額
Athena API 關於每個帳戶 (而非每個查詢) 的 API 呼叫數量的預設配額。如需預設配額的完整清單，請參閱 AWS 一般參考 指南中的[服務配額](https://docs.aws.amazon.com/general/latest/gr/athena.html#amazon-athena-limits)表。
如果您使用任何這些 API，且超過預設的每秒呼叫數配額，或帳戶中的高載容量，Athena API 會發出類似以下的錯誤："ClientError: An error occurred (ThrottlingException) when calling the ** operation: Rate exceeded." (ClientError：呼叫 操作時發生錯誤 (ThrottlingException)：超過速率。) 請減少每秒呼叫次數，或此帳戶的 API 爆發容量。
您可以在 [Athena Service Quotas 主控台](https://console.aws.amazon.com/servicequotas/home?region=us-east-1#!/services/athena/quotas)中變更每個帳戶 API 呼叫的 Athena 配額。
# Athena 引擎版本控制
Athena 偶爾會發行新的引擎版本，以提供改進的效能、功能和程式碼修正。當有新的引擎版本可供使用時，Athena 會透過 Athena 主控台和 [AWS Health 儀板表](https://aws.amazon.com/premiumsupport/technology/personal-health-dashboard/) 通知您。您的 會 AWS Health 儀板表 通知您可能影響 AWS 服務或帳戶的事件。如需 的詳細資訊 AWS Health 儀板表，請參閱 [入門 AWS Health 儀板表](https://docs.aws.amazon.com/health/latest/ug/getting-started-phd.html)。
引擎版本控制是按[工作群組](workgroups-manage-queries-control-costs.md)設定。您可以使用工作群組來控制查詢所使用的查詢引擎，以及是否讓 Athena 自動升級工作群組。使用中的查詢引擎會顯示在查詢編輯器中的工作群組詳細資訊頁面上，並可透過 Athena API 取得。
+ 依預設，工作群組設定為自動升級。當工作群組設定為自動升級時，Athena 會為您升級工作群組，除非它發現不相容。
+ 如果您將工作群組設定為使用特定版本，Athena 將不會變更工作群組的版本。
在這兩種情況下，當版本不再可用時，Athena 會升級您的工作群組。Athena 會透過 [AWS Health 儀板表](https://aws.amazon.com/premiumsupport/technology/personal-health-dashboard/) 通知您何時不再提供某個引擎版本。您的 會 Health 儀板表 通知您可能影響 AWS 服務或帳戶的事件。如需 的詳細資訊 AWS Health 儀板表，請參閱 [入門 AWS Health 儀板表](https://docs.aws.amazon.com/health/latest/ug/getting-started-phd.html)。
當您開始使用新的引擎版本時，一小部分的查詢子集可能會因為不相容而中斷。在發布新的 Athena 版本時，即會公告重大變更。您應透過建立使用新引擎的測試工作群組或測試升級現有工作群組，在升級之前使用工作群組來測試查詢。如需詳細資訊，請參閱[在引擎版本升級之前測試查詢](engine-versions-changing.md#engine-versions-testing)。
**Topics**
+ [變更 Athena 引擎版本](engine-versions-changing.md)
+ [Athena 引擎版本 3](engine-versions-reference-0003.md)
# 變更 Athena 引擎版本
Athena 偶爾會發行新的引擎版本，以提供改進的效能、功能和程式碼修正。當有新的引擎版本可供使用時，Athena 會在主控台中通知您。您可以選擇讓 Athena 決定何時升級，或手動為每個工作群組指定 Athena 引擎版本。
## 尋找工作群組的引擎版本
您也可以使用 **Workgroups** (工作群組) 頁面，來尋找任何工作群組目前使用的引擎版本。
**若要尋找任意工作群組目前的引擎版本**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 如果未顯示主控台的導覽窗格，請選擇左側的展開選單。
![\[選擇展開選單。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/nav-pane-expansion.png)
1. 在 Athena 主控台導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 在 **Workgroups** (工作群組) 頁面，尋找您想要的工作群組。工作群組的 **Query engine version** (查詢引擎版本) 欄位顯示查詢引擎版本。
## 使用 Athena 主控台變更引擎版本
當有新的引擎版本可用時，您可以選擇讓 Athena 決定何時升級工作群組，或手動指定工作群組使用的 Athena 引擎版本。如果目前只有一個版本可以使用，則無法手動指定不同版本。
**注意**
若要變更工作群組的引擎版本，必須擁有許可，才能對該工作群組執行 `athena:ListEngineVersions` 動作。如需 IAM 政策範例，請參閱 [工作群組政策範例](example-policies-workgroup.md)。
**讓 Athena 決定何時升級工作群組**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 如果未顯示主控台的導覽窗格，請選擇左側的展開選單。
1. 在主控台導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 在工作群組清單中，選擇您想要設定的工作群組連結。
1. 選擇**編輯**。
1. 在 **Query engine version** (查詢引擎版本) 中，對於 **Update query engine** (更新查詢引擎)，選擇 **Automatic** (自動) 讓 Athena 選擇何時升級您的工作群組。這是預設設定。
1. 選擇**儲存變更**。
在工作群組清單中，工作群組的 **Query engine update status** (查詢引擎更新狀態) 會顯示為 **Automatic** (自動)。
**若要手動選擇引擎版本**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 如果未顯示主控台的導覽窗格，請選擇左側的展開選單。
1. 在主控台導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 在工作群組清單中，選擇您想要設定的工作群組連結。
1. 選擇**編輯**。
1. 在 **Query engine version** (查詢引擎版本) 下，對於 **Update query engine** (更新查詢引擎)，選擇 **Manually** (手動) 即可手動選擇引擎版本。
1. 使用 **Query engine version** (查詢引擎版本) 選項，選擇您希望工作群組使用的引擎版本。如果不同引擎版本無法使用，則無法指定不同引擎版本。
1. 選擇**儲存變更**。
在工作群組清單中，工作群組的 **Query engine update status** (查詢引擎更新狀態) 會顯示為 **Manual** (手動)。
## 使用 AWS CLI 變更引擎版本
若要使用 變更引擎版本 AWS CLI，請使用下列範例中的語法。
```
aws athena update-work-group --work-group workgroup-name --configuration-updates EngineVersion={SelectedEngineVersion='Athena engine version 3'}
```
## 在建立工作群組時指定引擎版本
當您建立工作群組時，您可以指定工作群組使用的引擎版本，或讓 Athena 決定何時升級工作群組。如果新的引擎版本可供使用，則最佳實務則是建立工作群組，以測試新引擎，然後再升級其他工作群組。若要指定工作群組的引擎版本，您必須擁有工作群組的 `athena:ListEngineVersions` 許可。如需 IAM 政策範例，請參閱 [工作群組政策範例](example-policies-workgroup.md)。
**若要在建立工作群組時指定引擎版本**
1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 開啟 Athena 主控台。
1. 如果未顯示主控台的導覽窗格，請選擇左側的展開選單。
1. 在主控台導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 在 **Workgroups** (工作群組) 頁面中，請選擇 **Create workgroup** (建立工作群組)。
1. 在 **Create workgroup** (建立工作群組) 頁面中，請於 **Query engine version** (查詢引擎版本) 區段執行下列其中一項動作：
+ 選擇 **Automatic** (自動)，便可讓 Athena 選擇何時升級您的工作群組。這是預設設定。
+ 如果有不同引擎版本可供使用，透過選擇 **Manual** (手動)，便可手動選擇該引擎版本。
1. 視需要輸入其他欄位的資訊。如需其他欄位的相關資訊，請參閱 [建立工作群組](creating-workgroups.md)。
1. 選擇 **Create workgroup** (建立工作群組)。
## 在引擎版本升級之前測試查詢
當工作群組升級到新的引擎版本時，您的部分查詢可能會因為不相容而中斷。若要確保您的引擎版本升級順利進行，您可以事先測試您的查詢。
**若要在引擎版本升級之前測試您的查詢**
1. 請驗證您所使用的工作群組引擎版本。您正在使用的引擎版本顯示在 **Workgroups** (工作群組) 頁面上用於該工作群組的 **Query engine version** (查詢引擎版本) 欄位中。如需詳細資訊，請參閱[尋找工作群組的引擎版本](#engine-versions-changing-finding-the-query-engine-version-for-a-workgroup)。
1. 建立使用新引擎版本的測試工作群組。如需詳細資訊，請參閱[在建立工作群組時指定引擎版本](#engine-versions-changing-specifying-the-engine-version-when-you-create-a-workgroup)。
1. 使用新工作群組來執行您要測試的查詢。
1. 如果查詢失敗，請檢查新引擎中是否有可能會影響查詢的重大變更。某些變更可能需要您更新查詢的語法。
1. 如果您的查詢仍然失敗，請聯絡 AWS 支援 尋求協助。在 AWS 管理主控台中，選擇**支援**、**支援中心**，或使用 **Amazon Athena** 標籤在 [AWS re:Post](https://repost.aws/tags/TA78iVOM7gR62_QqDe2-CmiA/amazon-athena) 上詢問問題。
## 對引擎版本升級後失敗的查詢進行疑難排解
如果查詢在引擎版本升級後失敗，請檢查是否有重大變更，包括可能會影響查詢中的語法的變更。
如果您的查詢仍然失敗，請聯絡 AWS 支援 尋求協助。在 中 AWS 管理主控台，選擇**支援**、**支援中心**，或使用 **Amazon Athena** 標籤在 [AWS re：Post](https://repost.aws/tags/TA78iVOM7gR62_QqDe2-CmiA/amazon-athena) 上提出問題。
# Athena 引擎版本 3
Athena 引擎版本 3 也仍然採用持續整合方法，管理開放原始碼軟體，提高 [Trino](https://trino.io/) 和 [Presto](https://prestodb.io/) 專案的並行數，讓您可以更快速地使用到各種改善後的社群功能，並在 Athena 引擎中執行整合和調整。
此次推出的 Athena 引擎版本 3 支援先前的引擎版本的所有功能。本文件會重點說明先前的引擎版本與 Athena 引擎版本 3 之間的主要差異。如需詳細資訊，請參閱 *AWS 大數據部落格*文章「[升級至 Athena 引擎版本 3，以提升查詢效能並存取更多分析功能](https://aws.amazon.com/blogs/big-data/upgrade-to-athena-engine-version-3-to-increase-query-performance-and-access-more-analytics-features/)」。
+ [開始使用](#engine-versions-reference-0003-getting-started)
+ [改善和新功能](#engine-versions-reference-0003-improvements-and-new-features)
+ [新增功能](#engine-versions-reference-0003-added-features)
+ [新增的函數](#engine-versions-reference-0003-added-functions)
+ [效能改進](#engine-versions-reference-0003-performance-improvements)
+ [可靠性增強功能](#engine-versions-reference-0003-reliability-enhancements)
+ [查詢語法增強功能](#engine-versions-reference-0003-query-syntax-enhancements)
+ [資料格式和資料類型增強功能](#engine-versions-reference-0003-data-format-and-data-type-enhancements)
+ [突破性變更](#engine-versions-reference-0003-breaking-changes)
+ [查詢語法變更](#engine-versions-reference-0003-syntax-changes)
+ [資料處理變更](#engine-versions-reference-0003-data-processing-changes)
+ [時間戳記變更](#engine-versions-reference-0003-timestamp-changes)
+ [限制](#engine-versions-reference-0003-known-limitations)
## 開始使用
若要開始使用，請建立使用 Athena 引擎版本 3 的新 Athena 工作群組，或將現有工作群組設定為使用版本 3。
如需詳細資訊，請參閱[變更 Athena 引擎版本](https://docs.aws.amazon.com/athena/latest/ug/engine-versions-changing.html)。
## 改善和新功能
所列之功能和更新內容包括 Athena 本身的功能改進，以及從開放原始碼 Trino 整合的功能改進。如需有關 SQL 查詢運算子和函數的詳盡清單，請參閱 [Trino 文件](https://trino.io/docs/current/functions.html)。
### 新增功能
#### Apache Spark 歸納演算法支援
Athena 可讀取 Spark 雜湊演算法產生的儲存貯體。若要指定最初由 Spark 雜湊演算法撰寫該資料，請將 `('bucketing_format'='spark')` 放入 `CREATE TABLE` 陳述式的 `TBLPROPERTIES` 子句中。若未指定此屬性，則系統會使用 Hive 雜湊演算法。
```
CREATE EXTERNAL TABLE `spark_bucket_table`(
`id` int,
`name` string
)
CLUSTERED BY (`name`)
INTO 8 BUCKETS
STORED AS PARQUET
LOCATION
's3://amzn-s3-demo-bucket/to/bucketed/table/'
TBLPROPERTIES ('bucketing_format'='spark')
```
### 新增的函數
本節中的函數是 Athena 引擎版本 3 中新增的函數。
#### 彙總函數
**listagg(x, separator)** – 傳回串連的輸入值，由分隔符號字串分開。
```
SELECT listagg(value, ',') WITHIN GROUP (ORDER BY value) csv_value
FROM (VALUES 'a', 'c', 'b') t(value);
```
#### 陣列函數
**contains\$1sequence(x, seq)** – 如果陣列 x 包含所有陣列序列，並作為循序子集 (相同連續順序中的所有值)，則會傳回 true。
```
SELECT contains_sequence(ARRAY [1,2,3,4,5,6], ARRAY[1,2]);
```
#### 二進位函數
**murmur3(binary)** – 計算二進位的 128 位元 MurmurHash3 雜湊。
```
SELECT murmur3(from_base64('aaaaaa'));
```
#### 轉換函數
**format\$1number(number)** – 傳回使用單位符號的格式化字串。
```
SELECT format_number(123456); -- '123K'
```
```
SELECT format_number(1000000); -- '1M'
```
#### 日期和時間函數
**timezone\$1hour(timestamp)** – 傳回與時間戳記偏離的時區小時數。
```
SELECT EXTRACT(TIMEZONE_HOUR FROM TIMESTAMP '2020-05-10 12:34:56 +08:35');
```
**timezone\$1minute(timestamp)** – 傳回與時間戳記偏離的時區分鐘數。
```
SELECT EXTRACT(TIMEZONE_MINUTE FROM TIMESTAMP '2020-05-10 12:34:56 +08:35');
```
#### 地理空間函數
**to\$1encoded\$1polyline(Geometry)** – 將 linestring 或 multipoint 編碼為 polyline。
```
SELECT to_encoded_polyline(ST_GeometryFromText(
'LINESTRING (-120.2 38.5, -120.95 40.7, -126.453 43.252)'));
```
**from\$1encoded\$1polyline(varchar)** – 將 polyline 解碼為 linestring。
```
SELECT ST_AsText(from_encoded_polyline('_p~iF~ps|U_ulLnnqC_mqNvxq`@'));
```
**to\$1geojson\$1geometry(SphericalGeography)** – 以 GeoJSON 格式傳回指定的球形地理資訊。
```
SELECT to_geojson_geometry(to_spherical_geography(ST_GeometryFromText(
'LINESTRING (0 0, 1 2, 3 4)')));
```
**from\$1geojson\$1geometry(varchar)** – 以 GeoJSON 表示法傳回剝離非幾何鍵/值的球形地理類型物件。不支援 `Feature` 和 `FeatureCollection`。
```
SELECT from_geojson_geometry(to_geojson_geometry(to_spherical_geography(ST_GeometryFromText(
'LINESTRING (0 0, 1 2, 3 4)'))));
```
**geometry\$1nearest\$1points(Geometry, Geometry)** – 傳回每個幾何形狀上互相最近的點。如果任一幾何形狀為空，則會傳回 NULL。否則，便會傳回由兩個 `Point` 物件組成的資料列，這兩個物件與幾何形狀上任兩點的距離為最小距離。第一個點來自第一個 Geometry 引數，第二個點來自第二個 Geometry 引數。如果有多個具有相同最小距離的配對，則會任意選擇一對。
```
SELECT geometry_nearest_points(ST_GeometryFromText(
'LINESTRING (50 100, 50 200)'), ST_GeometryFromText(
'LINESTRING (10 10, 20 20)'));
```
#### Set Digest 函數
**make\$1set\$1digest(x)** – 將 x 的所有輸入值撰寫成一個 Setdigest。
```
SELECT make_set_digest(value) FROM (VALUES 1, 2, 3) T(value);
```
#### 字串函數
**soundex(char)** – 傳回包含字元音標表示法的字元串。
```
SELECT name
FROM nation
WHERE SOUNDEX(name) = SOUNDEX('CHYNA'); -- CHINA
```
**concat\$1ws(string0, string1, ..., stringN)** – 傳回串連的 `string1, string2, ..., stringN` (使用 `string0` 作分隔符號)。如果 `string0` 為 NULL，則傳回值為 NULL。系統會略過在分隔符號後以引數方式提供的任何 Null 值。
```
SELECT concat_ws(',', 'def', 'pqr', 'mno');
```
#### 範圍函數
**GROUPS** – 新增對群組型範圍框的支援。
```
SELECT array_agg(a) OVER(
ORDER BY a ASC NULLS FIRST GROUPS BETWEEN 1 PRECEDING AND 2 FOLLOWING)
FROM (VALUES 3, 3, 3, 2, 2, 1, null, null) T(a);
```
### 效能改進
Athena 引擎版本 3 的效能改進包含以下內容。
+ **更快速的 AWS Glue 資料表中繼資料擷取** – 涉及多個資料表的查詢將縮短查詢規劃時間。
+ **RIGHT JOIN 的動態篩選** – 現可針對具有相等聯結條件的右端聯結啟用動態篩選，如以下範例所示。
```
SELECT *
FROM lineitem RIGHT JOIN tpch.tiny.supplier
ON lineitem.suppkey = supplier.suppkey
WHERE supplier.name = 'abc';
```
+ **大型預備陳述式** – 預設 HTTP 請求/回應標頭大小已增加至 2 MB，以允許使用大型預備陳述式。
+ **approx\$1percentile()** – `approx_percentile` 函數現在使用 `tdigest` 而不是 `qdigest` 來從分佈擷取近似分位數值。這會導致更高的效能以及更低的記憶體使用量。請注意，由於此變更，函式傳回的結果與先前的引擎版本中的結果不同。如需詳細資訊，請參閱[approx\$1percentile 函數會傳回不同的結果](#engine-versions-reference-0003-approx-percentile-function)。
### 可靠性增強功能
Athena 引擎版本 3 的一般引擎記憶體用量和追蹤功能已改進。大型查詢較不易因節點當機而失敗。
### 查詢語法增強功能
**INTERSECT ALL** – 已新增對 `INTERSECT ALL` 的支援。
```
SELECT * FROM (VALUES 1, 2, 3, 4) INTERSECT ALL SELECT * FROM (VALUES 3, 4);
```
**EXCEPT ALL** – 已新增對 `EXCEPT ALL` 的支援。
```
SELECT * FROM (VALUES 1, 2, 3, 4) EXCEPT ALL SELECT * FROM (VALUES 3, 4);
```
**RANGE PRECEDING** – 已新增對範圍函數中 `RANGE PRECEDING` 的支援。
```
SELECT sum(x) over (order by x range 1 preceding)
FROM (values (1), (1), (2), (2)) t(x);
```
**MATCH\$1RECOGNIZE** – 已新增對資料列模式比對的支援，如以下範例所示。
```
SELECT m.id AS row_id, m.match, m.val, m.label
FROM (VALUES(1, 90),(2, 80),(3, 70),(4, 70)) t(id, value)
MATCH_RECOGNIZE (
ORDER BY id
MEASURES match_number() AS match,
RUNNING LAST(value) AS val,
classifier() AS label
ALL ROWS PER MATCH
AFTER MATCH SKIP PAST LAST ROW
PATTERN (() | A) DEFINE A AS true
) AS m;
```
### 資料格式和資料類型增強功能
Athena 引擎版本 3 具有以下資料格式和資料類型增強功能。
+ **LZ4 和 ZSTD** – 已新增對讀取 LZ4 和 ZSTD 壓縮 Parquet 資料的支援。已新增對寫入 ZSTD 壓縮 ORC 資料的支援。
+ **符號連結型資料表** – 已新增對在 Avro 檔案上建立符號連結型資料表的支援。範例如下。
```
CREATE TABLE test_avro_symlink
ROW FORMAT SERDE 'org.apache.hadoop.hive.serde2.avro.AvroSerDe'
...
INPUTFORMAT 'org.apache.hadoop.hive.ql.io.SymlinkTextInputFormat'
```
+ **SphericalGeography** – SphericalGeography 類型對地理座標 (有時稱為測地座標、緯度/經度或緯度/經度) 上所表示的空間特徵提供原生支援。地理座標是以角度單位 (度) 來表示的球面座標。
`to_spherical_geography` 函數會從幾何 (平面) 座標傳回地理 (球形) 座標，如以下範例所示。
```
SELECT to_spherical_geography(ST_GeometryFromText(
'LINESTRING (-40.2 28.9, -40.2 31.9, -37.2 31.9)'));
```
## 突破性變更
從先前的引擎版本移轉至 Athena 引擎版本 3 時，特定變更可能會影響資料表結構描述、語法或資料類型用量。本節會列出相關的錯誤訊息，並提供建議的因應措施。
### 查詢語法變更
#### IGNORE NULLS 不能與非值視窗函數一起使用
**錯誤訊息**：無法為 `bool_or` 函數指定 Null 處理方式子句。
**原因**：`IGNORE NULLS` 現在只能與[值函數](https://trino.io/docs/current/functions/window.html#value-functions) `first_value`、`last_value`、`nth_value`、`lead` 和 `lag` 一起使用。此變更之目的是符合 ANSI SQL 規格。
**建議的解決方案**：從查詢字符串中的非值視窗函數中移除 `IGNORE NULLS`。
#### CONCAT 函數必須有兩個或多個引數
**錯誤信息**：INVALID\$1FUNCTION\$1ARGUMENT: There must be two or more concatenation arguments (NVALID\$1FUNCTION\$1ARGUMENT：必須有兩個或多個串聯參數)
**原因**：先前，`CONCAT` 字串函數接受了單一引數。在 Athena 引擎版本 3 中，`CONCAT` 函數需要至少兩個引數。
**建議的解決方案**：將出現次數從 `CONCAT(str)` 變更為 `CONCAT(str, '')`。
在 Athena 引擎版本 3 中，函數中不可超過 127 個引數。如需詳細資訊，請參閱[函數呼叫的引數過多](troubleshooting-athena.md#troubleshooting-athena-too-many-arguments)。
#### approx\$1percentile 函數會傳回不同的結果
`approx_percentile` 函式會在 Athena 引擎版本 3 中傳回的結果與先前的引擎版本中傳回的結果不同。
**錯誤訊息**：無。
**原因**：`approx_percentile` 函數可能因版本變更而變更。
**重要**
由於 `approx_percentile` 函數的輸出是近似值，並且近似值可能會從一個版本變更為下一個版本，因此關鍵應用程式不得倚賴 `approx_percentile` 函數。
**建議的解決方案**：若要將先前的引擎版本行為估算為 `approx_percentile`，您可以在 Athena 引擎版本 3 中使用不同的函式組。例如，假設您在先前的引擎版本中有下列查詢：
```
SELECT approx_percentile(somecol, 2E-1)
```
若要估計 Athena 引擎版本 3 中的相同輸出，您可以嘗試使用 `qdigest_agg` 和 `value_at_quantile` 函數，如下列範例所示。請注意，即使使用此解決方法，也不能保證行為相同。
```
SELECT value_at_quantile(qdigest_agg(somecol, 1), 2E-1)
```
#### 地理空間函數不支援 varbinary 輸入
**錯誤訊息**：FUNCTION\$1NOT\$1FOUND for st\$1XXX
**原因**：一些地理空間函數不再支援舊版 `VARBINARY` 輸入類型或與文字相關的函數簽章。
**建議的解決方案**：使用地理空間函數將輸入類型轉換為受支援的類型。錯誤訊息會指出受支援的輸入類型。
#### 在 GROUP BY 子句中，巢狀資料欄必須使用雙引號
**錯誤訊息**："*column\$1name*"."*nested\$1column*" 必須是彙總表達式，或出現在 GROUP BY 子句中
**原因**：Athena 引擎版本 3 要求 `GROUP BY` 子句中的巢狀資料欄名稱必須加上雙引號。例如，下列查詢會產生錯誤，因為在 `GROUP BY` 子句中，`user.name` 未使用雙引號。
```
SELECT "user"."name" FROM dataset
GROUP BY user.name
```
**建議的解決方案**：在 `GROUP BY` 子句中的巢狀資料欄名稱周圍使用雙引號，如下列範例所示。
```
SELECT "user"."name" FROM dataset
GROUP BY "user"."name"
```
#### 在 Iceberg 資料表上使用 OPTIMIZE 時發生未預期的 FilterNode 錯誤
**錯誤訊息**：計畫中發現未預期的 FilterNode；可能是連接器無法處理提供的 WHERE 表達式。
**原因**：在 Iceberg 資料表上執行的 `OPTIMIZE` 陳述式使用了 `WHERE` 子句，其中該子句在其篩選條件表達式中包含了非分割區資料欄。
**建議的解決方案**：`OPTIMIZE` 陳述式僅支援依分割區來進行篩選。當您在已分割的資料表上執行 `OPTIMIZE` 時，請在 `WHERE` 子句中僅包含分割區資料欄。如果您在未分割的資料表上執行 `OPTIMIZE`，請勿指定 `WHERE` 子句。
#### Log() 函數引數的順序
在 Athena 引擎版本 3 中，`log()` 函式的引數順序已變更為 `log(base, value)`，以符合 SQL 標準。
#### Minute() 函數不支援 interval year to month
**錯誤訊息**：Unexpected parameters (interval year to month) for function minute.(Minute 函數的意外參數 (間隔使用年份和月份)。) Expected: minute(timestamp with time zone) , minute(time with time zone) , minute(timestamp) , minute(time) , minute(interval day to second). (函數 minute 出現未預期參數 (interval year to month)。預期：minute(timestamp with time zone)、minute(time with time zone)、minute(timestamp)、minute(time)、minute(interval day to second)。)
**原因**：在 Athena 引擎版本 3 中，已依據 ANSI SQL 規格，更精確地為 `EXTRACT` 執行類型檢查。
**建議的解決方案**：更新查詢，以確保類型與建議的函數簽章相符。
#### ORDER BY 表達式必須出現在 SELECT 清單中。
**錯誤訊息**：For SELECT DISTINCT, ORDER BY expressions must appear in SELECT list (若為 SELECT DISTINCT，ORDER BY 表達式必須出現在 SELECT 清單中)
**原因**：`SELECT` 子句中使用了不正確的資料表別名方式。
**建議的解決方案**：再次檢查 `ORDER BY` 表達式中的所有資料欄是否在 `SELECT DISTINCT` 子句中皆具有正確參考。
#### 比較從子查詢傳回的多個資料欄時，查詢失敗
**範例錯誤訊息**：值表達式和子查詢的結果必須是相同的類型：資料列(varchar, varchar) 與資料列(row(varchar, varchar))
**原因**：由於 Athena 引擎版本 3 中的語法更新，當查詢嘗試比較子查詢傳回的多個值，而子查詢 `SELECT` 陳述式會包括其資料欄清單 (用括號) 時，就會發生此錯誤，如下列範例所示。
```
SELECT *
FROM table1
WHERE (t1_col1, t1_col2)
IN (SELECT (t2_col1, t2_col2) FROM table2)
```
**解決方案**：在 Athena 引擎版本 3 中，移除子查詢 `SELECT` 陳述式中資料欄清單周圍的括號，如下列更新的範例查詢所示。
```
SELECT *
FROM table1
WHERE (t1_col1, t1_col2)
IN (SELECT t2_col1, t2_col2 FROM table2)
```
#### SKIP 是 DML 查詢的保留字詞
單字 `SKIP` 是 DML 查詢的保留字詞，例如 `SELECT`。若要在 DML 查詢中將 `SKIP` 用作識別符，請將其括在雙引號中。
如需有關 Athena 中保留字詞的詳細資訊，請參閱 [在查詢中逸出預留關鍵字](reserved-words.md)。
#### 時間歷程已取代 SYSTEM\$1TIME 和 SYSTEM\$1VERSION 子句。
**錯誤訊息**：mismatched input 'SYSTEM\$1TIME'. (不相符的輸入 'SYSTEM\$1TIME'。) 預期：'TIMESTAMP'、'VERSION'
**原因**：在先前的引擎版本中，Iceberg 資料表使用了 `FOR SYSTEM_TIME AS OF` 和 `FOR SYSTEM_VERSION AS OF` 子句作為時間戳記和版本時間歷程。Athena 引擎版本 3 使用了 `FOR TIMESTAMP AS OF` 和 `FOR VERSION AS OF` 子句。
**建議的解決方案**：更新 SQL 查詢，以使用 `TIMESTAMP AS OF` 和 `VERSION AS OF` 子句作為時間歷程操作，如下列範例所示。
依時間戳記的時間歷程：
```
SELECT * FROM TABLE FOR TIMESTAMP AS OF (current_timestamp - interval '1' day)
```
依版本的時間歷程：
```
SELECT * FROM TABLE FOR VERSION AS OF 949530903748831860
```
#### 陣列建構的引數過多
**錯誤訊息**：TOO\$1MANY\$1ARGUMENTS：陣列建構的引數過多。
**原因**：陣列建構中的元素數目上限現已設定為 254。
**建議的解決方案**：將元素分解為多個陣列，每個陣列具有 254 個或更少的元素，並使用 `CONCAT` 函數來串連陣列，如下列範例所示。
```
CONCAT(
ARRAY[x1,x2,x3...x254],
ARRAY[y1,y2,y3...y254],
...
)
```
#### 不允許使用零長度分隔的識別碼
**錯誤訊息**：Zero-length delimited identifier not allowed. (不允許使用零長度分隔的識別碼。)
**原因**：查詢使用了空白字串作為資料欄別名。
**建議的解決方案**：更新查詢以使用非空白的資料欄別名。
### 資料處理變更
#### 儲存貯體驗證
**錯誤訊息**：HIVE\$1INVALID\$1BUCKET\$1FILES：Hive 資料表已損壞。
**原因**：該資料表可能已損壞。為確定歸納資料表的查詢正確性，Athena 引擎版本 3 會在歸納資料上啟用額外的驗證，以確保查詢的正確性並避免執行期發生非預期的失敗。
**建議的解決方案**：使用 Athena 引擎版本 3 重新建立資料表。
#### 現在，將結構轉換為 JSON，會傳回欄位名稱
當您在 Athena 引擎第 3 版的 `SELECT` 查詢中將 `struct` 轉換為 JSON 時，該轉換現在會傳回欄位名稱和值 (例如 "`useragent":null`) 而非只是值 (例如，`null`)。
#### Iceberg 資料表資料欄層級安全性強制執行變更
**錯誤信息**：Access Denied: Cannot select from columns (存取遭拒：無法從資料欄中選取)
**原因**：Iceberg 資料表是在 Athena 之外建立的，並使用早於 0.13.0 的 [Apache Iceberg SDK](https://iceberg.apache.org/releases/) 版本。由於舊版 SDK 不會在 中填入資料欄 AWS Glue，Lake Formation 無法判斷授權存取的資料欄。
**建議的解決方案**：使用 Athena [ALTER TABLE SET TBLPROPERTIES](querying-iceberg-alter-table-set-properties.md) 陳述式執行更新，或使用最新的 Iceberg SDK 來修正資料表並更新 AWS Glue中的資料欄資訊。
#### List 資料類型中的 Null 值現已傳播至 UDF
**錯誤訊息**：Null Pointer Exception (Null 指標異常情形)
**原因**：如果您使用 UDF 連接器並已執行使用者定義的 Lambda 函數，則此問題可能會對您產生影響。
先前的引擎版本會篩選出 List 資料類型中已傳遞給使用者定義函式的 Null 值。在 Athena 引擎版本 3 中，會保留 Null 值並傳遞給 UDF。如果 UDF 嘗試在未檢查的情況下取消參考 Null 元素，這可能會導致 Null 指標異常情形。
例如，若您在如 DynamoDB 等原始資料來源中具有資料 `[null, 1, null, 2, 3, 4]`，則系統會將以下項目傳遞至使用者定義的 Lambda 函數：
**Athena 引擎版本 3**：`[null, 1, null, 2, 3, 4]`
**建議的解決方案**：確保使用者定義的 Lambda 函數會處理 List 資料類型中的 Null 元素。
#### 字元陣列中的子字串不再包含已填補的空格
**錯誤訊息**：No error is thrown, but the string returned no longer contains padded spaces. (未擲回任何錯誤，但傳回的字串不再包含已填補的空格。) 例如，`substr(char[20],1,100)` 現在會傳回長度為 20 而非 100 的字串。
**建議的解決方案**：無需採取任何動作。
#### 不支援的十進位資料欄類型強制轉換
**錯誤訊息**：HIVE\$1CURSOR\$1ERROR：讀取 Parquet 檔案失敗：s3://amzn-s3-demo-bucket/*path*/*file\$1name*.parquet 或 Parquet 資料欄有不支援的資料欄類型 (varchar) ([*column\$1name*]
**原因**：當嘗試將資料類型強制從 `varchar` 轉換為 decimal 時，Athena 引擎版本 2 偶有成功 (但經常失敗)。由於 Athena 引擎版本 3 會有類型驗證，即會在嘗試讀取值之前先檢查類型是否相容，因此類型嘗試強制執行現在總會失敗。
**建議的解決方案**：對於 Athena 引擎第 3 版，在 中修改結構描述 AWS Glue ，以使用數值資料類型，而不是 Parquet 檔案中`varchar`的小數資料欄。重新編目資料並確定新的資料欄資料類型為 decimal 類型，或在 Athena 中手動重新建立資料表，然後使用語法 `decimal(precision, scale)` 指定資料欄的 [decimal](data-types.md#data-types-decimal) 資料類型。
#### Float 或 double NaN 值不能再轉換為 bigint
**錯誤訊息**：INVALID\$1CAST\$1ARGUMENT：無法將 real/double NaN 轉換為 bigint
**原因**：在 Athena 引擎版本 3 中，`NaN` 無法再以 `bigint` 的形式轉換為 0。
**建議的解決方案**：當您轉換為 `bigint` 時，請確保 `NaN` 值不存在於 `float` 或 `double` 資料欄。
#### uuid() 函數傳回類型變更
下列問題會影響資料表和檢視。
**錯誤訊息**：不支援的 Hive 類型：uuid
**原因**：在先前的引擎版本中，`uuid()` 函式傳回了一個字串，但在 Athena 引擎版本 3 中，它會傳回一個偽隨機產生的 UUID (類型 4)。由於 Athena 中不支援 UUID 資料欄資料類型，因此無法在 CTAS 查詢中直接使用 `uuid()` 函數，以在 Athena 引擎版本 3 中產生 UUID 資料欄。
例如，下列 `CREATE TABLE` 陳述式在先前的引擎版本中成功完成；但在 Athena 引擎版本 3 中，則會傳回 NOT\$1SUPPORTED：不支援的 Hive 類型：uuid：
```
CREATE TABLE uuid_table AS
SELECT uuid() AS myuuid
```
同樣地，下列 `CREATE VIEW` 陳述式在 Athena 引擎版本 2 中已成功完成；但在 Athena 引擎版本 3 中，則會傳回資料欄 myuuid 的資料欄類型無效：不支援的 Hive 類型：uuid：
```
CREATE VIEW uuid_view AS
SELECT uuid() AS myuuid
```
在 Athena 引擎版本 3 中查詢在先前的引擎版本中建立的檢視時，會發生類似下列情況的錯誤：
VIEW\$1IS\$1STALE：行 1:15:：檢視 'awsdatacatalog.mydatabase.uuid\$1view' 已過時或處於無效狀態：從位置 0 查詢檢視投影之 uuid 類型的資料欄 [myuuid] 無法強制轉換為儲存在檢視定義中的 varchar 類型的資料欄 [myuuid]
**建議的解決方案**：建立資料表或檢視時，請使用 `cast()` 函數將 `uuid()` 的輸出轉換為 `varchar`，如下列範例所示：
```
CREATE TABLE uuid_table AS
SELECT CAST(uuid() AS VARCHAR) AS myuuid
```
```
CREATE VIEW uuid_view AS
SELECT CAST(uuid() AS VARCHAR) AS myuuid
```
#### CHAR 和 VARCHAR 強制問題
如果您在 Athena 引擎版本 3 中遇到 `varchar` 和 `char` 強制問題，請使用本節的解決方法。如果您無法使用這些解決方法，請聯絡 支援。
##### 混合 CHAR 和 VARCHAR 輸入的 CONCAT 函數失敗
**問題**：Athena 引擎版本 2 會成功執行下列查詢。
```
SELECT concat(CAST('abc' AS VARCHAR(20)), '12', CAST('a' AS CHAR(1)))
```
但是，在 Athena 引擎版本 3 上，相同的查詢會失敗，並顯示下列情況：
**錯誤訊息**：FUNCTION\$1NOT\$1FOUND：行 1:8：函數 concat 的意外參數 (varchar(20), varchar(2), char(1))。預期：concat(char(x), char(y)), concat(array(E), E) E、concat(E, array(E)) E、concat(array(E)) E、concat(varchar)、concat(varbinary)
**建議的解決方案**：使用 `concat` 函數時`varchar`，可轉換為 `char` 或 ，但不能混合兩者。
##### SQL \$1\$1 CHAR 和 VARCHAR 輸入的串聯失敗
在 Athena 引擎版本 3 中，雙垂直長條圖 `||` 串聯操作員要求 `varchar` 做為輸入。輸入不能是 `varchar` 和 `char` 類型的組合。
**錯誤訊息**：TYPE\$1NOT\$1FOUND：行 1:26：未知類型：char(65537)
**原因**：使用 `||` 來串連 `char` 和 `varchar` 的查詢可能會產生錯誤，如下列範例所示。
```
SELECT CAST('a' AS CHAR) || CAST('b' AS VARCHAR)
```
**建議的解決方案**：串連 `varchar` 和 `varchar`，如下列範例所示。
```
SELECT CAST('a' AS VARCHAR) || CAST('b' AS VARCHAR)
```
##### CHAR 和 VARCHAR UNION 查詢失敗
**錯誤訊息**：NOT\$1SUPPORTED：不支援的 Hive 類型：char(65536)。支援的 CHAR 類型：CHAR(<=255)
**原因**：嘗試合併 `char` 和 `varchar` 的查詢，如下列範例所示：
```
CREATE TABLE t1 (c1) AS SELECT CAST('a' as CHAR) as c1 UNION ALL SELECT CAST('b' AS VARCHAR) AS c1
```
**建議的解決方案**：在範例查詢中，將 `'a'` 轉換為 `varchar` 而不是 `char`。
##### CHAR 或 VARCHAR 強制後不需要的空白空格
在 Athena 引擎版本 3 中，當 `char(X)` 和 `varchar` 資料在形成陣列或單一資料欄時強制轉換為單一類型，則 `char(65535)` 是目標類型，而且每個欄位都包含許多不需要的尾隨空格。
**原因**：Athena 引擎版本 3 強制將 `varchar` 和 `char(X)` 轉換為 `char(65535)`，然後右邊填補了空格的資料。
**建議的解決方案**：明確地將每個欄位轉換為 `varchar`。
### 時間戳記變更
#### 日期時間戳記溢出會擲出錯誤
**錯誤訊息**：Millis overflow: XXX (毫秒溢出：XXX)
**原因**：由於在先前的引擎版本中未檢查 ISO 8601 日期是否溢出，因此部分日期會產生負數時間戳記。Athena 引擎版本 3 會檢查此溢出，並擲出例外狀況。
**建議的解決方案**：確保時間戳記在範圍內。
#### 不支援具有 TIME 的政治時區
**錯誤訊息**：INVALID LITERAL (無效常值)
**原因**：如 `SELECT TIME '13:21:32.424 America/Los_Angeles'` 等查詢。
**建議的解決方案**：避免使用具有 `TIME` 的政治時區。
#### Timestamp 資料欄中的精確度不符會造成序列化錯誤
**錯誤訊息**：SERIALIZATION\$1ERROR: Could not serialize column '*COLUMNZ*' of type 'timestamp(3)' at position *X*:*Y* (SERIALIZATION\$1ERROR：無法在位置 X:Y 處序列化類型為 'timestamp(3)' 的資料欄 'COLUMNZ')
*COLUMNZ* 是造成該問題之資料欄的輸出名稱。數字 *X*:*Y* 表示資料欄在輸出中的位置。
**原因**：Athena 引擎版本 3 會執行檢查，以確保資料中時間戳記的精確度與資料表規格中資料欄資料類型指定的精確度相同。目前，此精確度一直是 3。如果資料的精確度大於此值，則查詢會失敗，且系統會指出錯誤。
**建議的解決方案**：檢查您的資料，以確保您的時間戳記為毫秒精確度。
#### Iceberg 表的 UNLOAD 和 CTAS 查詢中的時間戳記精度不正確
**錯誤訊息**：時間戳記 (6) 的時間戳記精確度不正確；設定的精確度為毫秒
**原因**：Athena 引擎版本 3 會執行檢查，以確保資料中時間戳記的精確度與資料表規格中資料欄資料類型指定的精確度相同。目前，此精確度一直是 3。如果資料的精確度大於此值 (例如以微秒而非毫秒)，則查詢會失敗且系統會指出錯誤。
**解決方案**：若要解決此問題，請先將時間戳記精確度 `CAST` 為 6，如下列建立 Iceberg 資料表的 CTAS 範例所示。請注意，必須將精確度指定為 6 而不是 3，以避免錯誤：Iceberg 不支援時間戳記精度 (3)。
```
CREATE TABLE my_iceberg_ctas
WITH (table_type = 'ICEBERG', location = 's3://amzn-s3-demo-bucket/table_ctas/',
format = 'PARQUET')
AS SELECT id, CAST(dt AS timestamp(6)) AS "dt"
FROM my_iceberg
```
然後，由於 Athena 不支援時間戳記 6，因此請將值再次轉換為時間戳記 (例如，在檢視中)。下列範例從 `my_iceberg_ctas` 資料表建立檢視。
```
CREATE OR REPLACE VIEW my_iceberg_ctas_view AS
SELECT cast(dt AS timestamp) AS dt
FROM my_iceberg_ctas
```
#### 現在，將 ORC 檔案中的 Long 類型讀取為 Timestamp 會造成不正確的 ORC 檔案錯誤，反之亦然
**錯誤訊息**：Error opening Hive split ‘FILE (SPLIT POSITION)’ Malformed ORC file. (開啟 Hive 分割 ‘FILE (SPLIT POSITION)’ 格式不正確的 ORC 檔案時發生錯誤。) Cannot read SQL type timestamp from ORC stream .long\$1type of type LONG (開啟 Hive 分割 ‘FILE (SPLIT POSITION)’ 不正確的 ORC 檔案時發生錯誤。無法從 LONG 類型的 ORC 串流 .long\$1type 讀取 SQL 類型的時間戳記)
**原因**：Athena 引擎版本 3 現在會拒絕從 `Long` 資料類型隱含強制轉換至 `Timestamp`，或從 `Timestamp` 轉換至 `Long`。過去，若 `Long` 值為 epoch 毫秒，便會被隱含強制轉換為時間戳記。
**建議的解決方案**：使用 `from_unixtime` 函數來明確轉換資料欄，或者使用 `from_unixtime` 函數為以後的查詢建立一個額外的資料欄。
#### 不支援 time 和 interval year to month
**錯誤訊息**：TYPE MISMATCH (類型不相符)
**原因**：Athena 引擎版本 3 不支援 time 和 interval year to month (例如 `SELECT TIME '01:00' + INTERVAL '3' MONTH`)。
#### Int96 Parquet 格式的時間戳記溢出
**錯誤訊息**：Invalid timeOfDayNanos (無效的 timeOfDayNanos)
**原因**：`int96` Parquet 格式的時間戳記溢出。
**建議的解決方案**：辨識發生問題的特定檔案。然後使用最新且知名的 Parquet 程式庫再次產生資料檔案，或使用 Athena CTAS。如果問題仍持續發生，請聯絡 Athena 支援，並告知我們產生資料檔案的方法。
#### 從字串轉換為時間戳記時，日期和時間值之間需要的空格
**錯誤訊息**：INVALID\$1CAST\$1ARGUMENT：值無法轉換為時間戳記。
**原因**：Athena 引擎版本 3 不再接受連字號做為輸入字串中日期和時間值之間的有效分隔符。`cast`例如，下列查詢在 Athena 引擎版本 3 中無法運作：
```
SELECT CAST('2021-06-06-23:38:46' AS timestamp) AS this_time
```
**建議的解決方案**：在 Athena 引擎版本 3 中，將日期與時間之間的連字號取代為空格，如下列範例所示。
```
SELECT CAST('2021-06-06 23:38:46' AS timestamp) AS this_time
```
#### to\$1iso8601() 時間戳記傳回值變更
**錯誤訊息**：無
**原因**：在先前的引擎版本中，即使傳遞給 `to_iso8601` 函式的值不包含時區，該函式也會傳回帶有時區的時間戳記。在 Athena 引擎版本 3 中，只有當傳遞的引數包含時區時，`to_iso8601` 函數才會傳回時間戳記與時區。
例如，下列查詢會將目前日期傳遞給 `to_iso8601` 函數兩次：首先是做為具有時區的時間戳記，然後是做為時間戳記。
```
SELECT TO_ISO8601(CAST(CURRENT_DATE AS TIMESTAMP WITH TIME ZONE)), TO_ISO8601(CAST(CURRENT_DATE AS TIMESTAMP))
```
下列輸出會顯示 Athena 引擎版本 3 中的查詢結果。
在先前的引擎版本中：
****
| \$1 | \$1col0 | \$1col1 |
| --- | --- | --- |
| 1 | `2023-02-24T00:00:00.000Z ` | `2023-02-24T00:00:00.000Z` |
Athena 引擎版本 3：
****
| \$1 | \$1col0 | \$1col1 |
| --- | --- | --- |
| 1 | `2023-02-24T00:00:00.000Z` | `2023-02-24T00:00:00.000` |
**建議的解決方案**：要複製先前的行為，您可以先將時間戳記值傳遞至 `with_timezone` 函數，然後再將其傳遞給 `to_iso8601`，如下列範例所示：
```
SELECT to_iso8601(with_timezone(TIMESTAMP '2023-01-01 00:00:00.000', 'UTC'))
```
結果
****
| \$1 | \$1col0 |
| --- | --- |
| 1 | 2023-01-01T00:00:00.000Z |
#### at\$1timezone() 第一個參數必須指定一個日期
**問題**：在 Athena 引擎版本 3 中，`at_timezone` 函數無法將 `time_with_timezone` 值做為第一個參數。
**原因**：如果沒有日期資訊，則無法判斷傳遞的值是夏令時間還是標準時間。例如，`at_timezone('12:00:00 UTC', 'America/Los_Angeles')` 並不明確，因為無法判斷傳遞的值是太平洋夏令時間 (PDT) 還是太平洋標準時間 (PST)。
## 限制
Athena 引擎版本 3 有以下限制。
+ **查詢效能** – 許多查詢在 Athena 引擎版本 3 上的執行速度更快，但部分查詢計畫可能與先前的引擎版本不同。因此，部分查詢的延遲或成本可能有所不同。
+ **Trino 和 Presto 連接器** – 不支援 [Trino](https://trino.io/docs/current/connector.html) 和 [Presto](https://prestodb.io/docs/current/connector.html) 連接器。使用 Amazon Athena 聯合查詢來連接資料來源。如需詳細資訊，請參閱[使用 Amazon Athena 聯合查詢](federated-queries.md)。
+ **容錯執行** – 不支援 Trino [容錯執行](https://trino.io/docs/current/admin/fault-tolerant-execution.html) (Trino Tardigrade)。
+ **函數參數限制** – 函數使用的參數不能超過 127 個。如需詳細資訊，請參閱[函數呼叫的引數過多](troubleshooting-athena.md#troubleshooting-athena-too-many-arguments)。
Athena 引擎版本 2 中引入了下列限制，以確保查詢不會因資源限制而失敗。使用者無法設定這些限制。
+ **結果元素的數量** – 下列函數的結果元素 `n` 的數量限制為 10,000 或更少：`min(col, n)`、`max(col, n)`、`min_by(col1, col2, n)` 以及 `max_by(col1, col2, n)`。
+ **GROUPING SETS** – 分組集中的配量數目上限為 2048。
+ **文字檔案一行長度上限** – 文字檔案預設的一行長度上限為 200 MB。
+ **序列函數結果大小上限** – 序列函數的結果大小上限為 50,000 個項目。例如：`SELECT sequence(0,45000,1)` 成功，但 `SELECT sequence(0,55000,1)` 失敗並顯示錯誤訊息 The result of the sequence function must not have more than 50000 entries (序列函數的結果不能有 50,000 個以上項目)。此限制適用於序列函數 (包括時間戳記) 的所有輸入類型。
# Athena 的 SQL 參考
Amazon Athena 支援一部分的資料定義語言 (DDL) 和資料處理語言 (DML) 陳述式、函數、運算子和資料類型。在某些例外中，Athena DDL 是以 [HiveQL DDL](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+DDL) 為基礎，而 Athena DML 是以 [Trino](https://trino.io/docs/current/language.html) 為基礎。如需有關 Athena 引擎版本的資訊，請參閱[Athena 引擎版本控制](engine-versions.md)。
**Topics**
+ [Athena 中的資料類型](data-types.md)
+ [DML 查詢、函數和運算子](dml-queries-functions-operators.md)
+ [DDL 陳述式](ddl-reference.md)
+ [考量和限制](other-notable-limitations.md)
# Amazon Athena 中的資料類型
當您執行 `CREATE TABLE` 時，您需指定資料欄名稱和每個資料欄可包含的資料類型。您建立的資料表會存放在 AWS Glue Data Catalog中。
為了促進與其他查詢引擎的互通性，Athena 會對 DDL 陳述式 (例如 `CREATE TABLE`) 使用 [Apache Hive](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Types) 資料類型名稱。對於 `SELECT`、`CTAS` 和 `INSERT INTO` 等 DML 查詢，Athena 會使用 [Trino](https://trino.io/docs/current/language/types.html) 資料類型名稱。下列資料表會顯示 Athena 支援的資料類型。當 DDL 和 DML 類型在名稱、可用性或語法等方面有所不同時，它們會顯示在不同的資料欄中。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/data-types.html)
**Topics**
+ [資料類型範例](data-types-examples.md)
+ [資料類型的考量事項](data-types-considerations.md)
+ [使用時間戳記資料](data-types-timestamps.md)
# 資料類型範例
下列資料表會顯示 DML 資料類型的範例常值。
****
| 資料類型 | 範例 |
| --- | --- |
| BOOLEAN | `true` `false ` |
| TINYINT | `TINYINT '123'` |
| SMALLINT | `SMALLINT '123'` |
| INT、INTEGER | `123456790` |
| BIGINT | `BIGINT '1234567890'` `2147483648` |
| REAL | `'123456.78'` |
| DOUBLE | `1.234` |
| DECIMAL(precision, scale) | `DECIMAL '123.456'` |
| CHAR, CHAR(length) | `CHAR 'hello world'`, `CHAR 'hello ''world''!'` |
| VARCHAR, VARCHAR(length) | `VARCHAR 'hello world'`, `VARCHAR 'hello ''world''!'` |
| VARBINARY | `X'00 01 02'` |
| TIME, TIME(precision) | `TIME '10:11:12'`, `TIME '10:11:12.345'` |
| TIME WITH TIME ZONE | `TIME '10:11:12.345 -06:00'` |
| DATE | `DATE '2024-03-25'` |
| TIMESTAMP, TIMESTAMP WITHOUT TIME ZONE, TIMESTAMP(*precision*), TIMESTAMP(*precision*) WITHOUT TIME ZONE | `TIMESTAMP '2024-03-25 11:12:13'`, `TIMESTAMP '2024-03-25 11:12:13.456'` |
| TIMESTAMP WITH TIME ZONE, TIMESTAMP(precision) WITH TIME ZONE | `TIMESTAMP '2024-03-25 11:12:13.456 Europe/Berlin'` |
| INTERVAL YEAR TO MONTH | `INTERVAL '3' MONTH` |
| INTERVAL DAY TO SECOND | `INTERVAL '2' DAY` |
| ARRAY[element\$1type] | `ARRAY['one', 'two', 'three']` |
| MAP(key\$1type, value\$1type) | `MAP(ARRAY['one', 'two', 'three'], ARRAY[1, 2, 3])` 請注意，映射是從索引鍵陣列和值陣列建立的。下列範例會建立將字串映射為整數的資料表。 CREATE TABLE map_table(col1 map) LOCATION '...';
INSERT INTO map_table values(MAP(ARRAY['foo', 'bar'], ARRAY[1, 2]));
|
| ROW(field\$1name\$11 field\$1type\$11, field\$1name\$12 field\$1type\$12, …) | `ROW('one', 'two', 'three')` 請注意，以這種方式建立的資料列沒有資料欄名稱。若要新增資料欄名稱，可以使用 `CAST`，如下列範例所示： CAST(ROW(1, 2, 3) AS ROW(one INT, two INT, three INT))
|
| JSON | `JSON '{"one":1, "two": 2, "three": 3}'` |
| UUID | `UUID '12345678-90ab-cdef-1234-567890abcdef'` |
| IPADDRESS | `IPADDRESS '10.0.0.1'` `IPADDRESS '2001:db8::1'` |
# 資料類型的考量事項
## 大小限制
對於未指定大小限制的資料類型，請記住，單一資料列中所有資料的實際限制為 32MB。如需詳細資訊，請參閱 [在 Amazon Athena 中進行 SQL 查詢的考量事項與限制](other-notable-limitations.md) 中的 [Row or column size limitation](other-notable-limitations.md#sql-limitations-rowsize)。
## CHAR 和 VARCHAR
`CHAR(n)` 值的計數一律為 `n` 個字元。例如，如果您將 'abc' 轉換為 `CHAR(7)`，則會新增 4 個尾隨空格。
`CHAR` 值的比較包括前導和尾隨空格。
如果為 `CHAR` 或 `VARCHAR` 指定，讀取字串時，會以指定的長度進行截斷。如果基礎資料字串較長，則基礎資料字串會維持不變。
若要逸出 `CHAR` 或 `VARCHAR` 中的單引號，請使用額外的單引號。
若要將非字串資料類型轉換為 DML 查詢中的字串，請轉換為 `VARCHAR` 資料類型。
若要使用 `substr` 函式從 `CHAR` 資料類型傳回指定長度的子字串，您必須先將 `CHAR` 值轉換為 `VARCHAR`。在下列範例中，`col1` 使用 `CHAR` 資料類型。
```
substr(CAST(col1 AS VARCHAR), 1, 4)
```
## DECIMAL
若要在 `SELECT` 查詢中指定小數值為常值，例如以特定小數值選取資料列，可指定 `DECIMAL` 類型，並在查詢中以單引號列出小數值為常值，如下列範例所示。
```
SELECT * FROM my_table
WHERE decimal_value = DECIMAL '0.12'
```
```
SELECT DECIMAL '44.6' + DECIMAL '77.2'
```
# 使用時間戳記資料
本節說明在 Athena 中使用時間戳記資料的一些考量。
**注意**
先前的引擎版本與 Athena 引擎版本 3 之間的時間戳記處理方式發生變更。如需有關 Athena 引擎版本 3 中可能發生的時間戳記相關錯誤及建議的解決方案的資訊，請參閱 [Athena 引擎版本 3](engine-versions-reference-0003.md) 參考中的 [時間戳記變更](engine-versions-reference-0003.md#engine-versions-reference-0003-timestamp-changes)。
## 將時間戳記資料寫入 Amazon S3 物件的格式
將時間戳記資料寫入 Amazon S3 物件的格式，取決於您使用的資料欄資料類型和 [SerDe 程式庫](https://docs.aws.amazon.com/athena/latest/ug/supported-serdes.html)。
+ 如果您有類型為 `DATE` 的資料表資料欄，Athena 會預期資料的對應資料欄或屬性是 ISO 格式的字串 `YYYY-MM-DD`，或是內建的日期類型 (例如 Parquet 或 ORC 的日期類型)。
+ 如果您有類型為 `TIME` 的資料表資料欄，Athena 會預期資料的對應資料欄或屬性是 ISO 格式的字串 `HH:MM:SS`，或是內建的時間類型 (例如 Parquet 或 ORC 的時間類型)。
+ 如果您有類型為 `TIMESTAMP` 的資料表資料欄，Athena 會預期資料的對應資料欄或屬性是格式的字串 `YYYY-MM-DD HH:MM:SS.SSS` (注意日期和時間之間的空格)，或是內建的時間類型 (例如 Parquet、ORC 或 Ion 的時間類型)。請注意，Athena 不保證對無效時間戳記的行為 （例如 `0000-00-00 08:00:00.000`)。
**注意**
OpenCSVSerDe 時間戳記是例外狀況，且必須編碼為毫秒解析度的 UNIX epochs。
## 確保時間分割資料符合記錄中的時間戳記欄位
資料的產生者必須確定分割區值與分割區內的資料一致。例如，如果您的資料具有 `timestamp` 屬性，而您使用 Firehose 將資料載入 Amazon S3，則必須使用[動態分割](https://docs.aws.amazon.com/firehose/latest/dev/dynamic-partitioning.html)，因為 Firehose 的預設分割以掛鐘為基礎的。
## 使用字串做為分割區索引鍵的資料類型
出於效能考量，最好將 `STRING` 用作分割區索引鍵的資料類型。雖然 Athena 將格式 `YYYY-MM-DD` 的分割區值識別為您使用 `DATE` 類型時的日期，而這可能造成效能不彰。因此，我們建議您改用 `STRING` 資料類型做為分割區索引鍵。
## 如何寫入同樣按時間分割的時間戳記欄位的查詢
如何寫入同樣按時間分割的時間戳記欄位的查詢，取決於您要查詢的資料表的類型。
### Hive 資料表
使用 Athena 中最常用的 Hive 資料表，查詢引擎對資料欄和分割區索引鍵之間的關係一無所知。因此，您必須始終在資料欄和分割區索引鍵的查詢中新增述詞。
例如，假設您有 `event_time` 資料欄和 `event_date` 分割區索引鍵，而且想要查詢 23:00 到 03:00 之間的事件。在此案例中，您必須在查詢資料欄和分割區索引鍵中包含述詞，如下列範例所示。
```
WHERE event_time BETWEEN start_time AND end_time
AND event_date BETWEEN start_time_date AND end_time_date
```
### Iceberg 資料表
使用 Iceberg 資料表，您可以使用運算的分割區值，從而簡化查詢。例如，假設您的 Iceberg 資料表是使用如下 `PARTITIONED BY` 子句建立的：
```
PARTITIONED BY (event_date month(event_time))
```
在此案例下，查詢引擎會根據 `event_time` 述詞的值自動剔除分割區。因此，您的查詢只需要指定 `event_time` 的述詞，如下列範例所示。
```
WHERE event_time BETWEEN start_time AND end_time
```
如需詳細資訊，請參閱[建立 Iceberg 資料表](querying-iceberg-creating-tables.md)。
對時間戳記資料欄使用 Iceberg 的隱藏分割時，Iceberg 可能會在衍生自時間戳記資料欄的建構資料表資料欄上建立分割區，並將其轉換為日期，以實現更有效的分割。例如，它可能會從時間戳記資料欄 `event_time` 建立 `event_date`，並在 `event_date` 上自動進行分割。在這種情況下，分割區**類型**是**日期**。
為了在使用分割區時獲得最佳查詢效能，請篩選全天範圍以啟用述詞下推。例如，下列查詢不會下推，因為範圍無法轉換為單一日期分割區，即使其恰到落在一天內：
```
WHERE event_time >= TIMESTAMP '2024-04-18 00:00:00' AND event_time < TIMESTAMP '2024-04-18 12:00:00'
```
相反地，請使用全天範圍來允許述詞下推，並提升查詢效能，如下列範例所示。
```
WHERE event_time >= TIMESTAMP '2024-04-18 00:00:00' AND event_time < TIMESTAMP '2024-04-19 00:00:00'
```
您也可以使用 `BETWEEN start_time AND end_time` 語法或使用多日範圍，只要時間戳記部分為 `00:00:00` 即可。
如需詳細資訊，請參閱 [Trino 部落格文章](https://trino.io/blog/2023/04/11/date-predicates.html)。
# DML 查詢、函數和運算子
Athena DML 查詢引擎通常支援 Trino 和 Presto 語法，並且自行對其進行了改進。Athena 不支援 Trino 或 Presto 的所有功能。如需詳細資訊，請參閱本節中特定陳述式的主題以及[考量和限制](other-notable-limitations.md)。如需有關函數資訊，請參閱 [Amazon Athena 中的函數](functions.md)。如需有關 Athena 引擎版本的資訊，請參閱[Athena 引擎版本控制](engine-versions.md)。
如需 DDL 陳述式的資訊，請參閱[DDL 陳述式](ddl-reference.md)。如需不支援的 DDL 陳述式之清單，請參閱[不支援的 DDL](unsupported-ddl.md)。
**Topics**
+ [SELECT](select.md)
+ [INSERT INTO](insert-into.md)
+ [VALUES](values-statement.md)
+ [DELETE](delete-statement.md)
+ [UPDATE](update-statement.md)
+ [合併為](merge-into-statement.md)
+ [OPTIMIZE](optimize-statement.md)
+ [VACUUM](vacuum-statement.md)
+ [EXPLAIN 和 EXPLAIN ANALYZE](athena-explain-statement.md)
+ [PREPARE](sql-prepare.md)
+ [UNLOAD](unload.md)
+ [函數](functions.md)
+ [使用支援的時區](athena-supported-time-zones.md)
# SELECT
從零個或多個資料表中擷取資料列。
**注意**
本主題提供摘要資訊以供參考。關於使用 `SELECT` 和 SQL 語言的完整資訊已超出本文件的範圍。如需有關使用 Athena 特定 SQL 的資訊，請參閱[在 Amazon Athena 中進行 SQL 查詢的考量事項與限制](other-notable-limitations.md)和[在 Amazon Athena 中執行 SQL 查詢](querying-athena-tables.md)。如需在 Athena 建立資料庫、建立資料表和執行資料表 `SELECT` 查詢的範例，請參閱 [開始使用](getting-started.md)。
## 概要
```
[ WITH with_query [, ...] ]
SELECT [ ALL | DISTINCT ] select_expression [, ...]
[ FROM from_item [, ...] ]
[ WHERE condition ]
[ GROUP BY [ ALL | DISTINCT ] grouping_element [, ...] ]
[ HAVING condition ]
[ { UNION | INTERSECT | EXCEPT } [ ALL | DISTINCT ] select ]
[ ORDER BY expression [ ASC | DESC ] [ NULLS FIRST | NULLS LAST] [, ...] ]
[ OFFSET count [ ROW | ROWS ] ]
[ LIMIT [ count | ALL ] ]
```
**注意**
SQL SELECT 陳述式中的保留字必須以雙引號括住。如需詳細資訊，請參閱[SQL SELECT 陳述式中要逸出的預留關鍵字](reserved-words.md#list-of-reserved-words-sql-select)。
## Parameters
**[ WITH with\$1query [, ....] ]**
您可以使用 `WITH` 來展開巢狀查詢，或簡化子查詢。
Athena 引擎版本 3 開始支援使用 `WITH` 子句建立遞迴查詢。最大遞歸深度為 10。
`WITH` 子句位於查詢中的 `SELECT` 清單前面，可定義一或多個子查詢以用於 `SELECT` 查詢內。
每個子查詢定義臨時資料表，類似於檢視定義，供您在 `FROM` 子句中參考。這些資料表只在查詢執行時才使用。
`with_query` 語法是：
```
subquery_table_name [ ( column_name [, ...] ) ] AS (subquery)
```
其中：
+ `subquery_table_name` 是臨時資料表的唯一名稱，定義 `WITH` 子句子查詢的結果。每個 `subquery` 必須有可在 `FROM` 子句中參考的資料表名稱。
+ `column_name [, ...]` 是選用的輸出欄名稱清單。欄名稱的數目必須等於或少於 `subquery` 所定義的欄數。
+ `subquery` 是任何查詢陳述式。
**[ ALL \$1 DISTINCT ] select\$1expression**
`select_expression` 決定要選取的列。`select_expression` 可以使用下列其中一個格式：
```
expression [ [ AS ] column_alias ] [, ...]
```
```
row_expression.* [ AS ( column_alias [, ...] ) ]
```
```
relation.*
```
```
*
```
+ `expression [ [ AS ] column_alias ]` 語法會指定輸出資料欄。選用的 `[AS] column_alias` 語法會指定要用於輸出中資料欄的自訂標題名稱。
+ 對於 `row_expression.* [ AS ( column_alias [, ...] ) ]`，`row_expression` 是資料類型 `ROW` 的任意表達式。資料列的欄位會定義要包含在結果中的輸出資料欄。
+ 對於 `relation.*`，`relation` 的資料欄會包含在結果中。此語法不允許使用資料欄別名。
+ 星號 `*` 會指定所有資料欄都會包含在結果集中。
+ 在結果集中，資料欄的順序與 select 表達式所指定的資料欄規範順序相同。如果 select 表達式傳回多個資料欄，則資料欄順序會遵循來源關係或資料列類型表達式中使用的順序。
+ 指定資料欄別名時，別名會覆寫預先存在的資料欄或資料列欄位名稱。如果 select 表達式沒有資料欄名稱，則輸出中會顯示零索引的匿名資料欄名稱 (`_col0`、`_col1`、`_col2, ...`)。
+ 預設值為 `ALL`。`ALL` 使用與省略不用都一樣；所有欄的所有列都會選取，重複的列也會保留。
+ 當欄包含重複值時，可使用 `DISTINCT` 只傳回獨特值。
**FROM from\$1item [, ...]**
指出查詢的輸入，其中 `from_item` 可以是檢視、聯結建構或子查詢，如下所示。
`from_item` 可以是以下任一項：
+ `table_name [ [ AS ] alias [ (column_alias [, ...]) ] ]`
其中，`table_name` 是從中選取列的目標表格的名稱，`alias` 是提供給 `SELECT` 陳述式輸出的名稱，`column_alias` 為指定的 `alias` 定義欄。
**-或-**
+ `join_type from_item [ ON join_condition | USING ( join_column [, ...] ) ]`
其中 `join_type` 是以下其中一個：
+ `[ INNER ] JOIN`
+ `LEFT [ OUTER ] JOIN`
+ `RIGHT [ OUTER ] JOIN`
+ `FULL [ OUTER ] JOIN`
+ `CROSS JOIN`
+ `ON join_condition | USING (join_column [, ...])` 其中，使用 `join_condition` 可讓您指定多個資料表中聯結索引鍵的欄名稱，而使用 `join_column` 之前，兩個資料表中必須都有 `join_column`。
**[ WHERE condition ]**
根據您指定的 `condition` 篩選結果，其中 `condition` 通常具有以下語法。
```
column_name operator value [[[AND | OR] column_name operator value] ...]
```
*operator* 可以是其中一個比較子：`=`、`>`、`<`、`>=`、`<=`、`<>`、`!=`。
下面的子查詢表達式也可以用在 `WHERE` 子句中。
+ `[NOT] BETWEEN integer_A AND integer_B` – 指定兩個整數之間的範圍，如下列範例所示。如果資料欄資料類型是 `varchar`，則必須先將資料欄轉換為整數。
```
SELECT DISTINCT processid FROM "webdata"."impressions"
WHERE cast(processid as int) BETWEEN 1500 and 1800
ORDER BY processid
```
+ `[NOT] LIKE value` – 搜尋指定的模式。使用百分比符號 (`%`) 作為萬用字元，如下列範例所示。
```
SELECT * FROM "webdata"."impressions"
WHERE referrer LIKE '%.org'
```
+ `[NOT] IN (value[, value[, ...])` – 指定資料欄可能的值之清單，如下列範例所示。
```
SELECT * FROM "webdata"."impressions"
WHERE referrer IN ('example.com','example.net','example.org')
```
**[ GROUP BY [ ALL \$1 DISTINCT ] grouping\$1expressions [, ...] ]**
將 `SELECT` 陳述式的輸出分割成具有相符值的列。
`ALL` 和 `DISTINCT` 指定重複的分組集是否各產生相異的輸出列。如果省略，會採用 `ALL`。
`grouping_expressions` 可讓您執行複雜的分組操作。您可以使用複雜的分組操作來執行需要對單一查詢中的多組資料欄進行彙總的分析。
`grouping_expressions` 元素可以是任何函數，例如對輸入資料欄執行的 `SUM`、`AVG` 或 `COUNT`。
`GROUP BY` 表達式可依未出現在 `SELECT` 陳述式輸出中的輸入欄名稱，將輸出分組。
所有輸出表達式必須是彙總函數，或存在於 `GROUP BY` 子句中的欄。
您可以使用單一查詢來執行需要彙總多個欄集的分析。
Athena 支援使用 `GROUPING SETS`、`CUBE` 和 `ROLLUP` 的複雜彙總。`GROUP BY GROUPING SETS` 指定要分組的多個資料欄清單。`GROUP BY CUBE` 會針對一組給定的資料欄，產生所有可能的分組集。`GROUP BY ROLLUP` 會針對一組給定的資料欄，產生所有可能的小計。複雜的分組操作不支援對由輸入資料欄組成的表達式進行分組。只允許資料欄名稱。
您通常可以使用 `UNION ALL` 來達到與這些 `GROUP BY` 操作相同的結果，但使用 `GROUP BY` 的查詢好處是只讀取資料一次，而 `UNION ALL` 會讀取基礎資料三次，而且當資料來源易於變更時，可能會產生不一致的結果。
**[ HAVING condition ]**
與彙總函數和 `GROUP BY` 子句一起使用。控制要選取哪些群組，排除不符合 `condition` 的群組。計算群組和彙總之後會執行此篩選。
**[ \$1 UNION \$1 INTERSECT \$1 EXCEPT \$1 [ ALL \$1 DISTINCT ] union\$1query] ]**
`UNION`、`INTERSECT` 和 `EXCEPT` 將一個以上的 `SELECT` 陳述式的結果結合為單一查詢。`ALL` 或 `DISTINCT` 控制最終結果集包含的資料行的唯一性。
`UNION` 將第一個查詢產生的資料行與第二個查詢產生的資料行組合起來。為消除重複項，`UNION` 構建了一個消耗記憶體的雜湊資料表。為了更好的性能，如果您的查詢不需要消除重複項，則請考慮使用 `UNION ALL`。除非您使用括號來明確定義處理順序，否則多個 `UNION` 子句是由左向右處理。
`INTERSECT` 只傳回存在於第一個和第二個查詢之結果中的資料行。
`EXCEPT` 傳回第一個查詢之結果的資料行，不包括第二個查詢找到的資料行。
`ALL` 會包含所有資料行，即使資料行都相同也一樣。
`DISTINCT` 只會讓唯一的資料行包含在合併結果集中。
**[ ORDER BY expression [ ASC \$1 DESC ] [ NULLS FIRST \$1 NULLS LAST] [, ...] ]**
依一或多個輸出 `expression` 排序結果集。
當子句包含多個表達式時，結果集會根據第一個 `expression` 排序。然後，第二個 `expression` 套用的列有來自第一個表達式的相符值，以此類推。
每個 `expression` 可以指定 `SELECT` 的輸出欄，或依位置指定輸出欄的序數 (從 1 開始)。
`ORDER BY` 是在任何 `GROUP BY` 或 `HAVING` 子句之後當作最後一個步驟來評估。`ASC` 和 `DESC` 決定結果依遞增或遞減順序來排序。依預設，排序順序為遞增排序 (`ASC`)。無論是遞增或遞減排序，預設空值排序是 `NULLS LAST`。
**[ OFFSET count [ ROW \$1 ROWS ] ]**
使用 `OFFSET` 子句來捨棄結果集中的數個前導列。如果 `ORDER BY` 子句存在時，`OFFSET` 子句會根據排序的結果集進行評估，並且該集會在跳過的資料列遭到捨棄後保持排序。如果查詢沒有 `ORDER BY` 子句，則可以任意捨棄資料列。如果 `OFFSET` 指定的計數等於或超過結果集的大小，則最終結果為空白。
**LIMIT [ count \$1 ALL ]**
將結果集的列數限制為 `count`。`LIMIT ALL` 和省略 `LIMIT` 子句的效果相同。如果查詢沒有 `ORDER BY` 子句，則結果是任意順序。
**TABLESAMPLE [ BERNOULLI \$1 SYSTEM ] (percentage)**
根據取樣方法從資料表中選擇列的選用運算子。
`BERNOULLI` 以機率 `percentage` 選取要放入資料表樣本中的每一列。將會掃描資料表的所有實體區塊，並根據範本 `percentage` 和執行時間計算的隨機值之間的比較，略過特定的資料行。
使用 `SYSTEM` 時，資料表會分割為邏輯的資料區段，並以此精細程式來取樣資料表。
將會選取特定區段的所有資料行，或根據取樣 `percentage` 和執行時間計算的隨機值之間的比較，略過區段。`SYSTEM` 取樣依賴連接器。這個方法不保證獨立取樣機率。
**[ UNNEST (array\$1or\$1map) [WITH ORDINALITY] ]**
將陣列或映射展開成關係。陣列會展開成單一欄。映射會展開成兩欄 (*索引鍵*、*值*)。
您可以使用 `UNNEST` 搭配多個參數，以展開成多個欄，且列數與最高基數引數相等。
其他欄以空值填補。
`WITH ORDINALITY` 子句會將基數欄新增至尾端。
`UNNEST` 通常與 `JOIN` 一起使用，且可以參考 `JOIN` 左側關係中的欄。
## 在 Amazon S3 中取得來源資料的檔案位置
若要查看資料表資料行中資料的 Amazon S3 檔案位置，可以使用 `SELECT` 查詢中的 `"$path"`，如下列範例所示：
```
SELECT "$path" FROM "my_database"."my_table" WHERE year=2019;
```
此舉會傳回如下所示的結果：
```
s3://amzn-s3-demo-bucket/datasets_mytable/year=2019/data_file1.json
```
若要傳回資料表中資料的 S3 檔案名稱路徑經排序的單一清單，可以使用 `SELECT DISTINCT` 和 `ORDER BY`，如下範例所示。
```
SELECT DISTINCT "$path" AS data_source_file
FROM sampledb.elb_logs
ORDER By data_source_file ASC
```
若要僅傳回沒有路徑的檔案名稱，則可將 `"$path"` 作為參數傳遞給 `regexp_extract` 函數，如下列範例所示。
```
SELECT DISTINCT regexp_extract("$path", '[^/]+$') AS data_source_file
FROM sampledb.elb_logs
ORDER By data_source_file ASC
```
若要從特定檔案傳回資料，請在 `WHERE` 子句中指定檔案，如下列範例所示。
```
SELECT *,"$path" FROM my_database.my_table WHERE "$path" = 's3://amzn-s3-demo-bucket/my_table/my_partition/file-01.csv'
```
如需詳細資訊和範例，請參閱知識中心文章：[如何查看 Athena 資料表中某資料行的 Amazon S3 來源檔案？](https://aws.amazon.com/premiumsupport/knowledge-center/find-s3-source-file-athena-table-row/)。
**注意**
在 Athena 中，檢視不支援 Hive 或 Iceberg 隱藏的中繼資料欄 `$bucket`、`$file_modified_time`、`$file_size` 和 `$partition`。
## 逸出單引號
若要逸出單引號，請在它前面加上另一個單引號，如下列範例所示。請勿將此與雙引號混淆。
```
Select 'O''Reilly'
```
**結果**
`O'Reilly`
## 其他資源
如需有關使用 Athena 中 `SELECT` 陳述式的詳細資訊，請參閱以下資源。
| 如需有關以下內容的資訊 | 參閱以下資源 |
| --- | --- |
| 在 Athena 中執行查詢 | [在 Amazon Athena 中執行 SQL 查詢](querying-athena-tables.md) |
| 使用 SELECT 建立資料表 | [從查詢結果建立資料表 (CTAS)](ctas.md) |
| 將一個 SELECT 查詢的資料插入其他資料表 | [INSERT INTO](insert-into.md) |
| 使用 SELECT 陳述式中內建的函數 | [Amazon Athena 中的函數](functions.md) |
| 使用 SELECT 陳述式中使用者定義函數 | [利用使用者定義函式進行查詢](querying-udf.md) |
| 查詢資料目錄中繼資料 | [查詢 AWS Glue Data Catalog](querying-glue-catalog.md) |
# INSERT INTO
根據來源資料表上執行的 `SELECT` 查詢陳述式，或根據作為該陳述式的一部分提供的一組 `VALUES`，將新資料行插入目標資料表。當來源資料表以某一格式 (例如 CSV 或 JSON) 的基礎資料為基礎時，而目標資料表以另一種格式 (例如 Parquet 或 ORC) 為基礎，則您可以使用 `INSERT INTO` 查詢，將選取的資料轉換為目標資料表的格式。
## 考量和限制
搭配 Athena 使用 `INSERT` 查詢時，請考慮以下情況：
+ 在包含於 Amazon S3 中加密的基礎資料的資料表上執行 `INSERT` 查詢時，`INSERT` 查詢寫入的輸出檔案依預設不會加密。如果您要插入具有加密資料的資料表，建議您加密 `INSERT` 查詢結果。
如需使用主控台加密查詢結果的詳細資訊，請參閱[加密 Amazon S3 中存放的 Athena 查詢結果](encrypting-query-results-stored-in-s3.md)。若要使用 AWS CLI 或 Athena API 啟用加密，請使用 [StartQueryExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartQueryExecution.html) 動作的`EncryptionConfiguration`屬性，根據您的需求指定 Amazon S3 加密選項。
+ 對於 `INSERT INTO` 陳述式，預期的儲存貯體擁有者設定不適用於 Amazon S3 中的目的地資料表位置。預期的儲存貯體擁有者設定僅適用於您為 Athena 查詢結果指定的 Amazon S3 輸出位置。如需詳細資訊，請參閱[使用 Athena 主控台指定查詢結果位置](query-results-specify-location-console.md)。
+ 如需 ACID 合規 `INSERT INTO` 陳述式，則請參閱 [更新 Iceberg 資料表資料](querying-iceberg-updating-iceberg-table-data.md) 的 `INSERT INTO` 一節。
### 支援的格式和 SerDes
您可以在使用下列格式和 SerDes 資料建立的資料表上，執行 `INSERT` 查詢。
| 資料格式 | SerDe |
| --- | --- |
| Avro | org.apache.hadoop.hive.serde2.avro.AvroSerDe |
| Ion | com.amazon.ionhiveserde.IonHiveSerDe |
| JSON | org.apache.hive.hcatalog.data.JsonSerDe |
| ORC | org.apache.hadoop.hive.ql.io.orc.OrcSerde |
| Parquet | org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe |
| 文字檔案 | org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe 支援 TSV 和自訂分隔檔案。 |
| CSV | org.apache.hadoop.hive.serde2.OpenCSVSerde 僅字串類型支援寫入。在 Athena 中，您無法寫入 Glue 結構描述中包含非字串類型的任何資料表。如需詳細資訊，請參閱 [CSV SerDe](csv-serde.md#csv-serde-opencsvserde-considerations-non-string)。 |
### 不支援分區資料表
在分區資料表上不支援 `INSERT INTO`。如需詳細資訊，請參閱[使用分割和歸納](ctas-partitioning-and-bucketing.md)。
### 不支援聯合查詢
`INSERT INTO` 不支援聯合查詢。嘗試執行這項操作可能會產生錯誤訊息：外部目錄目前不支援此操作。如需聯合查詢的詳細資訊，請參閱[使用 Amazon Athena 聯合查詢](federated-queries.md)。
### 分割
搭配 `INSERT INTO` 或 `CREATE TABLE AS SELECT` 查詢使用分割區時，請將本章節的幾個重點納入考量。
#### 限制
`INSERT INTO` 陳述式支援最多將 100 個分割區寫入目標資料表。如果您在分割區超過 100 個的資料表上執行 `SELECT` 子句，除非 `SELECT` 查詢限制在 100 個分割區或更少，否則查詢會失敗。
如需解決此限制的相關資訊，請參閱[使用 CTAS 和 INSERT INTO 來解決 100 個分割區限制](ctas-insert-into.md)。
#### 資料欄排序
`INSERT INTO` 或 `CREATE TABLE AS SELECT` 陳述式會預期分割的資料欄為 `SELECT` 陳述式中投影資料欄清單的最後一個資料欄。
如果來源資料表未經分割，或與目標資料表相比在不同的資料欄上分割，則如 `INSERT INTO destination_table SELECT * FROM source_table` 的查詢會將來源資料表中的最後一個資料欄的值，認定為目標資料表中的分割區資料欄的值。嘗試從未分割的資料表建立分割的資料表時，請注意以上提醒。
#### Resources
如需有關搭配分割使用 `INSERT INTO` 的詳細資料，請參閱以下資源。
+ 如需將分割的資料插入分割的資料表，請參閱[使用 CTAS 和 INSERT INTO 來解決 100 個分割區限制](ctas-insert-into.md)。
+ 如需將未分割的資料插入分割的資料表，請參閱[使用 CTAS 和 INSERT INTO 以進行 ETL 和資料分析](ctas-insert-into-etl.md)。
### 寫入 Amazon S3 的檔案
`INSERT` 命令執行之後，Athena 會將檔案寫入 Amazon S3 中的來源資料位置。每個 `INSERT` 操作都會建立新的檔案，而不是附加到現有的檔案。檔案位置取決於資料表和 `SELECT` 查詢的結構 (若有)。Athena 會為每個 `INSERT` 查詢生成一個資訊清單檔案。資訊清單會追蹤查詢寫入的檔案。它會儲存到 Amazon S3 中的 Athena 查詢結果位置。如需詳細資訊，請參閱[識別查詢輸出檔案](querying-finding-output-files.md#querying-identifying-output-files)。
### 避免高度交易更新
當您使用 `INSERT INTO` 將資料列新增至 Amazon S3 中的資料表時，Athena 不會重寫或修改現有檔案。相反地，它會將這些資料列寫入一或多個新檔案中。由於資料表[擁有許多小型檔案，進而導致查詢效能降低](performance-tuning-data-optimization-techniques.md#performance-tuning-avoid-having-too-many-files)，以及寫入和讀取操作 (例如 `PutObject` 和 `GetObject`) 會導致 Amazon S3 的成本提高，因此使用 `INSERT INTO` 時請考慮下列選項：
+ 對於較大的資料列批次，降低執行 `INSERT INTO` 操作的頻率。
+ 對於大型資料擷取量，請考慮使用 [Amazon Data Firehose](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html) 之類的服務。
+ 完全避免使用 `INSERT INTO`。相反地，請將資料列累積到較大的檔案中，然後直接上傳至 Amazon S3，其中 Athena 可以在其中查詢這些資料。
### 尋找孤立檔案
如果 `CTAS` 或 `INSERT INTO` 陳述式失敗，孤立的資料可以留在資料位置，並且可能會在後續查詢中讀取。若要尋找孤立檔案以進行檢測或刪除，您可以使用 Athena 提供的資料資訊清單檔案來追蹤要寫入的檔案清單。如需詳細資訊，請參閱[識別查詢輸出檔案](querying-finding-output-files.md#querying-identifying-output-files)和 [DataManifestLocation](https://docs.aws.amazon.com/athena/latest/APIReference/API_QueryExecutionStatistics.html#athena-Type-QueryExecutionStatistics-DataManifestLocation)。
## INSERT INTO...SELECT
指定在一個資料表上執行的查詢：`source_table`，這會決定要插入第二個資料表的資料列：`destination_table`。如果 `SELECT` 查詢指定 `source_table` 中的資料欄，則該資料欄必須精確地符合 `destination_table` 中的資料欄。
如需 `SELECT` 查詢的詳細資訊，請參閱[SELECT](select.md)。
### 概要
```
INSERT INTO destination_table
SELECT select_query
FROM source_table_or_view
```
### 範例
選取 `vancouver_pageviews` 資料表中的所有列，並將其插入 `canada_pageviews` 資料表：
```
INSERT INTO canada_pageviews
SELECT *
FROM vancouver_pageviews;
```
僅選取 `vancouver_pageviews` 資料表中的列，其中 `date` 資料欄有介於 `2019-07-01` 到 `2019-07-31` 間的值，然後將其插入 `canada_july_pageviews`：
```
INSERT INTO canada_july_pageviews
SELECT *
FROM vancouver_pageviews
WHERE date
BETWEEN date '2019-07-01'
AND '2019-07-31';
```
請僅從 `country` 資料欄中 `usa` 的值選取 `cities_world` 資料表中 `city` 與 `state` 欄內的值，並將其插入 `cities_usa` 資料表中的 `city` 和 `state` 欄：
```
INSERT INTO cities_usa (city,state)
SELECT city,state
FROM cities_world
WHERE country='usa'
```
## INSERT INTO... VALUES
透過指定資料欄和值，將資料列插入現有的資料表。指定的資料欄和相關聯的資料類型必須精確地符合目標資料表中的資料欄和資料類型。
**重要**
我們不建議使用 `VALUES` 插入資料行，因為 Athena 會為每個 `INSERT` 操作產生檔案。這可能會導致建立許多小型檔案，並降低資料表的查詢效能。若要識別 `INSERT` 查詢建立的檔案，請檢查資料資訊清單檔案。如需詳細資訊，請參閱[使用查詢結果和近期查詢](querying.md)。
### 概要
```
INSERT INTO destination_table [(col1,col2,...)]
VALUES (col1value,col2value,...)[,
(col1value,col2value,...)][,
...]
```
### 範例
在下列範例中，城市資料表有三個資料欄：`id`、`city`、`state`、`state_motto`。`id` 資料欄的類型是 `INT`，而其他所有欄的類型都是 `VARCHAR`。
將單一列插入 `cities` 資料表，並指定所有資料欄值：
```
INSERT INTO cities
VALUES (1,'Lansing','MI','Si quaeris peninsulam amoenam circumspice')
```
在 `cities` 資料表中插入兩列：
```
INSERT INTO cities
VALUES (1,'Lansing','MI','Si quaeris peninsulam amoenam circumspice'),
(3,'Boise','ID','Esto perpetua')
```
# VALUES
建立常值內嵌資料表。資料表可以是匿名的，或者您也可以使用 `AS` 子句來指定資料表名稱、資料欄名稱或兩者兼具。
## 概要
```
VALUES row [, ...]
```
## Parameters
**資料列**
`row` 參數可以是單一表達式，也可以是 `( column_expression [, ...] )`。
## 範例
傳回具有一個資料欄和三個資料列的資料表：
```
VALUES 1, 2, 3
```
傳回具有兩個資料欄和三個資料列的資料表：
```
VALUES
(1, 'a'),
(2, 'b'),
(3, 'c')
```
傳回具有資料欄 `id` 和 `name` 的資料表：
```
SELECT * FROM (
VALUES
(1, 'a'),
(2, 'b'),
(3, 'c')
) AS t (id, name)
```
使用資料列 `id` 和 `name`，建立名為 `customers` 的資料表：
```
CREATE TABLE customers AS
SELECT * FROM (
VALUES
(1, 'a'),
(2, 'b'),
(3, 'c')
) AS t (id, name)
```
## 另請參閱
[INSERT INTO... VALUES](insert-into.md#insert-into-values)
# DELETE
刪除 Apache Iceberg 資料表中的資料列。`DELETE` 是交易型的並且僅由 Apache Iceberg 資料表支援。
## 概要
若要刪除 Iceberg 資料表中的資料列，請使用下列語法。
```
DELETE FROM [db_name.]table_name [WHERE predicate]
```
如需詳細資訊和範例，請參閱 [更新 Iceberg 資料表資料](querying-iceberg-updating-iceberg-table-data.md) 中的 `DELETE` 一節。
# UPDATE
更新 Apache Iceberg 資料表中的資料列。`UPDATE` 是交易型的並且僅由 Apache Iceberg 資料表支援。該陳述式僅適用於現有資料列，且無法用於插入或附加資料列。
## 概要
若要更新 Iceberg 資料表中的資料列，請使用下列語法。
```
UPDATE [db_name.]table_name SET xx=yy[,...] [WHERE predicate]
```
如需詳細資訊和範例，請參閱 [更新 Iceberg 資料表資料](querying-iceberg-updating-iceberg-table-data.md) 中的 `UPDATE` 一節。
# 合併為
有條件地更新、刪除資料列或將其插入至 Apache Iceberg 資料表。單一陳述式可以組合更新、刪除和插入動作。
**注意**
`MERGE INTO` 是交易型的並且僅由 Athena 引擎版本 3 中的 Apache Iceberg 資料表支援。
## 概要
若要有條件地更新、刪除或插入 Iceberg 資料表中的資料列，請使用下列語法。
```
MERGE INTO target_table [ [ AS ] target_alias ]
USING { source_table | query } [ [ AS ] source_alias ]
ON search_condition
when_clause [...]
```
*when\$1clause* 是下列其中一項：
```
WHEN MATCHED [ AND condition ]
THEN DELETE
```
```
WHEN MATCHED [ AND condition ]
THEN UPDATE SET ( column = expression [, ...] )
```
```
WHEN NOT MATCHED [ AND condition ]
THEN INSERT (column_name[, column_name ...]) VALUES (expression, ...)
```
`MERGE` 支援具有不同 `MATCHED` 條件之任意數量的 `WHEN` 子句。條件子句會在由 `MATCHED` 狀態和符合條件選取的第一個 `WHEN` 子句中執行 `DELETE`、`UPDATE` 或 `INSERT` 運算。
針對每個來源資料列，會依序處理 `WHEN` 子句。只會執行第一個相符的 `WHEN` 子句。其餘子句會遭到忽略。當單一目標資料表資料列與多個來源資料列相符時，就會引起使用者錯誤。
如果來源資料列不與任何 `WHEN` 子句相符且沒有 `WHEN NOT MATCHED` 子句，則會忽略來源資料列。
在具有 `UPDATE` 運算的 `WHEN` 子句中，資料欄值表達式可以指代目標或來源的任何欄位。若是 `NOT MATCHED`，`INSERT` 表達式可以指代來源的任何欄位。
**範例**
下列範例會將第二個資料表中的資料列合併至第一個資料表 (如果第一個資料表中不存在資料列)。請注意，`VALUES` 子句中列出的資料欄必須加上來源資料表別名的字首。`INSERT` 子句中列出的目標資料欄*不*得使用字首。
```
MERGE INTO iceberg_table_sample as ice1
USING iceberg2_table_sample as ice2
ON ice1.col1 = ice2.col1
WHEN NOT MATCHED
THEN INSERT (col1)
VALUES (ice2.col1)
```
如需更多 `MERGE INTO` 範例，請參閱 [更新 Iceberg 資料表資料](querying-iceberg-updating-iceberg-table-data.md)。
# OPTIMIZE
根據相關刪除檔案的大小和數量，將資料檔案重寫成更好的版面配置，進而最佳化 Apache Iceberg 資料表中的列。
**注意**
`OPTIMIZE` 是交易型的並且僅由 Apache Iceberg 資料表支援。
## 語法
以下語法摘要說明最佳化處理 Iceberg 資料表的方式。
```
OPTIMIZE [db_name.]table_name REWRITE DATA USING BIN_PACK
[WHERE predicate]
```
**注意**
`WHERE` 子句*述詞*中只允許分割區資料欄。指定非分割區資料欄會導致查詢失敗。
壓縮動作按重寫過程中掃描的資料量計費。`REWRITE DATA` 動作使用述詞來選擇包含對應資料列的檔案。如果檔案中的任何資料列與述詞相對應，則會選擇該檔案進行最佳化處理。因此，為了控制壓縮時包含的文件數量，請指定 `WHERE` 子句。
## 設定壓縮屬性
為了控制要選擇進行壓縮的檔案大小以及壓縮後產生的檔案大小，請使用資料表屬性參數。您可以使用 [ALTER TABLE SET TBLPROPERTIES](querying-iceberg-alter-table-set-properties.md) 命令來設定相關的[資料表屬性](querying-iceberg-creating-tables.md#querying-iceberg-table-properties)。
## 其他資源
[最佳化 Iceberg 資料表](querying-iceberg-data-optimization.md)
# VACUUM
`VACUUM` 陳述式會執行[快照過期](https://iceberg.apache.org/docs/latest/spark-procedures/#expire_snapshots)和[孤立檔案移除](https://iceberg.apache.org/docs/latest/spark-procedures/#remove_orphan_files)，進而在 Apache Iceberg 資料表上執行資料表維護。
**注意**
`VACUUM` 是交易型的並且僅由 Athena 引擎版本 3 中的 Apache Iceberg 資料表支援。
`VACUUM` 陳述式會減少儲存消耗，進而最佳化 Iceberg 資料表。如需有關使用 `VACUUM` 的詳細資訊，請參閱 [最佳化 Iceberg 資料表](querying-iceberg-data-optimization.md)。請注意，由於 `VACUUM` 陳述式會對 Amazon S3 進行 API 呼叫，向 Amazon S3 發出相關請求需支付費用。
**警告**
如果您執行快照過期操作，則無法再回溯至過期的快照。
## 概要
若要移除 Iceberg 資料表中不再需要的資料檔案，請使用下列語法。
```
VACUUM [database_name.]target_table
```
+ `VACUUM` 預期 Iceberg 資料位於 Amazon S3 資料夾中，而非 Amazon S3 儲存貯體中。例如，如果您的 Iceberg 資料位於 `s3://amzn-s3-demo-bucket`/ 而非 `s3://amzn-s3-demo-bucket/myicebergfolder/`，則 `VACUUM` 陳述式會失敗，並顯示錯誤訊息 GENERIC\$1INTERNAL\$1ERROR：檔案系統位置中缺少路徑：`s3://amzn-s3-demo-bucket`。
+ 若要讓 `VACUUM` 能夠刪除資料檔案，您的查詢執行角色必須擁有對 Iceberg 資料表、中繼資料、快照和資料檔案所在儲存貯體的 `s3:DeleteObject` 許可。如果許可不存在，則 `VACUUM` 查詢會成功，但檔案不會刪除。
+ 若要在名稱以底線開頭 (例如 `_mytable`) 的資料表上執行 `VACUUM`，請以反引號括住資料表名稱，如下列範例所示。如果在資料表名稱前加上資料庫名稱作為字首，請勿以反引號括住資料庫名稱。請注意，雙引號不能取代反引號。
此行為專屬於 `VACUUM`。對於以底線開頭的資料表名稱，`CREATE` 和 `INSERT INTO` 陳述式不需要反引號。
```
VACUUM `_mytable`
VACUUM my_database.`_mytable`
```
## 執行的操作
`VACUUM` 執行以下操作：
+ 移除早於 `vacuum_max_snapshot_age_seconds` 資料表屬性指定之時間的快照。依預設，此屬性已設為 432000 秒 (5 天)。
+ 移除不在保留期間內且超過 `vacuum_min_snapshots_to_keep` 資料表屬性所指定數目的快照。預設為 1。
您可以在 `CREATE TABLE` 陳述式中指定這些資料表屬性。建立資料表之後，您就可以使用 [ALTER TABLE SET TBLPROPERTIES](querying-iceberg-alter-table-set-properties.md) 陳述式來進行更新。
+ 移除任何因為快照移除而無法取得的中繼資料和資料檔案。您可以設定 `vacuum_max_metadata_files_to_keep` 資料表屬性，進而設定要保留的舊中繼資料檔案數目。預設值為 100.
+ 移除早於 `vacuum_max_snapshot_age_seconds` 資料表屬性中指定之時間的孤立檔案。孤立檔案是資料表的資料目錄中不屬於資料表狀態的檔案。
如需有關在 Athena 中建立和管理 Apache Iceberg 資料表的詳細資訊，則請參閱 [建立 Iceberg 資料表](querying-iceberg-creating-tables.md) 和 [管理 Iceberg 資料表](querying-iceberg-managing-tables.md)。
# 在 Athena 使用 EXPLAIN 和 EXPLAIN ANALYZE
`EXPLAIN` 陳述式會顯示指定 SQL 陳述式的邏輯或分散式執行計劃，或驗證 SQL 陳述式。您可以以文字格式或資料格式輸出結果，以便轉譯成圖形。
**注意**
您可以在 Athena 主控台中檢視查詢的邏輯和分散式計劃的圖形呈現，無需使用 `EXPLAIN` 語法。如需詳細資訊，請參閱[檢視 SQL 查詢的執行計畫](query-plans.md)。
`EXPLAIN ANALYZE` 陳述式會顯示指定 SQL 陳述式的分散式執行計劃，以及 SQL 查詢中每個操作的運算成本。您可以將結果輸出為文字或 JSON 格式。
## 考量和限制
在 Athena 的 `EXPLAIN` 和 `EXPLAIN ANALYZE` 陳述式有下列限制。
+ `EXPLAIN` 查詢不會掃描任何資料，因此 Athena 不會為此收取費用。然而，由於 `EXPLAIN` 查詢會呼叫 AWS Glue 來擷取資料表中繼資料，如果呼叫超過 [Glue 免費方案限制](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Categories=categories%23analytics&all-free-tier.q=glue&all-free-tier.q_operator=AND)的次數，則會從 Glue 收取費用。
+ 因為已執行 `EXPLAIN ANALYZE` 查詢，它們會掃描資料，並且 Athena 會針對掃描的資料量收取費用。
+ 在 Lake Formation 中定義的資料列或儲存格篩選資訊及查詢統計資料資訊未在 `EXPLAIN` 和 `EXPLAIN ANALYZE` 的輸出中顯示。
## EXPLAIN 語法
```
EXPLAIN [ ( option [, ...]) ] statement
```
*option* 可為下列項目之一：
```
FORMAT { TEXT | GRAPHVIZ | JSON }
TYPE { LOGICAL | DISTRIBUTED | VALIDATE | IO }
```
如果未指定 `FORMAT` 選項，則輸出預設為 `TEXT` 格式。`IO` 類型提供有關查詢讀取的資料表和結構描述的資訊。
## EXPLAIN ANALYZE 語法
除了包含在 `EXPLAIN`，`EXPLAIN ANALYZE` 輸出也包含指定查詢的執行時間統計數字，例如 CPU 用量、資料列輸入數目以及資料列輸出數目。
```
EXPLAIN ANALYZE [ ( option [, ...]) ] statement
```
*option* 可為下列項目之一：
```
FORMAT { TEXT | JSON }
```
如果未指定 `FORMAT` 選項，則輸出預設為 `TEXT` 格式。因為 `EXPLAIN ANALYZE` 的所有查詢為 `DISTRIBUTED`，則 `TYPE` 選項不可為 `EXPLAIN ANALYZE`。
*陳述式*可為下列其中之一：
```
SELECT
CREATE TABLE AS SELECT
INSERT
UNLOAD
```
## EXPLAIN 範例
下列針對 `EXPLAIN` 的範例從較簡單的內容進展到較複雜的內容。
### 範例 1：使用 EXPLAIN 陳述式以文字格式顯示查詢計畫
在下列範例中，`EXPLAIN` 會顯示對 Elastic Load Balancing 日誌的 `SELECT` 查詢的執行計劃。格式預設為文字輸出。
```
EXPLAIN
SELECT
request_timestamp,
elb_name,
request_ip
FROM sampledb.elb_logs;
```
#### 結果
```
- Output[request_timestamp, elb_name, request_ip] => [[request_timestamp, elb_name, request_ip]]
- RemoteExchange[GATHER] => [[request_timestamp, elb_name, request_ip]]
- TableScan[awsdatacatalog:HiveTableHandle{schemaName=sampledb, tableName=elb_logs,
analyzePartitionValues=Optional.empty}] => [[request_timestamp, elb_name, request_ip]]
LAYOUT: sampledb.elb_logs
request_ip := request_ip:string:2:REGULAR
request_timestamp := request_timestamp:string:0:REGULAR
elb_name := elb_name:string:1:REGULAR
```
### 範例 2：使用 EXPLAIN 繪製查詢計畫的圖形
您可以使用 Athena 主控台來繪製查詢計劃圖。在查詢編輯器中輸入類似以下的 `SELECT` 陳述式，然後選擇 **EXPLAIN**。
```
SELECT
c.c_custkey,
o.o_orderkey,
o.o_orderstatus
FROM tpch100.customer c
JOIN tpch100.orders o
ON c.c_custkey = o.o_custkey
```
Athena 查詢編輯器的 **Explain** (解釋) 頁面隨即開啟，並顯示查詢的分散式計劃和邏輯計劃。下圖顯示範例的邏輯計劃。
![\[Athena 查詢編輯器轉譯的查詢計劃圖。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/athena-explain-statement-tpch.png)
**重要**
目前，即使 Athena 確實將這些篩選條件套用至您的查詢，有些分割區篩選條件可能不會顯示在巢狀運算子樹狀結構圖形中。若要驗證此等篩選條件的效果，請在查詢上執行 `EXPLAIN` 或 `EXPLAIN ANALYZE` 並查看結果。
如需在 Athena 主控台中使用查詢計劃圖形功能的詳細資訊，請參閱 [檢視 SQL 查詢的執行計畫](query-plans.md)。
### 範例 3：使用 EXPLAIN 陳述式來驗證分割區剔除
當您對分割的金鑰使用篩選述詞來查詢分割的資料表時，查詢引擎會將述詞套用至分割的金鑰，以減少讀取的資料量。
以下範例使用 `EXPLAIN` 查詢，對分割資料表上的 `SELECT` 查詢驗證分割區剔除。首先，`CREATE TABLE` 陳述式會建立 `tpch100.orders_partitioned` 資料表。該資料表在資料欄 `o_orderdate` 上分割。
```
CREATE TABLE `tpch100.orders_partitioned`(
`o_orderkey` int,
`o_custkey` int,
`o_orderstatus` string,
`o_totalprice` double,
`o_orderpriority` string,
`o_clerk` string,
`o_shippriority` int,
`o_comment` string)
PARTITIONED BY (
`o_orderdate` string)
ROW FORMAT SERDE
'org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe'
STORED AS INPUTFORMAT
'org.apache.hadoop.hive.ql.io.parquet.MapredParquetInputFormat'
OUTPUTFORMAT
'org.apache.hadoop.hive.ql.io.parquet.MapredParquetOutputFormat'
LOCATION
's3://amzn-s3-demo-bucket//'
```
`tpch100.orders_partitioned` 資料表在 `o_orderdate` 上有多個分割區，如 `SHOW PARTITIONS` 命令所示。
```
SHOW PARTITIONS tpch100.orders_partitioned;
o_orderdate=1994
o_orderdate=2015
o_orderdate=1998
o_orderdate=1995
o_orderdate=1993
o_orderdate=1997
o_orderdate=1992
o_orderdate=1996
```
下列 `EXPLAIN` 查詢會對指定 `SELECT` 陳述式驗證分割區剔除。
```
EXPLAIN
SELECT
o_orderkey,
o_custkey,
o_orderdate
FROM tpch100.orders_partitioned
WHERE o_orderdate = '1995'
```
#### 結果
```
Query Plan
- Output[o_orderkey, o_custkey, o_orderdate] => [[o_orderkey, o_custkey, o_orderdate]]
- RemoteExchange[GATHER] => [[o_orderkey, o_custkey, o_orderdate]]
- TableScan[awsdatacatalog:HiveTableHandle{schemaName=tpch100, tableName=orders_partitioned,
analyzePartitionValues=Optional.empty}] => [[o_orderkey, o_custkey, o_orderdate]]
LAYOUT: tpch100.orders_partitioned
o_orderdate := o_orderdate:string:-1:PARTITION_KEY
:: [[1995]]
o_custkey := o_custkey:int:1:REGULAR
o_orderkey := o_orderkey:int:0:REGULAR
```
結果中的粗體文字顯示述詞 `o_orderdate = '1995'` 已套用於 `PARTITION_KEY`。
### 範例 4：使用 EXPLAIN 查詢來檢查聯結順序和聯結類型
下列 `EXPLAIN` 查詢會檢查 `SELECT` 陳述式的聯結順序和聯結類型。使用這樣的查詢來檢查查詢記憶體的使用情況，以便減少取得 `EXCEEDED_LOCAL_MEMORY_LIMIT` 錯誤的可能性。
```
EXPLAIN (TYPE DISTRIBUTED)
SELECT
c.c_custkey,
o.o_orderkey,
o.o_orderstatus
FROM tpch100.customer c
JOIN tpch100.orders o
ON c.c_custkey = o.o_custkey
WHERE c.c_custkey = 123
```
#### 結果
```
Query Plan
Fragment 0 [SINGLE]
Output layout: [c_custkey, o_orderkey, o_orderstatus]
Output partitioning: SINGLE []
Stage Execution Strategy: UNGROUPED_EXECUTION
- Output[c_custkey, o_orderkey, o_orderstatus] => [[c_custkey, o_orderkey, o_orderstatus]]
- RemoteSource[1] => [[c_custkey, o_orderstatus, o_orderkey]]
Fragment 1 [SOURCE]
Output layout: [c_custkey, o_orderstatus, o_orderkey]
Output partitioning: SINGLE []
Stage Execution Strategy: UNGROUPED_EXECUTION
- CrossJoin => [[c_custkey, o_orderstatus, o_orderkey]]
Distribution: REPLICATED
- ScanFilter[table = awsdatacatalog:HiveTableHandle{schemaName=tpch100,
tableName=customer, analyzePartitionValues=Optional.empty}, grouped = false,
filterPredicate = ("c_custkey" = 123)] => [[c_custkey]]
LAYOUT: tpch100.customer
c_custkey := c_custkey:int:0:REGULAR
- LocalExchange[SINGLE] () => [[o_orderstatus, o_orderkey]]
- RemoteSource[2] => [[o_orderstatus, o_orderkey]]
Fragment 2 [SOURCE]
Output layout: [o_orderstatus, o_orderkey]
Output partitioning: BROADCAST []
Stage Execution Strategy: UNGROUPED_EXECUTION
- ScanFilterProject[table = awsdatacatalog:HiveTableHandle{schemaName=tpch100,
tableName=orders, analyzePartitionValues=Optional.empty}, grouped = false,
filterPredicate = ("o_custkey" = 123)] => [[o_orderstatus, o_orderkey]]
LAYOUT: tpch100.orders
o_orderstatus := o_orderstatus:string:2:REGULAR
o_custkey := o_custkey:int:1:REGULAR
o_orderkey := o_orderkey:int:0:REGULAR
```
查詢範例在交叉聯結中得到最佳化處理，以獲得更好的性能。結果顯示 `tpch100.orders` 將作為 `BROADCAST` 分佈類型進行分配。這意味著 `tpch100.orders` 資料表將分配到執行聯結操作的所有節點。`BROADCAST` 分佈類型會要求 `tpch100.orders` 資料表的所有篩選結果納入執行聯結操作的每個節點的記憶體。
不過，`tpch100.customer` 資料表比 `tpch100.orders` 小。由於 `tpch100.customer` 需要更少的記憶體，您可以將查詢重寫為 `BROADCAST tpch100.customer`，而非 `tpch100.orders`。這可減少查詢取得 `EXCEEDED_LOCAL_MEMORY_LIMIT` 錯誤的可能性。此策略假設下列要點：
+ 在 `tpch100.customer` 資料表中 `tpch100.customer.c_custkey` 為唯一。
+ 在 `tpch100.customer` 和 `tpch100.orders` 間有一對多的映射關係。
下列範例顯示重寫的查詢。
```
SELECT
c.c_custkey,
o.o_orderkey,
o.o_orderstatus
FROM tpch100.orders o
JOIN tpch100.customer c -- the filtered results of tpch100.customer are distributed to all nodes.
ON c.c_custkey = o.o_custkey
WHERE c.c_custkey = 123
```
### 範例 5：使用 EXPLAIN 查詢移除沒有效果的述詞
您可以使用 `EXPLAIN` 查詢來檢查篩選述詞的有效性。您可以使用結果移除沒有效果的述詞，如下列範例所示。
```
EXPLAIN
SELECT
c.c_name
FROM tpch100.customer c
WHERE c.c_custkey = CAST(RANDOM() * 1000 AS INT)
AND c.c_custkey BETWEEN 1000 AND 2000
AND c.c_custkey = 1500
```
#### 結果
```
Query Plan
- Output[c_name] => [[c_name]]
- RemoteExchange[GATHER] => [[c_name]]
- ScanFilterProject[table =
awsdatacatalog:HiveTableHandle{schemaName=tpch100,
tableName=customer, analyzePartitionValues=Optional.empty},
filterPredicate = (("c_custkey" = 1500) AND ("c_custkey" =
CAST(("random"() * 1E3) AS int)))] => [[c_name]]
LAYOUT: tpch100.customer
c_custkey := c_custkey:int:0:REGULAR
c_name := c_name:string:1:REGULAR
```
結果中的 `filterPredicate` 顯示優化器將原始三個述詞合併為兩個述詞，並更改了應用程式的順序。
```
filterPredicate = (("c_custkey" = 1500) AND ("c_custkey" = CAST(("random"() * 1E3) AS int)))
```
因為結果顯示述詞 `AND c.c_custkey BETWEEN 1000 AND 2000` 沒有任何效果，您可以在不更改查詢結果的情況下移除此述詞。
如需有關 `EXPLAIN` 查詢結果中所使用術語的詳細資訊，請參閱[了解 Athena EXPLAIN 陳述式結果](athena-explain-statement-understanding.md)。
## EXPLAIN ANALYZE 範例
下列範例將顯示範例 `EXPLAIN ANALYZE` 查詢和輸出。
### 範例 1：使用 EXPLAIN ANALYZE 以文字格式顯示查詢計畫和運算成本
在下列範例中，`EXPLAIN ANALYZE` 會顯示對 CloudFront 日誌的 `SELECT` 查詢的執行計劃和運算成本。格式預設為文字輸出。
```
EXPLAIN ANALYZE SELECT FROM cloudfront_logs LIMIT 10
```
#### 結果
```
Fragment 1
CPU: 24.60ms, Input: 10 rows (1.48kB); per task: std.dev.: 0.00, Output: 10 rows (1.48kB)
Output layout: [date, time, location, bytes, requestip, method, host, uri, status, referrer,\
os, browser, browserversion]
Limit[10] => [[date, time, location, bytes, requestip, method, host, uri, status, referrer, os,\
browser, browserversion]]
CPU: 1.00ms (0.03%), Output: 10 rows (1.48kB)
Input avg.: 10.00 rows, Input std.dev.: 0.00%
LocalExchange[SINGLE] () => [[date, time, location, bytes, requestip, method, host, uri, status, referrer, os,\
browser, browserversion]]
CPU: 0.00ns (0.00%), Output: 10 rows (1.48kB)
Input avg.: 0.63 rows, Input std.dev.: 387.30%
RemoteSource[2] => [[date, time, location, bytes, requestip, method, host, uri, status, referrer, os,\
browser, browserversion]]
CPU: 1.00ms (0.03%), Output: 10 rows (1.48kB)
Input avg.: 0.63 rows, Input std.dev.: 387.30%
Fragment 2
CPU: 3.83s, Input: 998 rows (147.21kB); per task: std.dev.: 0.00, Output: 20 rows (2.95kB)
Output layout: [date, time, location, bytes, requestip, method, host, uri, status, referrer, os,\
browser, browserversion]
LimitPartial[10] => [[date, time, location, bytes, requestip, method, host, uri, status, referrer, os,\
browser, browserversion]]
CPU: 5.00ms (0.13%), Output: 20 rows (2.95kB)
Input avg.: 166.33 rows, Input std.dev.: 141.42%
TableScan[awsdatacatalog:HiveTableHandle{schemaName=default, tableName=cloudfront_logs,\
analyzePartitionValues=Optional.empty},
grouped = false] => [[date, time, location, bytes, requestip, method, host, uri, st
CPU: 3.82s (99.82%), Output: 998 rows (147.21kB)
Input avg.: 166.33 rows, Input std.dev.: 141.42%
LAYOUT: default.cloudfront_logs
date := date:date:0:REGULAR
referrer := referrer:string:9:REGULAR
os := os:string:10:REGULAR
method := method:string:5:REGULAR
bytes := bytes:int:3:REGULAR
browser := browser:string:11:REGULAR
host := host:string:6:REGULAR
requestip := requestip:string:4:REGULAR
location := location:string:2:REGULAR
time := time:string:1:REGULAR
uri := uri:string:7:REGULAR
browserversion := browserversion:string:12:REGULAR
status := status:int:8:REGULAR
```
### 範例 2：使用 EXPLAIN ANALYZE 以 JSON 格式顯示查詢計畫
下列範例會顯示對 CloudFront 日誌的 `SELECT` 查詢的執行計劃和運算成本。此範例指定 JSON 作為輸出格式。
```
EXPLAIN ANALYZE (FORMAT JSON) SELECT * FROM cloudfront_logs LIMIT 10
```
#### 結果
```
{
"fragments": [{
"id": "1",
"stageStats": {
"totalCpuTime": "3.31ms",
"inputRows": "10 rows",
"inputDataSize": "1514B",
"stdDevInputRows": "0.00",
"outputRows": "10 rows",
"outputDataSize": "1514B"
},
"outputLayout": "date, time, location, bytes, requestip, method, host,\
uri, status, referrer, os, browser, browserversion",
"logicalPlan": {
"1": [{
"name": "Limit",
"identifier": "[10]",
"outputs": ["date", "time", "location", "bytes", "requestip", "method", "host",\
"uri", "status", "referrer", "os", "browser", "browserversion"],
"details": "",
"distributedNodeStats": {
"nodeCpuTime": "0.00ns",
"nodeOutputRows": 10,
"nodeOutputDataSize": "1514B",
"operatorInputRowsStats": [{
"nodeInputRows": 10.0,
"nodeInputRowsStdDev": 0.0
}]
},
"children": [{
"name": "LocalExchange",
"identifier": "[SINGLE] ()",
"outputs": ["date", "time", "location", "bytes", "requestip", "method", "host",\
"uri", "status", "referrer", "os", "browser", "browserversion"],
"details": "",
"distributedNodeStats": {
"nodeCpuTime": "0.00ns",
"nodeOutputRows": 10,
"nodeOutputDataSize": "1514B",
"operatorInputRowsStats": [{
"nodeInputRows": 0.625,
"nodeInputRowsStdDev": 387.2983346207417
}]
},
"children": [{
"name": "RemoteSource",
"identifier": "[2]",
"outputs": ["date", "time", "location", "bytes", "requestip", "method", "host",\
"uri", "status", "referrer", "os", "browser", "browserversion"],
"details": "",
"distributedNodeStats": {
"nodeCpuTime": "0.00ns",
"nodeOutputRows": 10,
"nodeOutputDataSize": "1514B",
"operatorInputRowsStats": [{
"nodeInputRows": 0.625,
"nodeInputRowsStdDev": 387.2983346207417
}]
},
"children": []
}]
}]
}]
}
}, {
"id": "2",
"stageStats": {
"totalCpuTime": "1.62s",
"inputRows": "500 rows",
"inputDataSize": "75564B",
"stdDevInputRows": "0.00",
"outputRows": "10 rows",
"outputDataSize": "1514B"
},
"outputLayout": "date, time, location, bytes, requestip, method, host, uri, status,\
referrer, os, browser, browserversion",
"logicalPlan": {
"1": [{
"name": "LimitPartial",
"identifier": "[10]",
"outputs": ["date", "time", "location", "bytes", "requestip", "method", "host", "uri",\
"status", "referrer", "os", "browser", "browserversion"],
"details": "",
"distributedNodeStats": {
"nodeCpuTime": "0.00ns",
"nodeOutputRows": 10,
"nodeOutputDataSize": "1514B",
"operatorInputRowsStats": [{
"nodeInputRows": 83.33333333333333,
"nodeInputRowsStdDev": 223.60679774997897
}]
},
"children": [{
"name": "TableScan",
"identifier": "[awsdatacatalog:HiveTableHandle{schemaName=default,\
tableName=cloudfront_logs, analyzePartitionValues=Optional.empty},\
grouped = false]",
"outputs": ["date", "time", "location", "bytes", "requestip", "method", "host", "uri",\
"status", "referrer", "os", "browser", "browserversion"],
"details": "LAYOUT: default.cloudfront_logs\ndate := date:date:0:REGULAR\nreferrer :=\
referrer: string:9:REGULAR\nos := os:string:10:REGULAR\nmethod := method:string:5:\
REGULAR\nbytes := bytes:int:3:REGULAR\nbrowser := browser:string:11:REGULAR\nhost :=\
host:string:6:REGULAR\nrequestip := requestip:string:4:REGULAR\nlocation :=\
location:string:2:REGULAR\ntime := time:string:1: REGULAR\nuri := uri:string:7:\
REGULAR\nbrowserversion := browserversion:string:12:REGULAR\nstatus :=\
status:int:8:REGULAR\n",
"distributedNodeStats": {
"nodeCpuTime": "1.62s",
"nodeOutputRows": 500,
"nodeOutputDataSize": "75564B",
"operatorInputRowsStats": [{
"nodeInputRows": 83.33333333333333,
"nodeInputRowsStdDev": 223.60679774997897
}]
},
"children": []
}]
}]
}
}]
}
```
## 其他資源
如需其他資訊，請參閱以下資源。
+ [了解 Athena EXPLAIN 陳述式結果](athena-explain-statement-understanding.md)
+ [檢視 SQL 查詢的執行計畫](query-plans.md)
+ [檢視已完成查詢的統計資料和執行詳細資訊](query-stats.md)
+ Trino [https://trino.io/docs/current/sql/explain.html](https://trino.io/docs/current/sql/explain.html) 文件
+ Trino [https://trino.io/docs/current/sql/explain-analyze.html](https://trino.io/docs/current/sql/explain-analyze.html) 文件
+ *AWS 大數據部落格*中的[使用 Amazon Athena 中的 EXPLAIN 和 EXPLAIN ANALYZE 優化聯合查詢效能](https://aws.amazon.com/blogs/big-data/optimize-federated-query-performance-using-explain-and-explain-analyze-in-amazon-athena/)。
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/7JUyTqglmNU)
# 了解 Athena EXPLAIN 陳述式結果
本主題提供 Athena `EXPLAIN` 陳述式結果中使用的操作術語的簡要指南。
## EXPLAIN 陳述式輸出類型
`EXPLAIN` 陳述式輸出可為以下兩種類型之一：
+ **邏輯計劃** – 顯示 SQL 引擎用來執行陳述式的邏輯計劃。此選項的語法為 `EXPLAIN` 或 `EXPLAIN (TYPE LOGICAL)`。
+ **分散式計劃** – 顯示分散式環境中的執行計劃。輸出顯示片段，這是處理階段。每個計劃片段會由一或多個節點處理。資料可以在處理片段的節點之間進行交換。此選項的語法為 `EXPLAIN (TYPE DISTRIBUTED)`。
在分散式計畫的輸出中，用 `Fragment` *number* [*fragment\$1type*] 表示片段 (處理階段)，其中 *number* 是一個以零為起始的整數，以及 *fragment\$1type* 指定片段如何由節點執行。片段類型提供資料交換配置的深入資訊，如下表所述。
**分散式計劃片段類型**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/athena-explain-statement-understanding.html)
## Exchange
交換相關術語描述如何在工作節點之間交換資料。傳輸可以是本機或遠端。
**LocalExchange [*exchange\$1type*] **
針對查詢的不同階段，在工作節點內本機傳輸資料。*exchange\$1type* 的值可以是邏輯或分散式交換類型其中一種，如本節後文所述。
**RemoteExchange [*exchange\$1type*] **
針對查詢的不同階段，在工作節點之間傳輸資料。*exchange\$1type* 的值可以是邏輯或分散式交換類型其中一種，如本節後文所述。
### 邏輯 Exchange 類型
下列交換類型說明邏輯計劃的交換階段期間所採取的動作。
+ **`GATHER`** – 單一工作節點會收集所有其他工作節點的輸出。例如，選取查詢的最後階段會收集所有節點的結果，並將結果寫入 Amazon S3。
+ **`REPARTITION`** – 根據套用至下一個運算子所需的分割結構描述，將資料行資料傳送至特定工作者。
+ **`REPLICATE`** – 將資料行資料複製到所有工作者。
### 分散式交換類型
下列交換類型指出在分散式計劃中的節點之間交換資料時的資料配置。
+ **`HASH`** – 交換會使用雜湊函數將資料分配到多個目的地。
+ **`SINGLE`** – 交換會將資料分配到單一目的地。
## 掃描
下列術語描述查詢期間如何掃描資料。
**TableScan **
掃描來自 Amazon S3 或 Apache Hive 連接器的資料表來源資料，並套用從篩選述詞產生的分割區剔除。
**ScanFilter **
掃描來自 Amazon S3 或 Hive 連接器的資料表來源資料，並套用從篩選述詞產生的分割區剔除，以及從沒有透過分割區剔除套用的其他篩選述詞產生的分割區剔除。
**ScanFilterProject **
首先，掃描來自 Amazon S3 或 Hive 連接器的資料表來源資料，並套用從篩選述詞產生的分割區剔除，以及從沒有透過分割區剔除套用的其他篩選述詞產生的分割區剔除。然後，將輸出資料的記憶體配置修改為新的投影，以改善後續階段的效能。
## Join
聯結兩個資料表之間的資料。聯結可以依聯結類型和分佈類型來分類。
### 聯結類型
聯結類型定義聯結操作發生的方式。
**CrossJoin** – 產生已聯結的兩個資料表的笛卡兒乘積。
**InnerJoin** – 選取兩個資料表中具有相符值的記錄。
**LeftJoin** – 選取左資料表中的所有記錄，以及右資料表中的相符記錄。如果沒有發生匹配，右側的結果是 NULL。
**RightJoin** – 選取右資料表中的所有記錄，以及左資料表中的相符記錄。如果沒有發生匹配，左側的結果是 NULL。
**FullJoin** – 選取左側或右側資料表記錄中有相符項目的所有記錄。聯結資料表包含來自兩個資料表的所有記錄，並在兩側不符的地方以 NULL 填充。
**注意**
基於效能考量，查詢引擎可以將聯結查詢重新寫入不同的聯結類型，以產生相同的結果。例如，在一個資料表上具有述詞的內部聯結查詢可以重寫入 `CrossJoin`。這會將述詞推送到資料表的掃描階段，以便掃描較少的資料。
### 聯結分佈類型
分佈類型定義執行聯結操作時，如何在工作節點之間交換資料。
**已分割** – 左側和右側資料表會在所有工作節點間進行雜湊分割。已分割分佈會在每個節點消耗較少的記憶體。已分割分佈可以比複寫的聯結慢得多。當您聯結兩個大資料表時適合使用已分割聯結。
**已複寫** – 一個資料表會在所有工作節點之間進行雜湊分割，另一個資料表會複寫到所有工作節點，以執行聯結操作。複寫的分佈可以比已分割聯結快得多，但它會在每個工作節點中耗用更多的記憶體。如果複寫的資料表太大，工作節點可能會遇到記憶體不足錯誤。當其中一個聯結的資料表很小時，就適合使用複寫的聯結。
# PREPARE
使用名稱 `statement_name` 建立 SQL 陳述式，以供之後執行。陳述式可以包含以問號表示的參數。若要提供值給參數並執行預備陳述式，請使用 [EXECUTE](sql-execute.md)。
## 概要
```
PREPARE statement_name FROM statement
```
下表描述了參數。
****
| 參數 | Description |
| --- | --- |
| statement\$1name | 要預備之陳述式的名稱。該名稱在工作群組內必須是唯一的。 |
| statement | SELECT、CTAS 或 INSERT INTO 查詢。 |
**注意**
工作群組中預備陳述式的數量上限為 1000。
## 範例
以下範例準備一個不含參數的選擇查詢。
```
PREPARE my_select1 FROM
SELECT * FROM nation
```
以下範例準備一個包含參數的選擇查詢。`productid` 和 `quantity` 的值將由 `EXECUTE` 陳述式的 `USING` 子句提供：
```
PREPARE my_select2 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 = ?
```
## 其他資源
[使用預備陳述式](querying-with-prepared-statements-querying.md)
[EXECUTE](sql-execute.md)
[DEALLOCATE PREPARE](sql-deallocate-prepare.md)
[INSERT INTO](insert-into.md)
# EXECUTE
執行名為 `statement_name` 的預備陳述式。預備陳述式中問號的參數值定義在以逗號分隔的清單的 `USING` 子句中。若要建立預備陳述式，使用 [PREPARE](sql-prepare.md)。
## 概要
```
EXECUTE statement_name [ USING parameter1[, parameter2, ... ] ]
```
## 範例
以下範例準備並執行不含任何參數的查詢。
```
PREPARE my_select1 FROM
SELECT name FROM nation
EXECUTE my_select1
```
以下範例準備並執行含有一個參數的查詢。
```
PREPARE my_select2 FROM
SELECT * FROM "my_database"."my_table" WHERE year = ?
EXECUTE my_select2 USING 2012
```
這相當於：
```
SELECT * FROM "my_database"."my_table" WHERE year = 2012
```
以下範例準備並執行含有兩個參數的查詢。
```
PREPARE my_select3 FROM
SELECT order FROM orders WHERE productid = ? and quantity < ?
EXECUTE my_select3 USING 346078, 12
```
## 其他資源
[使用預備陳述式](querying-with-prepared-statements-querying.md)
[PREPARE](sql-prepare.md)
[INSERT INTO](insert-into.md)
# DEALLOCATE PREPARE
從目前工作群組的預備陳述式中移除具有指定名稱的預備陳述式。
## 概要
```
DEALLOCATE PREPARE statement_name
```
## 範例
下列範例會從目前的工作群組中移除 `my_select1` 預備陳述式。
```
DEALLOCATE PREPARE my_select1
```
## 其他資源
[使用預備陳述式](querying-with-prepared-statements-querying.md)
[PREPARE](sql-prepare.md)
# UNLOAD
從 `SELECT` 陳述式寫入查詢結果至指定的資料格式。針對 `UNLOAD` 支援的格式包括 Apache Parquet、ORC、Apache Avro 和 JSON。CSV 是 Athena `SELECT` 命令支援的唯一輸出格式，但您可以使用支援各種輸出格式的 `UNLOAD` 命令來括住 `SELECT` 查詢，並將其輸出重寫為 `UNLOAD` 支援的其中一種格式。
雖然您可以使用 `CREATE TABLE AS` (CTAS) 陳述式以 CSV 以外的格式輸出資料，但 CTAS 陳述式需要在 Athena 中建立資料表。`UNLOAD` 陳述式在您想以非 CSV 格式輸出 `SELECT` 查詢結果，但不要相關聯的資料表時十分有用。例如，下游應用程式可能需要 `SELECT` 查詢結果使用 JSON 格式，而且如果您打算對其他分析使用 `SELECT` 查詢結果，則 Parquet 或 ORC 的效能可能優於 CSV。
## 考量和限制
當您在 Athena 中使用 `UNLOAD` 陳述式時，請謹記以下幾點：
+ **沒有檔案的全域排序** – `UNLOAD`結果會同時寫入多個檔案。如果 `UNLOAD` 陳述式中的 `SELECT` 查詢會指定排序順序，則每個檔案的內容會依排序順序排列，但檔案並不會彼此排序。
+ **未刪除孤立資料** – 在發生故障的情況下，Athena 不會嘗試刪除孤立的資料。此行為同於 CTAS 和 `INSERT INTO` 陳述式。
+ **分割區數量上限** – 可搭配 `UNLOAD` 使用的分割區數量上限為 100。
+ **中繼資料和資訊清單檔案** – Athena 會為每個 `UNLOAD` 查詢產生中繼資料檔案和資訊清單檔案。資訊清單會追蹤查詢寫入的檔案。這兩個檔案都會儲存到 Amazon S3 中的 Athena 查詢結果位置。如需詳細資訊，請參閱[識別查詢輸出檔案](querying-finding-output-files.md#querying-identifying-output-files)。
+ **加密** – `UNLOAD` 輸出檔案會根據用於 Amazon S3 的加密組態進行加密。若要設定加密組態來加密 `UNLOAD` 結果，您可以使用 [EncryptionConfiguration API](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html)。
+ **預備陳述式** – `UNLOAD` 可以與預備的陳述式一起使用。如需有關 Athena 中的預備陳述式的資訊，請參閱[使用參數化查詢](querying-with-prepared-statements.md)。
+ **服務配額** – `UNLOAD` 會使用 DML 查詢配額。如需有關配額的資訊，請參閱 [Service Quotas](service-limits.md)。
+ **預期的儲存貯體擁有者** – 預期的儲存貯體擁有者設定不適用於 `UNLOAD` 查詢中指定的目的地 Amazon S3 位置。預期的儲存貯體擁有者設定僅適用於您為 Athena 查詢結果指定的 Amazon S3 輸出位置。如需詳細資訊，請參閱[使用 Athena 主控台指定查詢結果位置](query-results-specify-location-console.md)。
## 語法
`UNLOAD` 陳述式使用下列語法。
```
UNLOAD (SELECT col_name[, ...] FROM old_table)
TO 's3://amzn-s3-demo-bucket/my_folder/'
WITH ( property_name = 'expression' [, ...] )
```
除了寫入分割區時，`TO` 目標必須在沒有資料的 Amazon S3 中指定位置。在 `UNLOAD` 查詢寫入指定位置之前，它會驗證儲存貯體位置是否為空。由於 `UNLOAD` 在指定位置已經有資料時不會將資料寫入該位置，`UNLOAD` 不會覆寫現有資料。若要重複使用儲存貯體位置作為 `UNLOAD` 的目標，請刪除儲存貯體位置中的資料，然後再次執行查詢。
請注意，當 `UNLOAD` 寫入分割區時，此行為會有所不同。如果您多次執行具有相同 `SELECT` 陳述式、相同 `TO` 位置和相同分割區的相同 `UNLOAD` 查詢，則每個 `UNLOAD` 查詢都會在指定的位置和分割區將資料卸載至 Amazon S3。
### Parameters
*property\$1name* 可能的值如下。
** 格式 = '*file\$1format*'**
必要。指定輸出的檔案格式。*file\$1format* 的可能值為 `ORC`、`PARQUET`、`AVRO`、`JSON` 或 `TEXTFILE`。
** 壓縮 = '*compression\$1format*'**
選用。此選項僅適用於 ORC 和 Parquet 格式。ORC 的預設值為 `zlib`，而 Parquet 的預設值則為 `gzip`。如需有關支援的壓縮格式的資訊，請參閱 [Athena 壓縮支援](https://docs.aws.amazon.com/athena/latest/ug/compression-formats.html)。
此選項不適用於 `AVRO` 格式。Athena 對 `JSON` 和 `TEXTFILE` 格式使用 `gzip`。
**compression\$1level = *compression\$1level* **
選用。用於 ZSTD 壓縮的壓縮級別。此屬性僅適用於 ZSTD 壓縮。如需詳細資訊，請參閱[使用 ZSTD 壓縮級別](compression-support-zstd-levels.md)。
** field\$1delimiter = '*delimiter*'**
選用。指定 CSV、TSV 和其他文字格式檔案的單一字元欄位分隔符號。以下範例指定逗點分隔符號。
```
WITH (field_delimiter = ',')
```
目前不支援多字元欄位分隔符號。如果您未指定欄位分隔符號，系統會使用八進位制字元 `\001` (^A)。
** partitioned\$1by = ARRAY[ *col\$1name*[,...] ] **
選用。資料欄的陣列清單，輸出依這些資料欄進行分割。
在 `SELECT` 陳列式中，請確保已分割資料欄的名稱位於資料欄清單中的最後。
## 範例
下列範例會使用 JSON 格式，將 `SELECT` 查詢的輸出寫入 Amazon S3 位置 `s3://amzn-s3-demo-bucket/unload_test_1/`。
```
UNLOAD (SELECT * FROM old_table)
TO 's3://amzn-s3-demo-bucket/unload_test_1/'
WITH (format = 'JSON')
```
下列範例會採用 Snappy 壓縮方式以 Parquet 格式寫入 `SELECT` 查詢的輸出。
```
UNLOAD (SELECT * FROM old_table)
TO 's3://amzn-s3-demo-bucket/'
WITH (format = 'PARQUET',compression = 'SNAPPY')
```
下列範例會以文字格式寫入四個資料欄，且輸出依最後一個資料欄分割。
```
UNLOAD (SELECT name1, address1, comment1, key1 FROM table1)
TO 's3://amzn-s3-demo-bucket/ partitioned/'
WITH (format = 'TEXTFILE', partitioned_by = ARRAY['key1'])
```
下列範例會使用 Parquet 檔案格式、ZSTD 壓縮和 ZSTD 壓縮級別 4，將查詢結果卸載到指定的位置。
```
UNLOAD (SELECT * FROM old_table)
TO 's3://amzn-s3-demo-bucket/'
WITH (format = 'PARQUET', compression = 'ZSTD', compression_level = 4)
```
## 其他資源
+ *AWS 大數據部落格*中的[使用 Amazon Athena UNLOAD 特徵簡化 ETL 和 ML 管道](https://aws.amazon.com/blogs/big-data/simplify-your-etl-and-ml-pipelines-using-the-amazon-athena-unload-feature/)。
# Amazon Athena 中的函數
如需有關 Athena 引擎版本之間函式的變更，請參閱 [Athena 引擎版本控制](engine-versions.md)。如需可與 `AT TIME ZONE` 運算子搭配使用的時區清單，請參閱[使用支援的時區](athena-supported-time-zones.md)。
**Topics**
+ [Athena 引擎版本 3](functions-env3.md)
# Athena 引擎版本 3 函式
Athena 引擎版本 3 中的函數以 Trino 為基礎。如需有關 Trino 函數、運算子和表達式的資訊，請參閱 Trino 文件中的 [Functions and operators](https://trino.io/docs/current/functions.html) (函數和運算子)，以及以下具體子節。
+ [Aggregate](https://trino.io/docs/current/functions/aggregate.html)
+ [Array](https://trino.io/docs/current/functions/array.html) (陣列)
+ [：二進位](https://trino.io/docs/current/functions/binary.html)
+ [Bitwise](https://trino.io/docs/current/functions/bitwise.html) (位元)
+ [Color (顏色)](https://trino.io/docs/current/functions/color.html)
+ [Comparison](https://trino.io/docs/current/functions/comparison.html) (比較)
+ [有條件](https://trino.io/docs/current/functions/conditional.html)
+ [Conversion](https://trino.io/docs/current/functions/conversion.html) (轉換)
+ [日期和時間](https://trino.io/docs/current/functions/datetime.html)
+ [Decimal](https://trino.io/docs/current/functions/decimal.html) (小數)
+ [Geospatial](https://trino.io/docs/current/functions/geospatial.html) (地理空間)
+ [HyperLogLog](https://trino.io/docs/current/functions/hyperloglog.html)
+ [IP Address](https://trino.io/docs/current/functions/ipaddress.html) (IP 地址)
+ [JSON](https://trino.io/docs/current/functions/json.html)
+ [Lambda](https://trino.io/docs/current/functions/lambda.html)
+ [Logical](https://trino.io/docs/current/functions/logical.html) (邏輯)
+ [Machine learning](https://trino.io/docs/current/functions/ml.html) (機器學習)
+ [Map](https://trino.io/docs/current/functions/map.html)
+ [Math](https://trino.io/docs/current/functions/math.html)
+ [Quantile digest](https://trino.io/docs/current/functions/qdigest.html) (分位數摘要)
+ [Regular expression](https://trino.io/docs/current/functions/regexp.html) (常規表達式)
+ [Session](https://trino.io/docs/current/functions/session.html) (工作階段)
+ [Set Digest](https://trino.io/docs/current/functions/setdigest.html)
+ [：字串](https://trino.io/docs/current/functions/string.html)
+ [資料表](https://trino.io/docs/current/functions/table.html)
+ [Teradata](https://trino.io/docs/current/functions/teradata.html)
+ [T-Digest](https://trino.io/docs/current/functions/tdigest.html)
+ [URL](https://trino.io/docs/current/functions/url.html)
+ [UUID](https://trino.io/docs/current/functions/uuid.html)
+ [視窗](https://trino.io/docs/current/functions/window.html)
## invoker\$1principal() 函式
`invoker_principal` 函式是 Athena 引擎版本 3 所獨有的，Trino 中找不到該函式。
傳回包含主體 (IAM 角色或 Identity Center 身分) 的 ARN 的 `VARCHAR`，其中該主體可執行呼叫函式的查詢。例如，如果查詢調用者使用 IAM 角色的許可來執行查詢，則函式會傳回 IAM 角色的 ARN。執行查詢的角色必須允許 `LakeFormation:GetDataLakePrincipal` 動作。
### Usage
```
SELECT invoker_principal()
```
下列資料表會顯示範例結果。
****
| \$1 | \$1col0 |
| --- | --- |
| 1 | arn:aws:iam::111122223333:role/Admin |
# 使用支援的時區
您可以在 `SELECT timestamp` 陳述式中使用 `AT TIME ZONE` 運算子來指定傳回之時間戳記的時區，如以下範例所示：
```
SELECT timestamp '2012-10-31 01:00 UTC' AT TIME ZONE 'America/Los_Angeles' AS la_time;
```
**結果**
```
la_time
2012-10-30 18:00:00.000 America/Los_Angeles
```
如需 Athena 中支援的時區清單，請展開本主題結尾的 [支援的時區清單](#athena-supported-time-zones-list)。
## 時區函數和範例
以下是一些其他與時區相關的函數和範例。
+ **at\$1timezone(*timestamp*, *zone*)** – 傳回*區域*相應當地時間的*時間戳記*值。
**範例**
```
SELECT at_timezone(timestamp '2021-08-22 00:00 UTC', 'Canada/Newfoundland')
```
**結果**
```
2021-08-21 21:30:00.000 Canada/Newfoundland
```
+ **timezone\$1hour(*timestamp*)** – 以 `bigint` 傳回時區偏離時間戳記的小時數。
**範例**
```
SELECT timezone_hour(timestamp '2021-08-22 04:00 UTC' AT TIME ZONE 'Canada/Newfoundland')
```
**結果**
```
-2
```
+ **timezone\$1minute(*timestamp*)** – 以 `bigint` 傳回時區偏離*時間戳記*的分鐘數 。
**範例**
```
SELECT timezone_minute(timestamp '2021-08-22 04:00 UTC' AT TIME ZONE 'Canada/Newfoundland')
```
**結果**
```
-30
```
+ **with\$1timezone(*timestamp*, *zone*)** – 從指定的*時間戳記*和*區域*值傳回時間戳記和時區。
**範例**
```
SELECT with_timezone(timestamp '2021-08-22 04:00', 'Canada/Newfoundland')
```
**結果**
```
2021-08-22 04:00:00.000 Canada/Newfoundland
```
## 支援的時區清單
下列清單包含可搭配 Athena 中 `AT TIME ZONE` 運算子使用的時區。如需其他與時區相關的函數和範例，請參閱 [時區函數和範例](#athena-supported-time-zones-functions-examples)。
```
Africa/Abidjan
Africa/Accra
Africa/Addis_Ababa
Africa/Algiers
Africa/Asmara
Africa/Asmera
Africa/Bamako
Africa/Bangui
Africa/Banjul
Africa/Bissau
Africa/Blantyre
Africa/Brazzaville
Africa/Bujumbura
Africa/Cairo
Africa/Casablanca
Africa/Ceuta
Africa/Conakry
Africa/Dakar
Africa/Dar_es_Salaam
Africa/Djibouti
Africa/Douala
Africa/El_Aaiun
Africa/Freetown
Africa/Gaborone
Africa/Harare
Africa/Johannesburg
Africa/Juba
Africa/Kampala
Africa/Khartoum
Africa/Kigali
Africa/Kinshasa
Africa/Lagos
Africa/Libreville
Africa/Lome
Africa/Luanda
Africa/Lubumbashi
Africa/Lusaka
Africa/Malabo
Africa/Maputo
Africa/Maseru
Africa/Mbabane
Africa/Mogadishu
Africa/Monrovia
Africa/Nairobi
Africa/Ndjamena
Africa/Niamey
Africa/Nouakchott
Africa/Ouagadougou
Africa/Porto-Novo
Africa/Sao_Tome
Africa/Timbuktu
Africa/Tripoli
Africa/Tunis
Africa/Windhoek
America/Adak
America/Anchorage
America/Anguilla
America/Antigua
America/Araguaina
America/Argentina/Buenos_Aires
America/Argentina/Catamarca
America/Argentina/ComodRivadavia
America/Argentina/Cordoba
America/Argentina/Jujuy
America/Argentina/La_Rioja
America/Argentina/Mendoza
America/Argentina/Rio_Gallegos
America/Argentina/Salta
America/Argentina/San_Juan
America/Argentina/San_Luis
America/Argentina/Tucuman
America/Argentina/Ushuaia
America/Aruba
America/Asuncion
America/Atikokan
America/Atka
America/Bahia
America/Bahia_Banderas
America/Barbados
America/Belem
America/Belize
America/Blanc-Sablon
America/Boa_Vista
America/Bogota
America/Boise
America/Buenos_Aires
America/Cambridge_Bay
America/Campo_Grande
America/Cancun
America/Caracas
America/Catamarca
America/Cayenne
America/Cayman
America/Chicago
America/Chihuahua
America/Coral_Harbour
America/Cordoba
America/Costa_Rica
America/Creston
America/Cuiaba
America/Curacao
America/Danmarkshavn
America/Dawson
America/Dawson_Creek
America/Denver
America/Detroit
America/Dominica
America/Edmonton
America/Eirunepe
America/El_Salvador
America/Ensenada
America/Fort_Nelson
America/Fort_Wayne
America/Fortaleza
America/Glace_Bay
America/Godthab
America/Goose_Bay
America/Grand_Turk
America/Grenada
America/Guadeloupe
America/Guatemala
America/Guayaquil
America/Guyana
America/Halifax
America/Havana
America/Hermosillo
America/Indiana/Indianapolis
America/Indiana/Knox
America/Indiana/Marengo
America/Indiana/Petersburg
America/Indiana/Tell_City
America/Indiana/Vevay
America/Indiana/Vincennes
America/Indiana/Winamac
America/Indianapolis
America/Inuvik
America/Iqaluit
America/Jamaica
America/Jujuy
America/Juneau
America/Kentucky/Louisville
America/Kentucky/Monticello
America/Knox_IN
America/Kralendijk
America/La_Paz
America/Lima
America/Los_Angeles
America/Louisville
America/Lower_Princes
America/Maceio
America/Managua
America/Manaus
America/Marigot
America/Martinique
America/Matamoros
America/Mazatlan
America/Mendoza
America/Menominee
America/Merida
America/Metlakatla
America/Mexico_City
America/Miquelon
America/Moncton
America/Monterrey
America/Montevideo
America/Montreal
America/Montserrat
America/Nassau
America/New_York
America/Nipigon
America/Nome
America/Noronha
America/North_Dakota/Beulah
America/North_Dakota/Center
America/North_Dakota/New_Salem
America/Ojinaga
America/Panama
America/Pangnirtung
America/Paramaribo
America/Phoenix
America/Port-au-Prince
America/Port_of_Spain
America/Porto_Acre
America/Porto_Velho
America/Puerto_Rico
America/Punta_Arenas
America/Rainy_River
America/Rankin_Inlet
America/Recife
America/Regina
America/Resolute
America/Rio_Branco
America/Rosario
America/Santa_Isabel
America/Santarem
America/Santiago
America/Santo_Domingo
America/Sao_Paulo
America/Scoresbysund
America/Shiprock
America/Sitka
America/St_Barthelemy
America/St_Johns
America/St_Kitts
America/St_Lucia
America/St_Thomas
America/St_Vincent
America/Swift_Current
America/Tegucigalpa
America/Thule
America/Thunder_Bay
America/Tijuana
America/Toronto
America/Tortola
America/Vancouver
America/Virgin
America/Whitehorse
America/Winnipeg
America/Yakutat
America/Yellowknife
Antarctica/Casey
Antarctica/Davis
Antarctica/DumontDUrville
Antarctica/Macquarie
Antarctica/Mawson
Antarctica/McMurdo
Antarctica/Palmer
Antarctica/Rothera
Antarctica/South_Pole
Antarctica/Syowa
Antarctica/Troll
Antarctica/Vostok
Arctic/Longyearbyen
Asia/Aden
Asia/Almaty
Asia/Amman
Asia/Anadyr
Asia/Aqtau
Asia/Aqtobe
Asia/Ashgabat
Asia/Ashkhabad
Asia/Atyrau
Asia/Baghdad
Asia/Bahrain
Asia/Baku
Asia/Bangkok
Asia/Barnaul
Asia/Beirut
Asia/Bishkek
Asia/Brunei
Asia/Calcutta
Asia/Chita
Asia/Choibalsan
Asia/Chongqing
Asia/Chungking
Asia/Colombo
Asia/Dacca
Asia/Damascus
Asia/Dhaka
Asia/Dili
Asia/Dubai
Asia/Dushanbe
Asia/Gaza
Asia/Harbin
Asia/Hebron
Asia/Ho_Chi_Minh
Asia/Hong_Kong
Asia/Hovd
Asia/Irkutsk
Asia/Istanbul
Asia/Jakarta
Asia/Jayapura
Asia/Jerusalem
Asia/Kabul
Asia/Kamchatka
Asia/Karachi
Asia/Kashgar
Asia/Kathmandu
Asia/Katmandu
Asia/Khandyga
Asia/Kolkata
Asia/Krasnoyarsk
Asia/Kuala_Lumpur
Asia/Kuching
Asia/Kuwait
Asia/Macao
Asia/Macau
Asia/Magadan
Asia/Makassar
Asia/Manila
Asia/Muscat
Asia/Nicosia
Asia/Novokuznetsk
Asia/Novosibirsk
Asia/Omsk
Asia/Oral
Asia/Phnom_Penh
Asia/Pontianak
Asia/Pyongyang
Asia/Qatar
Asia/Qyzylorda
Asia/Rangoon
Asia/Riyadh
Asia/Saigon
Asia/Sakhalin
Asia/Samarkand
Asia/Seoul
Asia/Shanghai
Asia/Singapore
Asia/Srednekolymsk
Asia/Taipei
Asia/Tashkent
Asia/Tbilisi
Asia/Tehran
Asia/Tel_Aviv
Asia/Thimbu
Asia/Thimphu
Asia/Tokyo
Asia/Tomsk
Asia/Ujung_Pandang
Asia/Ulaanbaatar
Asia/Ulan_Bator
Asia/Urumqi
Asia/Ust-Nera
Asia/Vientiane
Asia/Vladivostok
Asia/Yakutsk
Asia/Yangon
Asia/Yekaterinburg
Asia/Yerevan
Atlantic/Azores
Atlantic/Bermuda
Atlantic/Canary
Atlantic/Cape_Verde
Atlantic/Faeroe
Atlantic/Faroe
Atlantic/Jan_Mayen
Atlantic/Madeira
Atlantic/Reykjavik
Atlantic/South_Georgia
Atlantic/St_Helena
Atlantic/Stanley
Australia/ACT
Australia/Adelaide
Australia/Brisbane
Australia/Broken_Hill
Australia/Canberra
Australia/Currie
Australia/Darwin
Australia/Eucla
Australia/Hobart
Australia/LHI
Australia/Lindeman
Australia/Lord_Howe
Australia/Melbourne
Australia/NSW
Australia/North
Australia/Perth
Australia/Queensland
Australia/South
Australia/Sydney
Australia/Tasmania
Australia/Victoria
Australia/West
Australia/Yancowinna
Brazil/Acre
Brazil/DeNoronha
Brazil/East
Brazil/West
CET
CST6CDT
Canada/Atlantic
Canada/Central
Canada/Eastern
Canada/Mountain
Canada/Newfoundland
Canada/Pacific
Canada/Saskatchewan
Canada/Yukon
Chile/Continental
Chile/EasterIsland
Cuba
EET
EST5EDT
Egypt
Eire
Europe/Amsterdam
Europe/Andorra
Europe/Astrakhan
Europe/Athens
Europe/Belfast
Europe/Belgrade
Europe/Berlin
Europe/Bratislava
Europe/Brussels
Europe/Bucharest
Europe/Budapest
Europe/Busingen
Europe/Chisinau
Europe/Copenhagen
Europe/Dublin
Europe/Gibraltar
Europe/Guernsey
Europe/Helsinki
Europe/Isle_of_Man
Europe/Istanbul
Europe/Jersey
Europe/Kaliningrad
Europe/Kiev
Europe/Kirov
Europe/Lisbon
Europe/Ljubljana
Europe/London
Europe/Luxembourg
Europe/Madrid
Europe/Malta
Europe/Mariehamn
Europe/Minsk
Europe/Monaco
Europe/Moscow
Europe/Nicosia
Europe/Oslo
Europe/Paris
Europe/Podgorica
Europe/Prague
Europe/Riga
Europe/Rome
Europe/Samara
Europe/San_Marino
Europe/Sarajevo
Europe/Simferopol
Europe/Skopje
Europe/Sofia
Europe/Stockholm
Europe/Tallinn
Europe/Tirane
Europe/Tiraspol
Europe/Ulyanovsk
Europe/Uzhgorod
Europe/Vaduz
Europe/Vatican
Europe/Vienna
Europe/Vilnius
Europe/Volgograd
Europe/Warsaw
Europe/Zagreb
Europe/Zaporozhye
Europe/Zurich
GB
GB-Eire
Hongkong
Iceland
Indian/Antananarivo
Indian/Chagos
Indian/Christmas
Indian/Cocos
Indian/Comoro
Indian/Kerguelen
Indian/Mahe
Indian/Maldives
Indian/Mauritius
Indian/Mayotte
Indian/Reunion
Iran
Israel
Jamaica
Japan
Kwajalein
Libya
MET
MST7MDT
Mexico/BajaNorte
Mexico/BajaSur
Mexico/General
NZ
NZ-CHAT
Navajo
PRC
PST8PDT
Pacific/Apia
Pacific/Auckland
Pacific/Bougainville
Pacific/Chatham
Pacific/Chuuk
Pacific/Easter
Pacific/Efate
Pacific/Enderbury
Pacific/Fakaofo
Pacific/Fiji
Pacific/Funafuti
Pacific/Galapagos
Pacific/Gambier
Pacific/Guadalcanal
Pacific/Guam
Pacific/Honolulu
Pacific/Johnston
Pacific/Kiritimati
Pacific/Kosrae
Pacific/Kwajalein
Pacific/Majuro
Pacific/Marquesas
Pacific/Midway
Pacific/Nauru
Pacific/Niue
Pacific/Norfolk
Pacific/Noumea
Pacific/Pago_Pago
Pacific/Palau
Pacific/Pitcairn
Pacific/Pohnpei
Pacific/Ponape
Pacific/Port_Moresby
Pacific/Rarotonga
Pacific/Saipan
Pacific/Samoa
Pacific/Tahiti
Pacific/Tarawa
Pacific/Tongatapu
Pacific/Truk
Pacific/Wake
Pacific/Wallis
Pacific/Yap
Poland
Portugal
ROK
Singapore
Turkey
US/Alaska
US/Aleutian
US/Arizona
US/Central
US/East-Indiana
US/Eastern
US/Hawaii
US/Indiana-Starke
US/Michigan
US/Mountain
US/Pacific
US/Pacific-New
US/Samoa
W-SU
WET
```
# DDL 陳述式
直接在 Athena 中使用此處顯示的支援的資料定義語言 (DDL) 陳述式。Athena 查詢引擎部分以 [HiveQL DDL](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+DDL) 為基礎。Athena 不支援所有 DDL 陳述式，而且 HiveQL DDL 和 Athena DDL 之間有一些差異。如需詳細資訊，請參閱本節中的參考主題和[不支援的 DDL](unsupported-ddl.md)。
**Topics**
+ [不支援的 DDL](unsupported-ddl.md)
+ [ALTER DATABASE SET DBPROPERTIES](alter-database-set-dbproperties.md)
+ [ALTER TABLE ADD COLUMNS](alter-table-add-columns.md)
+ [ALTER TABLE ADD PARTITION](alter-table-add-partition.md)
+ [ALTER TABLE CHANGE COLUMN](alter-table-change-column.md)
+ [ALTER TABLE DROP PARTITION](alter-table-drop-partition.md)
+ [ALTER TABLE RENAME PARTITION](alter-table-rename-partition.md)
+ [ALTER TABLE REPLACE COLUMNS](alter-table-replace-columns.md)
+ [ALTER TABLE SET LOCATION](alter-table-set-location.md)
+ [ALTER TABLE SET TBLPROPERTIES](alter-table-set-tblproperties.md)
+ [變更檢視方言](alter-view-dialect.md)
+ [CREATE DATABASE](create-database.md)
+ [CREATE TABLE](create-table.md)
+ [CREATE TABLE AS](create-table-as.md)
+ [CREATE VIEW](create-view.md)
+ [DESCRIBE](describe-table.md)
+ [DESCRIBE VIEW](describe-view.md)
+ [DROP DATABASE](drop-database.md)
+ [DROP TABLE](drop-table.md)
+ [DROP VIEW](drop-view.md)
+ [MSCK REPAIR TABLE](msck-repair-table.md)
+ [SHOW COLUMNS](show-columns.md)
+ [SHOW CREATE TABLE](show-create-table.md)
+ [SHOW CREATE VIEW](show-create-view.md)
+ [SHOW DATABASES](show-databases.md)
+ [SHOW PARTITIONS](show-partitions.md)
+ [SHOW TABLES](show-tables.md)
+ [SHOW TBLPROPERTIES](show-tblproperties.md)
+ [SHOW VIEWS](show-views.md)
# 不支援的 DDL
Athena SQL 不支援下列 DDL 陳述式。如需 Athena 中 Iceberg 資料表支援的 DDL 陳述式，請參閱 [演進 Iceberg 資料表結構描述](querying-iceberg-evolving-table-schema.md) 和 [在 Iceberg 資料表上執行其他 DDL 操作](querying-iceberg-additional-operations.md)。
+ ALTER INDEX
+ ALTER TABLE *table\$1name* ARCHIVE PARTITION
+ ALTER TABLE *table\$1name* CLUSTERED BY
+ ALTER TABLE *table\$1name* DROP COLUMN (支援 Iceberg 資料表)
+ ALTER TABLE *table\$1name* EXCHANGE PARTITION
+ ALTER TABLE *table\$1name* CLUSTERED BY
+ ALTER TABLE *table\$1name* NOT SKEWED
+ ALTER TABLE *table\$1name* NOT SORTED
+ ALTER TABLE *table\$1name* NOT STORED AS DIRECTORIES
+ ALTER TABLE *table\$1name* partitionSpec CHANGE COLUMNS
+ ALTER TABLE *table\$1name* partitionSpec COMPACT
+ ALTER TABLE *table\$1name* partitionSpec CONCATENATE
+ ALTER TABLE *table\$1name* partitionSpec SET FILEFORMAT
+ ALTER TABLE *table\$1name* RENAME TO (支援 Iceberg 資料表)
+ ALTER TABLE*table\$1name*設定服務器屬性
+ ALTER TABLE *table\$1name* SET SKEWED LOCATION
+ ALTER TABLE *table\$1name* SKEWED BY
+ ALTER TABLE *table\$1name* TOUCH
+ ALTER TABLE *table\$1name* UNARCHIVE PARTITION
+ COMMIT
+ CREATE INDEX
+ CREATE ROLE
+ CREATE TABLE *table\$1name* LIKE *existing\$1table\$1name*
+ CREATE TEMPORARY MACRO
+ DELETE FROM
+ DESCRIBE DATABASE
+ DFS
+ DROP INDEX
+ DROP ROLE
+ DROP TEMPORARY MACRO
+ EXPORT TABLE
+ GRANT ROLE
+ IMPORT TABLE
+ LOCK DATABASE
+ LOCK TABLE
+ REVOKE ROLE
+ ROLLBACK
+ SHOW COMPACTIONS
+ SHOW CURRENT ROLES
+ SHOW GRANT
+ SHOW INDEXES
+ SHOW LOCKS
+ SHOW PRINCIPALS
+ SHOW ROLE GRANT
+ SHOW ROLES
+ SHOW STATS
+ SHOW TRANSACTIONS
+ START TRANSACTION
+ UNLOCK DATABASE
+ UNLOCK TABLE
# ALTER DATABASE SET DBPROPERTIES
為資料庫建立一或多個屬性。`DATABASE` 和 `SCHEMA` 可互換使用，兩者的意義相同。
## 概要
```
ALTER {DATABASE|SCHEMA} database_name
SET DBPROPERTIES ('property_name'='property_value' [, ...] )
```
## Parameters
**SET DBPROPERTIES ('property\$1name'='property\$1value' [, ...]**
指定名為 `property_name` 之資料庫的一或多個屬性，並以 `property_value` 分別為每個屬性建立值。如果 `property_name` 已存在，`property_value` 會覆寫舊值。
## 範例
```
ALTER DATABASE jd_datasets
SET DBPROPERTIES ('creator'='John Doe', 'department'='applied mathematics');
```
```
ALTER SCHEMA jd_datasets
SET DBPROPERTIES ('creator'='Jane Doe');
```
# ALTER TABLE ADD COLUMNS
將一個或多個資料欄新增至現有資料表中。使用選用的 `PARTITION` 語法時，會更新分割區中繼資料。
## 概要
```
ALTER TABLE table_name
[PARTITION
(partition_col1_name = partition_col1_value
[,partition_col2_name = partition_col2_value][,...])]
ADD COLUMNS (col_name data_type)
```
## Parameters
**PARTITION (partition\$1col\$1name = partition\$1col\$1value [,...])**
使用您指定的資料欄名稱/值組合來建立分割區。只有當資料欄的資料類型為字串時，才需要用引號括住 `partition_col_value`。
**ADD COLUMNS (col\$1name data\$1type [,col\$1name data\$1type,...])**
將資料行新增在現有資料欄之後，但在分割區資料欄之前。
## 範例
```
ALTER TABLE events ADD COLUMNS (eventowner string)
```
```
ALTER TABLE events PARTITION (awsregion='us-west-2') ADD COLUMNS (event string)
```
```
ALTER TABLE events PARTITION (awsregion='us-west-2') ADD COLUMNS (eventdescription string)
```
## 備註
+ 若要於執行 `ALTER TABLE ADD COLUMNS` 之後在 Athena 查詢編輯器導覽窗格中查看新資料表資料欄，請手動重新整理編輯器中的資料表清單，然後再次展開資料表。
+ `ALTER TABLE ADD COLUMNS` 不適用於具有 `date` 資料類型的資料欄。若要解決這個問題，請轉為使用 `timestamp` 資料類型。
# ALTER TABLE ADD PARTITION
為資料表建立一或多個分割區欄。每個分割區由一或多個不同的欄名稱/值組合組成。每種指定的組合都會另外建立一個資料目錄，這樣可在某些情況下改善查詢效能。分割區的欄本身不存在於資料表的資料中，因此，如果您使用的分割區欄名稱和資料表中的欄名稱相同，就會發生錯誤。如需詳細資訊，請參閱[分割您的資料](partitions.md)。
在 Athena 中，資料表及其分割區必須使用相同的資料格式，但其結構描述可能不同。如需詳細資訊，請參閱[更新含有分割區的資料表](updates-and-partitions.md)。
如需有關 IAM 政策中所需資源層級許可的資訊 (包括 `glue:CreatePartition`)，請參閱《[AWS Glue API 許可：動作和資源參考](https://docs.aws.amazon.com/glue/latest/dg/api-permissions-reference.html)》以及 [在 中設定資料庫和資料表的存取權 AWS Glue Data Catalog](fine-grained-access-to-glue-resources.md)。如需有關使用 Athena 時許可的疑難排解資訊，請參閱 [對 Athena 中的問題進行疑難排解](troubleshooting-athena.md) 主題的 [許可](troubleshooting-athena.md#troubleshooting-athena-permissions) 章節。
## 概要
```
ALTER TABLE table_name ADD [IF NOT EXISTS]
PARTITION
(partition_col1_name = partition_col1_value
[,partition_col2_name = partition_col2_value]
[,...])
[LOCATION 'location1']
[PARTITION
(partition_colA_name = partition_colA_value
[,partition_colB_name = partition_colB_value
[,...])]
[LOCATION 'location2']
[,...]
```
## Parameters
當新增分割區時，您可以為分割區指定一或多個資料欄名稱/值組，以及該分割區的資料檔案所在的 Simple Storage Service (Amazon S3) 路徑。
**[IF NOT EXISTS]**
如果已有相同定義的分割區，則會造成錯誤隱藏。
**PARTITION (partition\$1col\$1name = partition\$1col\$1value [,...])**
使用您指定的資料欄名稱/值組合來建立分割區。只有當欄的資料類型是字串時，才需要以字串字元圍住 `partition_col_value`。
**[LOCATION 'location']**
指定目錄，將在其中存放先前陳述式定義的分割區。當資料使用 Hive 樣式分割 (`pk1=v1/pk2=v2/pk3=v3`) 時，`LOCATION` 子句為選用的。使用 Hive 樣式分割時，會從資料表的位置、分割區索引鍵名稱和分割區索引鍵值自動建構完整的 Amazon S3 URI。如需詳細資訊，請參閱[分割您的資料](partitions.md)。
## 考量事項
對您可以在單一 `ALTER TABLE ADD PARTITION` DDL 陳述式中新增的分割區數量，Amazon Athena 不會施加特定限制。不過，如果您需要新增大量分割區，請考慮將操作分成較小的批次，以避免潛在的效能問題。下列範例使用連續命令來個別新增分割區，並使用 `IF NOT EXISTS` 來避免新增重複項目。
```
ALTER TABLE table_name ADD IF NOT EXISTS PARTITION (ds='2023-01-01')
ALTER TABLE table_name ADD IF NOT EXISTS PARTITION (ds='2023-01-02')
ALTER TABLE table_name ADD IF NOT EXISTS PARTITION (ds='2023-01-03')
```
在 Athena 中使用分割區時，也請謹記以下幾點：
+ 雖然 Athena 支援查詢具有 1，000 萬個分割區的 AWS Glue 資料表，但 Athena 無法在單一掃描中讀取超過 100 萬個分割區。
+ 若要最佳化查詢並減少掃描的分割區數量，請考慮分割區剔除或使用分割區索引等策略。
如需有關在 Athena 中使用分割區的其他考量事項，請參閱 [分割您的資料](partitions.md)。
## 範例
下列範例會將單一分割區新增至資料表，以取得 HIVE 樣式分割資料。
```
ALTER TABLE orders ADD
PARTITION (dt = '2016-05-14', country = 'IN');
```
下列範例會將多個分割區新增至資料表，以取得 HIVE 樣式分割資料。
```
ALTER TABLE orders ADD
PARTITION (dt = '2016-05-31', country = 'IN')
PARTITION (dt = '2016-06-01', country = 'IN');
```
如果資料表不適用於 HIVE 樣式的分割資料，則 `LOCATION` 子句是必需的，且應該是包含分割區資料之字首的完整 Amazon S3 URI。
```
ALTER TABLE orders ADD
PARTITION (dt = '2016-05-31', country = 'IN') LOCATION 's3://amzn-s3-demo-bucket/path/to/INDIA_31_May_2016/'
PARTITION (dt = '2016-06-01', country = 'IN') LOCATION 's3://amzn-s3-demo-bucket/path/to/INDIA_01_June_2016/';
```
若要在分割區已存在時忽略錯誤，請使用 `IF NOT EXISTS` 子句，如下列範例所示。
```
ALTER TABLE orders ADD IF NOT EXISTS
PARTITION (dt = '2016-05-14', country = 'IN');
```
## 零位元組 `_$folder$` 檔案
如果您執行 `ALTER TABLE ADD PARTITION` 語句並錯誤地指定已存在的分區和不正確的 Simple Storage Service (Amazon S3) 位置，則格式為 `partition_value_$folder$` 的零位元組預留位置檔案會在 Simple Storage Service (Amazon S3) 中建立。您必須手動移除這些檔案。
若要防止這種情況發生，請使用 `ALTER TABLE ADD PARTITION` 陳述式中的 `ADD IF NOT EXISTS` 語法，如下列範例所示。
```
ALTER TABLE table_name ADD IF NOT EXISTS PARTITION […]
```
# ALTER TABLE CHANGE COLUMN
變更資料表中資料欄的名稱、類型、順序或註解。
## 概要
```
ALTER TABLE [db_name.]table_name
CHANGE [COLUMN] col_old_name col_new_name column_type
[COMMENT col_comment] [FIRST|AFTER column_name]
```
## 範例
下列範例會將資料欄名稱 `area` 變更為 `zip`，使資料類型轉換為整數，並將重新命名的資料欄放置在 `id` 資料欄之後。
```
ALTER TABLE example_table CHANGE COLUMN area zip int AFTER id
```
下列範例會將註解新增至 `example_table` 的中繼資料中的 `zip` 資料欄。若要查看註解，請使用 AWS CLI [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/athena/get-table-metadata.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/athena/get-table-metadata.html) 命令或瀏覽 AWS Glue 主控台中資料表的結構描述。
```
ALTER TABLE example_table CHANGE COLUMN zip zip int COMMENT 'USA zipcode'
```
# ALTER TABLE DROP PARTITION
捨棄指定資料表的一或多個指定分割區。
## 概要
```
ALTER TABLE table_name DROP [IF EXISTS] PARTITION (partition_spec) [, PARTITION (partition_spec)]
```
## Parameters
**[IF EXISTS]**
如果指定的分割區不存在，會造成錯誤訊息隱藏。
**PARTITION (partition\$1spec)**
每個 `partition_spec` 會以 `partition_col_name = partition_col_value [,...]` 的形式指定一個資料欄名稱/值組合。
## 範例
```
ALTER TABLE orders
DROP PARTITION (dt = '2014-05-14', country = 'IN');
```
```
ALTER TABLE orders
DROP PARTITION (dt = '2014-05-14', country = 'IN'), PARTITION (dt = '2014-05-15', country = 'IN');
```
## 備註
`ALTER TABLE DROP PARTITION` 陳述式不會提供單一語法來一次捨棄所有分割區，或支援篩選條件來指定要捨棄的分割區範圍。
作為解決方法，您可以在指令碼中使用 AWS Glue API [GetPartitions](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-catalog-partitions.html#aws-glue-api-catalog-partitions-GetPartitions) 和 [BatchDeletePartition](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-catalog-partitions.html#aws-glue-api-catalog-partitions-BatchDeletePartition) 動作。`GetPartitions` 動作支援類似於 SQL `WHERE` 表達式中的複雜篩選條件表達式。使用 `GetPartitions` 建立要刪除的分割區篩選清單後，您可以使用 `BatchDeletePartition` 動作以刪除以 25 為單位批次的分割區。
# ALTER TABLE RENAME PARTITION
重新命名分割區值。
**注意**
ALTER TABLE RENAME PARTITION 不會重新命名分割區資料欄。若要變更分割區資料欄名稱，您可以使用 AWS Glue 主控台。如需詳細資訊，請參閱本文件稍後的[在 中重新命名分割區資料欄 AWS Glue](#alter-table-rename-partition-column-name)。
## 概要
對於名為 `table_name` 的資料表，將 `partition_spec` 指定的分割區值重新命名為 `new_partition_spec` 指定的值。
```
ALTER TABLE table_name PARTITION (partition_spec) RENAME TO PARTITION (new_partition_spec)
```
## Parameters
**PARTITION (partition\$1spec)**
每個 `partition_spec` 會以 `partition_col_name = partition_col_value [,...]` 的形式指定一個資料欄名稱/值組合。
## 範例
```
ALTER TABLE orders
PARTITION (dt = '2014-05-14', country = 'IN') RENAME TO PARTITION (dt = '2014-05-15', country = 'IN');
```
## 在 中重新命名分割區資料欄 AWS Glue
使用下列程序，在 AWS Glue 主控台中重新命名分割區資料欄名稱。
**在 AWS Glue 主控台中重新命名資料表分割區欄**
1. 登入 AWS 管理主控台 並在 https：//[https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/) 開啟 AWS Glue 主控台。
1. 在導覽窗格中，選擇 **Tables** (資料表)。
1. 在**資料表**頁面上，使用**篩選資料表**搜尋方塊，尋找您要變更的資料表。
1. 在**名稱**資料欄中，選擇您要變更的資料表的連結。
1. 在資料表的詳細資訊頁面，於**結構描述**區段中，執行下列其中一項動作：
+ 若要以 JSON 格式變更名稱，請選擇**以 JSON 格式編輯結構**。
+ 若要直接變更名稱，請選擇**編輯結構描述**。此程序選擇**編輯結構描述**。
1. 選取您要重新命名的分割資料欄的核取方塊，然後選擇**編輯**。
1. 在**編輯結構描述項目**對話方塊中，針對**名稱**，輸入分割區資料欄的新名稱。
1. 選擇**另存為新的資料表版本**。此動作會更新分割區資料欄名稱，並保留結構描述演變歷史記錄，而不會建立資料的單獨實體副本。
1. 若要比較資料表版本，請在資料表的詳細資訊頁面上，選擇**動作**，然後選擇**比較版本**。
## 其他資源
如需有關分割區的詳細資訊，請參閱 [分割您的資料](partitions.md)。
# ALTER TABLE REPLACE COLUMNS
從透過 [LazySimpleSerDe](lazy-simple-serde.md) 建立的資料表中移除所有現有的資料欄，並用指定的一組資料欄取代它們。使用選用的 `PARTITION` 語法時，會更新分割區中繼資料。您也可以使用 `ALTER TABLE REPLACE COLUMNS` 透過僅指定您想要保留的資料欄來刪除其他資料欄。
## 概要
```
ALTER TABLE table_name
[PARTITION
(partition_col1_name = partition_col1_value
[,partition_col2_name = partition_col2_value][,...])]
REPLACE COLUMNS (col_name data_type [, col_name data_type, ...])
```
## Parameters
**PARTITION (partition\$1col\$1name = partition\$1col\$1value [,...])**
以您指定的資料欄名稱/值組合來指定分割區。只有當資料欄的資料類型為字串時，才需要用引號括住 `partition_col_value`。
**REPLACE COLUMNS (col\$1name data\$1type [,col\$1name data\$1type,...])**
以指定的資料欄名稱和資料類型取代現有資料欄。
## 備註
+ 如需在執行 `ALTER TABLE REPLACE COLUMNS` 之後，查看 Athena 查詢編輯器導覽窗格中的資料表資料表欄位變更，請手動重新整理編輯器中的資料表清單，然後再次展開資料表。
+ `ALTER TABLE REPLACE COLUMNS` 不適用於具有 `date` 資料類型的資料欄。若要解決這個問題，請轉為使用資料表中的 `timestamp` 資料類型。
+ 請注意，即使您只取代單一資料欄，語法必須是 `ALTER TABLE table-name REPLACE COLUMNS`，以及複數形式的*資料欄*。您不僅必須指定要取代的資料欄，還必須指定要保留的資料欄 – 如果不是，您未指定的資料欄將會遭到捨棄。這種語法和行為從 Apache Hive DDL 衍生。如需參考，請參閱 Apache 文件中的[新增/取代資料欄](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+DDL#LanguageManualDDL-Add/ReplaceColumns)。
## 範例
在下列範例中，資料表 `names_cities` 是使用 [LazySimpleSerDe](lazy-simple-serde.md) 所建立的，並有三個名為 `col1`、`col2` 和 `col3` 的資料欄。所有資料欄均為 `string` 類型。若要顯示資料表中的資料欄，下列命令會使用 [SHOW COLUMNS](show-columns.md) 陳述式。
```
SHOW COLUMNS IN names_cities
```
查詢的結果：
```
col1
col2
col3
```
下列 `ALTER TABLE REPLACE COLUMNS` 命令將資料欄名稱取代為 `first_name`、`last_name` 和 `city`。基礎來源資料不受影響。
```
ALTER TABLE names_cities
REPLACE COLUMNS (first_name string, last_name string, city string)
```
若要測試結果，請重新執行 `SHOW COLUMNS`。
```
SHOW COLUMNS IN names_cities
```
查詢的結果：
```
first_name
last_name
city
```
顯示新資料欄名稱的另一種方法是在 Athena 查詢編輯器中[預覽資料表](creating-tables-showing-table-information.md)，或執行您自己的 `SELECT` 查詢。
# ALTER TABLE SET LOCATION
變更名為 `table_name` 之資料表的位置，以及 (選擇性) 含 `partition_spec` 的分割區。
## 概要
```
ALTER TABLE table_name [ PARTITION (partition_spec) ] SET LOCATION 'new location'
```
## Parameters
**PARTITION (partition\$1spec)**
以 `partition_spec` 參數指定您想要變更位置的分割區。`partition_spec` 以 `partition_col_name = partition_col_value` 的形式指定一個欄名稱/值組合。
**SET LOCATION 'new location'**
指定新的位置，其必須是 Amazon S3 位置。如需有關語法的資訊，請參閱 [Amazon S3 中的資料表位置](tables-location-format.md)。
## 範例
```
ALTER TABLE customers PARTITION (zip='98040', state='WA') SET LOCATION 's3://amzn-s3-demo-bucket/custdata/';
```
# ALTER TABLE SET TBLPROPERTIES
將自訂或預定義的中繼資料屬性新增到資料表中，並設定他們的指派值。若要查看資料表中的屬性，請使用 [SHOW TBLPROPERTIES](show-tblproperties.md) 命令。
由於不支援 Apache Hive [受管資料表](https://cwiki.apache.org/confluence/display/Hive/Managed+vs.+External+Tables)，設定 `'EXTERNAL'='FALSE'` 不會有任何作用。
## 概要
```
ALTER TABLE table_name SET TBLPROPERTIES ('property_name' = 'property_value' [ , ... ])
```
## Parameters
**SET TBLPROPERTIES ('property\$1name' = 'property\$1value' [ , ... ])**
指定以 `property_name` 新增的中繼資料屬性，以及以 `property value` 新增的個別值。如果 `property_name` 已存在，它的值會設定為新指定的 `property_value`。
下列預先定義的資料表屬性有特殊用途。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/alter-table-set-tblproperties.html)
## 範例
下列範例會將註解附註新增至資料表屬性。
```
ALTER TABLE orders
SET TBLPROPERTIES ('notes'="Please don't drop this table.");
```
下列範例會修改資料表 `existing_table`，以使用具有 ZSTD 壓縮和 ZSTD 壓縮級別 4 的 Parquet 檔案格式。
```
ALTER TABLE existing_table
SET TBLPROPERTIES ('parquet.compression' = 'ZSTD', 'compression_level' = 4)
```
# 變更檢視方言
從 AWS Glue Data Catalog 檢視新增或捨棄引擎方言。僅適用於 AWS Glue Data Catalog 檢視。需要 `Lake Formation` 管理員或定義程式許可。
如需 AWS Glue Data Catalog 檢視的詳細資訊，請參閱 [在 Athena 中使用 Data Catalog 檢視](views-glue.md)。
## 語法
```
ALTER VIEW name [ FORCE ] [ ADD|UPDATE ] DIALECT AS query
```
```
ALTER VIEW name [ DROP ] DIALECT
```
**FORCE**
`FORCE` 關鍵字會導致檢視中的衝突性引擎方言資訊被新的定義覆寫。當 Data Catalog 檢視更新導致現有引擎方言具有衝突性檢視定義時，`FORCE` 關鍵字非常有用。假設 Data Catalog 檢視同時具有 Athena 和 Amazon Redshift 方言，而且更新會導致檢視定義中與 Amazon Redshift 方言發生衝突。在此情況下，您可使用 `FORCE` 關鍵字允許更新完成，並將 Amazon Redshift 方言標記為過時。當引擎標記為過時查詢檢視時，查詢會失敗。引擎擲回例外狀況，以禁止過時的結果。若要更正此問題，請更新檢視中過時的方言。
**ADD**
將新引擎方言新增至 Data Catalog 檢視。指定的引擎不得存在於 Data Catalog 檢視中。
**UPDATE**
更新 Data Catalog 檢視中已存在的引擎方言。
**DROP**
從 Data Catalog 檢視中捨棄現有的引擎方言。從 Data Catalog 檢視中捨棄引擎後，捨棄的引擎無法查詢 Data Catalog 檢視。檢視中的其他引擎方言仍可查詢檢視。
**DIALECT AS**
引入引擎特定的 SQL 查詢。
## 範例
```
ALTER VIEW orders_by_date FORCE ADD DIALECT
AS
SELECT orderdate, sum(totalprice) AS price
FROM orders
GROUP BY orderdate
```
```
ALTER VIEW orders_by_date FORCE UPDATE DIALECT
AS
SELECT orderdate, sum(totalprice) AS price
FROM orders
GROUP BY orderdate
```
```
ALTER VIEW orders_by_date DROP DIALECT
```
# CREATE DATABASE
建立資料庫。`DATABASE` 和 `SCHEMA` 可互換使用。它們的意義相同。
**注意**
如需在 Athena 建立資料庫、建立資料表和執行資料表 `SELECT` 查詢的範例，請參閱 [開始使用](getting-started.md)。
## 概要
```
CREATE {DATABASE|SCHEMA} [IF NOT EXISTS] database_name
[COMMENT 'database_comment']
[LOCATION 'S3_loc']
[WITH DBPROPERTIES ('property_name' = 'property_value') [, ...]]
```
有關 Athena 中資料庫名稱的限制，請參閱 [為資料庫、資料表和資料欄命名](tables-databases-columns-names.md)。
## Parameters
**[IF NOT EXISTS]**
如果名為 `database_name` 的資料表已存在，會造成錯誤隱藏。
**[COMMENT database\$1comment]**
為名為 `comment` 的內建中繼資料屬性以及您為 `database_comment` 提供的值，建立中繼資料值。在 中 AWS Glue，`COMMENT`內容會寫入資料庫屬性的 `Description` 欄位。
**[LOCATION S3\$1loc]**
以 `S3_loc` 指定資料庫檔案和中繼存放區將存在的位置。此位置必須是 Amazon S3 位置。
**[WITH DBPROPERTIES ('property\$1name' = 'property\$1value') [, ...] ]**
可讓您指定資料庫定義的自訂中繼資料屬性。
## 範例
```
CREATE DATABASE clickstreams;
```
```
CREATE DATABASE IF NOT EXISTS clickstreams
COMMENT 'Site Foo clickstream data aggregates'
LOCATION 's3://amzn-s3-demo-bucket/clickstreams/'
WITH DBPROPERTIES ('creator'='Jane D.', 'Dept.'='Marketing analytics');
```
## 檢視資料庫屬性
若要使用 檢視您在 AWSDataCatalog 中建立之資料庫的資料庫屬性`CREATE DATABASE`，您可以使用 AWS CLI 命令 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/get-database.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/get-database.html)，如下列範例所示：
```
aws glue get-database --name
```
在 JSON 輸出中，其結果看起來如下：
```
{
"Database": {
"Name": "",
"Description": "",
"LocationUri": "s3://amzn-s3-demo-bucket",
"Parameters": {
"