# Amazon Athena 上的 Apache Spark 入门
<a name="notebooks-spark-getting-started"></a>

**注意**  
对于 Apache Spark 3.5 发行版，请按照 [SageMaker 笔记本](https://docs.amazonaws.cn/sagemaker-unified-studio/latest/userguide/what-is-sagemaker-unified-studio.html)中的入门指南进行操作。对 Pyspark 引擎 3 发行版使用本指南。

要开始在 Amazon Athena 上使用 Apache Spark，您必须先创建一个支持 Spark 的工作组。切换到工作组后，您可以创建笔记本或打开现有笔记本。打开 Athena 中的笔记本后，会自动为其启动一个新会话，您可以直接在 Athena 笔记本编辑器中进行处理。

**注意**  
在尝试创建笔记本之前，请务必创建启用 Spark 的工作组。

## 步骤 1：在 Athena 中创建启用 Spark 的工作组
<a name="notebooks-spark-getting-started-creating-a-spark-enabled-workgroup"></a>

您可以在 Athena 中使用[工作组](workgroups-manage-queries-control-costs.md)对用户、团队、应用程序或工作负载进行分组，并跟踪成本。要在 Amazon Athena 中使用 Apache Spark，您需要创建一个使用 Spark 引擎的 Amazon Athena 工作组。

**注意**  
启用 Apache Spark 的工作组可以使用 Athena 笔记本编辑器，但不能使用 Athena 查询编辑器。只有 Athena SQL 工作组可以使用 Athena 查询编辑器。

**在 Athena 中创建启用 Spark 的工作组**

1. 打开 Athena 控制台，网址为 [https://console.aws.amazon.com/athena/](https://console.amazonaws.cn/athena/home)。

1. 如果控制台导航窗格不可见，请选择左侧的扩展菜单。  
![\[选择扩展菜单。\]](http://docs.amazonaws.cn/athena/latest/ug/images/nav-pane-expansion.png)

1. 在导航窗格中，选择 **Workgroups**（工作组）。

1. 在 **Workgroups**（工作组）页面中，选择 **Create workgroup**（创建工作组）。

1. 在 **Workgroup name**（工作组名称）中，输入您的 Apache Spark 工作组名称。

1. （可选）对于 **Description**（描述），输入工作组的描述。

1. 对于 **Analytics engine**（分析引擎），选择 **Apache Spark**。
**注意**  
创建工作组后，无法更改工作组的分析引擎类型。例如，无法将 Athena 引擎版本 3 工作组更改为 PySpark 引擎版本 3 工作组。

1. 在本教程中，请选择 **Turn on example notebook**（打开示例笔记本）。此可选功能将向工作组添加名为 `example-notebook-random_string` 的示例笔记本，并添加笔记本用于在账户中创建、显示和删除特定数据库和表的 Amazon Glue 相关权限，并在 Amazon S3 中添加示例数据集的读取权限。要查看添加的权限，请选择 **View additional permissions details**（查看其他权限详细信息）。
**注意**  
 运行示例笔记本可能会产生一些额外费用。

1. 对于**计算结果设置**，请从以下选项中进行选择：
   + **创建新的 S3 存储桶** – 此选项会在账户中为计算结果创建 Amazon S3 存储桶。存储桶名称的格式为 `account_id-region-athena-results-bucket-alphanumeric_id`，使用的设置为：禁用 ACL、阻止公有访问、禁用版本控制和强制存储桶拥有者。
   + **选择现有 S3 位置** – 对于此选项，请执行以下操作：
     + 在搜索框中输入一个现有位置的 S3 路径，或选择 **Browse S3**（浏览 S3）以从列表中选择一个存储桶。
**注意**  
在 Amazon S3 中选择现有位置时，请勿向该位置附加正斜杠 (`/`)。这样操作会导致指向 [calculation details page](#notebooks-spark-getting-started-viewing-session-and-calculation-details)（计算详细信息页面）上计算结果位置的链接指向错误的目录。如果出现这种情况，请编辑工作组的结果位置以删除尾部正斜杠。
     + （可选）选择 **View**（查看）以打开 Amazon S3 控制台的 **Buckets**（存储桶）页面，您可以在其中查看有关所选现有存储桶的更多信息。
     + （可选）在 **Expected bucket owner**（预期存储桶拥有者）中，输入您希望其成为查询结果输出位置存储桶拥有者的 Amazon 账户 ID。建议您尽可能选择此选项作为额外的安全措施。如果存储桶拥有者的账户 ID 与您指定的 ID 不匹配，则输出到存储桶的尝试将会失败。有关更多信息，请参阅《*Amazon S3 用户指南*》中的[使用存储桶拥有者条件验证存储桶所有权](https://docs.amazonaws.cn/AmazonS3/latest/userguide/bucket-owner-condition.html) 
     + （可选）如果您的计算结果位置属于其他账户所有，并且您希望向其他账户授予对查询结果的完全控制权，请选择 **Assign bucket owner full control over query results**（为存储桶拥有者分配对查询结果的完全控制权）。

1. （可选）如果要加密查询结果，则选择**加密查询结果**。
   + 对于**加密类型**，选择下列选项之一：
     + **SSE\$1S3**：此选项使用具有 Amazon S3 托管加密密钥的服务器端加密（SSE）。
     + **SSE\$1KMS**：此选项使用具有 Amazon KMS 托管密钥的服务器端加密（SSE）。

       要**选择 Amazon KMS 密钥**，请选择以下选项之一。
       + **使用 Amazon 拥有的密钥**：Amazon KMS 密钥由 Amazon 拥有和管理。使用此密钥不会产生额外的费用。
       + **选择其他 Amazon KMS 密钥（高级）**：对于此选项，请执行以下操作之一：
         + 要使用现有密钥，请使用搜索框选择 Amazon KMS 或输入密钥 ARN。
         + 要在 Amazon KMS 控制台中创建密钥，选择**创建 Amazon KMS 密钥**。执行角色必须具有使用您创建的密钥的权限。在 KMS 控制台中完成密钥创建后，返回 Athena 控制台中的**创建工作组**页面，然后使用**选择 Amazon KMS 密钥或输入 ARN** 搜索框选择您刚刚创建的密钥。
**重要**  
更改工作组的 [Amazon KMS key](https://docs.amazonaws.cn/kms/latest/developerguide/concepts.html) 后，在更新之前托管的笔记本仍会引用旧的 KMS 密钥，而更新之后托管的笔记本将使用新的 KMS 密钥。要更新旧笔记本以引用新的 KMS 密钥，请导出每个旧笔记本然后导入。如果在将旧笔记本引用更新为新 KMS 密钥之前删除了旧 KMS 密钥，则旧笔记本将无法解密且无法恢复。  
此行为也适用于[别名](https://docs.amazonaws.cn/kms/latest/developerguide/kms-alias.html)的更新，别名是 KMS 密钥的易记名称。更新 KMS 密钥别名以指向新的 KMS 密钥后，在别名更新之前托管的笔记本仍会引用旧的 KMS 密钥，而在别名更新之后托管的笔记本会使用新的 KMS 密钥。在更新 KMS 密钥或别名之前，请考虑以下几点。

1. 对于**其他配置**，请选择**使用默认值**。此选项可帮助您开始使用启用 Spark 的工作组。使用默认值时，Athena 会在 Amazon S3 中为您创建 IAM 角色和计算结果位置。IAM 角色的名称和要创建的 S3 存储桶位置将在 **Additional configurations**（其他配置）标题下方的复选框中显示。

   如果不想使用默认值，请继续执行 [（可选）指定您自己的工作组配置](#notebooks-spark-getting-started-workgroup-configuration) 一节中的步骤，以手动配置工作组。

1. （可选）**Tags**（标签）– 使用此选项可向工作组添加标签。有关更多信息，请参阅 [标记 Athena 资源](tags.md)。

1. 选择 **Create workgroup (创建工作组)**。系统将显示一条消息通知您工作组已成功创建，并且该工作组将在工作组列表中显示。

### （可选）指定您自己的工作组配置
<a name="notebooks-spark-getting-started-workgroup-configuration"></a>

如果要为笔记本指定自己的 IAM 角色以及计算结果位置，请按照本节中的步骤操作。如果您为 **Additional configurations**（其他配置）选项选择了 **Use defaults**（使用默认值），请跳过本节并直接转至 [步骤 2：打开笔记本资源管理器并切换工作组](#notebooks-spark-getting-started-switching-workgroups-and-opening-notebook-explorer)。

以下过程假定您已完成上一节中 **To create a Spark enabled workgroup in Athena**（在 Athena 中创建启用 Spark 的工作组）过程的步骤 1 至 9。

**指定您自己的工作组配置**

1. 如果要创建或使用您自己的 IAM 角色或配置笔记本加密，请扩展 **IAM role configuration**（IAM 角色配置）。
   + 对于**用于授权 Athena 的服务角色**，选择以下选项之一：
     + **创建并使用新服务角色**：选择此选项，Athena 将为您创建服务角色。要查看角色授予的权限，请选择 **View permission details**（查看权限详细信息）。
     + **使用现有服务角色**：从下拉菜单中选择一个现有角色。所选角色必须包含第一个选项中的权限。有关启用笔记本的工作组的权限的更多信息，请参阅 [对启用 Spark 的工作组进行故障排除](notebooks-spark-troubleshooting-workgroups.md)。
   + 对于 **Notebook and calculation code encryption key management**（笔记本和计算代码加密密钥管理），选择下列选项之一：
     + **使用 Amazon 拥有的密钥进行加密（默认）**：Amazon KMS 密钥由 Amazon 拥有和管理。使用此密钥不会产生额外的费用。
     + **使用您自己的 Amazon KMS 密钥加密**：对于此选项，请执行以下操作之一：
       + 要使用现有密钥，请使用搜索框选择 Amazon KMS 或输入密钥 ARN。
       + 要在 Amazon KMS 控制台中创建密钥，选择**创建 Amazon KMS 密钥**。执行角色必须具有使用您创建的密钥的权限。在 KMS 控制台中完成密钥创建后，返回 Athena 控制台中的**创建工作组**页面，然后使用**选择 Amazon KMS 密钥或输入 ARN** 搜索框选择您刚刚创建的密钥。
**重要**  
更改工作组的 [Amazon KMS key](https://docs.amazonaws.cn/kms/latest/developerguide/concepts.html) 后，在更新之前托管的笔记本仍会引用旧的 KMS 密钥，而更新之后托管的笔记本将使用新的 KMS 密钥。要更新旧笔记本以引用新的 KMS 密钥，请导出每个旧笔记本然后导入。如果在将旧笔记本引用更新为新 KMS 密钥之前删除了旧 KMS 密钥，则旧笔记本将无法解密且无法恢复。  
此行为也适用于[别名](https://docs.amazonaws.cn/kms/latest/developerguide/kms-alias.html)的更新，别名是 KMS 密钥的易记名称。更新 KMS 密钥别名以指向新的 KMS 密钥后，在别名更新之前托管的笔记本仍会引用旧的 KMS 密钥，而在别名更新之后托管的笔记本会使用新的 KMS 密钥。在更新 KMS 密钥或别名之前，请考虑以下几点。

1. <a name="notebook-gs-metrics"></a>（可选）**Other settings**（其他设置）– 扩展此选项可启用或禁用工作组的 **Publish CloudWatch metrics**（发布 CloudWatch 指标）选项。在默认情况下，该字段会被选中。有关更多信息，请参阅 [使用 CloudWatch 指标监控 Apache Spark](notebooks-spark-metrics.md)。

1. （可选）**Tags**（标签）– 使用此选项可向工作组添加标签。有关更多信息，请参阅 [标记 Athena 资源](tags.md)。

1. 选择 **Create workgroup (创建工作组)**。系统将显示一条消息通知您工作组已成功创建，并且该工作组将在工作组列表中显示。

## 步骤 2：打开笔记本资源管理器并切换工作组
<a name="notebooks-spark-getting-started-switching-workgroups-and-opening-notebook-explorer"></a>

您必须先切换到该工作组，然后才能使用刚刚创建的启用 Spark 的工作组。要切换启用 Spark 的工作组，可以使用“笔记本资源管理器”或“笔记本编辑器”中的 **Workgroup**（工作组）选项。

**注意**  
开始之前，请确保您的浏览器不会阻止第三方 Cookie。浏览器的默认设置，或用户启用的设置阻止第三方 Cookie 时，都将阻止笔记本启动。有关管理 Cookie 的更多信息，请参阅：  
[Chrome](https://support.alertlogic.com/hc/en-us/articles/360018127132-Turn-Off-Block-Third-Party-Cookies-in-Chrome-for-Windows)
[Firefox](https://support.mozilla.org/en-US/kb/third-party-cookies-firefox-tracking-protection)
[Safari](https://support.apple.com/guide/safari/manage-cookies-sfri11471/mac)

**打开笔记本资源管理器并切换工作组**

1. 在导航窗格中，选择 **Notebook explorer**（笔记本资源管理器）。

1. 使用控制台右上角的 **Workgroup**（工作组）选项来选择您创建的启用 Spark 的工作组。示例笔记本将在笔记本列表中显示。

   您可以通过以下方式使用笔记本资源管理器：
   + 选择笔记本的链接名称，在新会话中打开该笔记本。
   + 要重命名、删除或导出笔记本，请使用 **Actions**（操作）菜单。
   + 要导入笔记本文件，请选择 **Import file**（导入文件）。
   + 要创建笔记本，请选择 **Create notebook**（创建笔记本）。

## 步骤 3：运行笔记本示例
<a name="notebooks-spark-getting-started-running-the-example-notebook"></a>

示例笔记本从公开的纽约出租车旅行数据集查询数据。该笔记本包含展示了如何使用 Spark DataFrames、Spark SQL 和 Amazon Glue Data Catalog 的示例。

**运行示例笔记本**

1. 在“笔记本资源管理器”中，选择示例笔记本的链接名称。

   这将通过默认参数启动笔记本会话，并在笔记本编辑器中打开笔记本。系统将显示一条消息，通知您已使用默认参数（最大 DPU 数为 20）启动新的 Apache Spark 会话。

1. 要按顺序运行单元格并查看结果，请为笔记本中的每个单元格选择一次 **Run**（运行）按钮。
   + 向下滚动以查看结果以及新单元格。
   + 对于包含计算结果的单元格，进度栏会显示完成百分比、所用时间和剩余时间。
   + 示例笔记本将在您的账户中创建示例数据库和表。作为清除步骤，最后一个单元格会将其删除。

**注意**  
如果您在示例笔记本中更改文件夹、表或数据库名称，请确保这些更改会反映在您使用的 IAM 角色中。否则，笔记本可能因权限不足而无法运行。

## 步骤 4：编辑会话详细信息
<a name="notebooks-spark-getting-started-editing-session-details"></a>

在启动笔记本会话后，您可以编辑会话详细信息，例如表格式、加密、会话空闲超时以及要使用的数据处理单元（DPU）的最大并发数。DPU 是对处理能力的相对度量，它由 4 个 vCPU 的计算容量和 16GB 内存组成。

**编辑会话详细信息**

1. 在笔记本编辑器中，从右上角的 **Session**（会话）菜单中选择 **Edit session**（编辑会话）。

1. 在**编辑会话详细信息**对话框的 **Spark 属性**部分中，选择或输入以下选项的值：
   + **其他表格式** - 选择 **Linux Foundation Delta Lake**、**Apache Hudi**、**Apache Iceberg** 或**自定义**。
     + 对于 **Delta**、**Hudi** 或 **Iceberg** 表选项，对应表格式所需的表属性将自动在**在表中编辑**和**在 JSON 中编辑**选项中提供。有关使用这些表格式的更多信息，请参阅 [在 Athena for Spark 中使用非 Hive 表格式](notebooks-spark-table-formats.md)。
     + 要为**自定义**或其他表类型添加或移除表属性，使用**在表中编辑**和**在 JSON 中编辑**选项。
     + 对于**在表中编辑**选项，选择**添加属性**添加属性，或者选择**移除**移除属性。要输入属性名称及其值，使用**键**和**值**框。
     + 对于**在 JSON 中编辑**选项，使用 JSON 文本编辑器直接编辑配置。
       + 要将 JSON 文本复制到剪贴板，选择**复制**。
       + 要从 JSON 编辑器中移除所有文本，选择**清除**。
       + 要配置换行或为 JSON 编辑器选择颜色主题，选择设置（齿轮）图标。
   + **打开 Spark 加密** - 选择此选项可加密写入磁盘并通过 Spark 网络节点发送的数据。有关更多信息，请参阅 [启用 Apache Spark 加密](notebooks-spark-encryption.md)。

1. 在**编辑参数**部分中，选择或输入以下选项的值：
   + **Session idle timeout**（会话空闲超时）– 选择或输入一个介于 1 和 480 分钟之间的值。默认值为 20。
   + **Coordinator size**（协调器大小）– *协调器*是一种特殊的执行程序，负责编排处理工作并管理笔记本会话中的其他执行程序。当前，1 DPU 是默认且唯一可能的值。
   + **Executor size**（执行程序大小）– *执行程序*是笔记本会话可以向 Athena 请求的最小计算单位。当前，1 DPU 是默认且唯一可能的值。
   + **Max concurrent value**（最大并发值）– 可以同时运行的最大 DPU 数。默认值为 20，最小值为 3，最大值为 60。增加此值不会自动分配其他资源，但 Athena 会在计算负载需要以及资源可用时尝试分配指定的最大值。

1. 选择**保存**。

1. 出现 **Confirm edit**（确认编辑）提示时，选择 **Confirm**（确认）。

   Athena 会保存笔记本并使用您指定的参数开始新会话。笔记本编辑器中的横幅将通知您已通过修改后的参数开始新会话。
**注意**  
Athena 会记住笔记本的会话设置。如果您编辑会话的参数然后终止会话，Athena 会在您下次启动笔记本会话时使用您配置的会话参数。

## 步骤 5：查看会话和计算的详细信息
<a name="notebooks-spark-getting-started-viewing-session-and-calculation-details"></a>

运行笔记本后，您可以查看会话和计算的详细信息。

**查看会话和计算的详细信息**

1. 在右上角的 **Session**（会话）菜单中，选择 **View details**（查看详细信息）。
   + **Current session**（当前会话）选项卡会显示有关当前会话的信息，包括会话 ID、创建时间、状态和工作组。
   + **History**（历史记录）选项卡会列出先前会话的会话 ID。要查看先前会话的详细信息，请选择 **History**（历史记录）选项卡，然后在列表中选择会话 ID。
   + **Calculations**（计算）部分将在会话中运行的计算列表显示。

1. 要查看计算的详细信息，请选择计算 ID。

1. 在 **Calculation details**（计算详细信息）页面上，可以执行以下操作：
   + 要查看计算代码，请参阅 **Code**（代码）部分。
   + 要查看计算结果，请选择 **Results**（结果）选项卡。
   + 要以文本格式下载显示的结果，请选择 **Download results**（下载结果）。
   + 要在 Amazon S3 中查看有关计算结果的信息，请选择 **View in S3**（在 S3 中查看）。

## 步骤 6：终止会话
<a name="notebooks-spark-getting-started-terminating-a-session"></a>

**终止笔记本会话**

1. 在笔记本编辑器中，从右上角的 **Session**（会话）菜单中选择 **Terminate**（终止）。

1. 出现 **Confirm session termination**（确认终止会话）提示时，选择 **Confirm**（确认）。笔记本已保存，您将返回到笔记本编辑器。

**注意**  
在笔记本编辑器中关闭笔记本选项卡并不会终止活动笔记本的会话。要确保会话已终止，请依次选择 **Session**（会话）、**Terminate**（终止）选项。

## 步骤 7：创建自己的笔记本
<a name="notebooks-spark-getting-started-creating-your-own-notebook"></a>

创建启用 Spark 的 Athena 工作组后，您可以创建自己的笔记本。

**创建笔记本**

1. 如果控制台导航窗格不可见，请选择左侧的扩展菜单。

1. 在 Athena 控制台导航窗格中，选择 **Notebook explorer**（笔记本资源管理器）或 **Notebook editor**（笔记本编辑器）。

1. 请执行以下操作之一：
   + 在 **Notebook explorer**（笔记本资源管理器）中，选择 **Create notebook**（创建笔记本）。
   + 在 **Notebook editor**（笔记本编辑器）中，选择 **Create notebook**（创建笔记本），或选择加号图标（**\$1**）添加笔记本。

1. 在 **Create notebook**（创建笔记本）对话框中，在 **Notebook name**（笔记本名称）中输入名称。

1. （可选）展开 **Spark 属性**，然后为以下选项选择或输入值：
   + **其他表格式** - 选择 **Linux Foundation Delta Lake**、**Apache Hudi**、**Apache Iceberg** 或**自定义**。
     + 对于 **Delta**、**Hudi** 或 **Iceberg** 表选项，对应表格式所需的表属性将自动在**在表中编辑**和**在 JSON 中编辑**选项中提供。有关使用这些表格式的更多信息，请参阅 [在 Athena for Spark 中使用非 Hive 表格式](notebooks-spark-table-formats.md)。
     + 要为**自定义**或其他表类型添加或移除表属性，使用**在表中编辑**和**在 JSON 中编辑**选项。
     + 对于**在表中编辑**选项，选择**添加属性**添加属性，或者选择**移除**移除属性。要输入属性名称及其值，使用**键**和**值**框。
     + 对于**在 JSON 中编辑**选项，使用 JSON 文本编辑器直接编辑配置。
       + 要将 JSON 文本复制到剪贴板，选择**复制**。
       + 要从 JSON 编辑器中移除所有文本，选择**清除**。
       + 要配置换行或为 JSON 编辑器选择颜色主题，选择设置（齿轮）图标。
   + **打开 Spark 加密** - 选择此选项可加密写入磁盘并通过 Spark 网络节点发送的数据。有关更多信息，请参阅 [启用 Apache Spark 加密](notebooks-spark-encryption.md)。

1. （可选）展开 **Session parameters**（会话参数），然后为以下选项选择或输入值：
   + **Session idle timeout**（会话空闲超时）– 选择或输入一个介于 1 和 480 分钟之间的值。默认值为 20。
   + **Coordinator size**（协调器大小）– *协调器*是一种特殊的执行程序，负责编排处理工作并管理笔记本会话中的其他执行程序。当前，1 DPU 是默认且唯一可能的值。DPU（数据处理单元）是对处理能力的相对度量，它由 4 个 vCPU 的计算容量和 16 GB 的内存组成。
   + **Executor size**（执行程序大小）– *执行程序*是笔记本会话可以向 Athena 请求的最小计算单位。当前，1 DPU 是默认且唯一可能的值。
   + **Max concurrent value**（最大并发值）– 可以同时运行的最大 DPU 数。默认值为 20，最大值为 60。增加此值不会自动分配其他资源，但 Athena 会在计算负载需要以及资源可用时尝试分配指定的最大值。

1. 选择**创建**。笔记本将在笔记本编辑器的新会话中打开。

有关管理笔记本文件的信息，请参阅[管理笔记本文件](notebooks-spark-managing.md)。