# 使用 Athena 笔记本编辑器 **注意** Pyspark 引擎版本 3 支持 Athena 笔记本编辑器。要将笔记本与 Apache Spark 版本 3.5 搭配使用，请参阅 [SageMaker Notebooks](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/what-is-sagemaker-unified-studio.html)。 您可以在 Athena 笔记本资源管理器中管理笔记本，并使用 Athena 笔记本编辑器在会话中对其进行编辑和运行。您可以根据要求为笔记本会话配置 DPU 使用情况。 当您停止笔记本时，即会终止关联会话。将保存所有文件，但声明的变量、函数和类中正在进行的更改会丢失。重新启动笔记本后，Athena 会重新加载笔记本文件，您可以再次运行代码。 Athena 笔记本编辑器是一个用于编写和运行代码的交互式环境。以下各节介绍该环境的各项功能。 ## 了解笔记本会话和计算 每个笔记本都与一个 Python 内核相关联并运行 Python 代码。笔记本可以有一个或多个包含命令的单元格。要运行笔记本中的单元格，首先要为笔记本创建会话。会话会跟踪笔记本的变量和状态。 运行笔记本中的单元格意味着运行当前会话中的计算。计算会推进笔记本的状态，并且可能执行诸如从 Amazon S3 读取或写入其他数据存储等任务。只要会话在运行，计算就会使用和修改为笔记本维护的状态。 如果不再需要状态，可以结束会话。结束会话后，笔记本会保留，但变量和其他状态信息会销毁。如果您需要同时处理多个项目，可以为每个项目创建一个会话，这些会话相互独立。 会话具有专用的计算容量，以 DPU 为单位。创建会话时，可以为会话分配多个 DPU。不同的会话可能具有不同的功能，具体取决于任务的要求。 ## 在命令模式和编辑模式之间切换 笔记本编辑器具有模态用户界面：一种用于在单元格中输入文本的编辑模式，以及一种用于向编辑器本身发出命令（例如复制、粘贴或运行）的命令模式。 要使用编辑模式和命令模式，您可以执行以下任务： + 要进入编辑模式，请按 **ENTER** 或选择一个单元格。当单元格处于编辑模式时，单元格的左边距为绿色。 + 要进入命令模式，请按 **ESC**，或在单元格以外的位置单击。请注意，命令通常仅适用于当前选定的单元格，而不适用于所有单元格。当编辑器处于命令模式时，单元格的左边距为蓝色。 + 在命令模式下，您可以使用键盘快捷键和编辑器上方的菜单，但不能在单个单元格中输入文本。 + 要选择单元格，请选择该单元格。 + 要选择所有单元格，请按 **Ctrl\$1A**（Windows）或 **Cmd\$1A**（Mac）。 ## 使用笔记本编辑器菜单中的操作 笔记本编辑器顶部菜单中的图标提供以下选项： + **保存** – 保存笔记本的当前状态。 + **在下方插入单元格** – 在当前选定的单元格下方添加一个新的（空）单元格。 + **剪切所选单元格** – 将选定单元格从其当前位置移除并将其复制到内存。 + **复制所选单元格** – 将所选单元格复制到内存。 + **在下方粘贴单元格** – 将复制的单元格粘贴到当前单元格下方。 + **向上移动所选单元格** – 将当前单元格移至上方单元格上方。 + **向下移动所选单元格** – 将当前单元格移至下方单元格下方。 + **运行** – 运行当前（选定的）单元格。输出将立即在当前单元格下方显示。 + **全部运行** – 运行笔记本中的所有单元格。每个单元格的输出将立即在单元格下方显示。 + **停止（中断内核）** – 通过中断内核来停止当前笔记本。 + **格式选项** – 选择单元格格式，可以是以下格式之一： + **代码** – 用于 Python 代码（默认）。 + **Markdown** – 用于以 [GitHub 风格的 markdown](https://docs.github.com/en/get-started/writing-on-github) 格式输入文本。运行单元格以渲染 markdown。 + **Raw NBConvert** – 用于以未修改的格式输入文本。标记为 **Raw NBConvert** 的单元格可通过 Jupyter [nbconvert](https://nbconvert.readthedocs.io/en/latest/usage.html) 命令行工具转换为其他格式，例如 HTML。 + **标题** – 用于更改单元格的标题级别。 + **命令面板** – 包含 Jupyter notebook 命令及其键盘快捷键。有关键盘快捷键的更多信息，请参阅本文档后续章节。 + **会话** – 使用此菜单中的选项[查看](notebooks-spark-getting-started.md#notebooks-spark-getting-started-viewing-session-and-calculation-details)会话的详细信息、[编辑会话参数](notebooks-spark-getting-started.md#notebooks-spark-getting-started-editing-session-details)或[终止](notebooks-spark-getting-started.md#notebooks-spark-getting-started-terminating-a-session)会话。 ## 使用命令模式键盘快捷键提高工作效率 以下是笔记本编辑器命令模式的一些常见键盘快捷键。按 **ESC** 进入命令模式后，可以使用这些快捷键。要查看编辑器中可用命令的完整列表，请按 **ESC \$1 H**。 **** | Key | Action | | --- | --- | | 1 - 6 | 将单元格类型更改为 markdown 并将标题级别设置为键入的数字 | | a | 在当前单元格上方创建一个单元格 | | b | 在当前单元格下方创建一个单元格 | | c | 将当前单元格复制到内存 | | d d | 删除当前单元格 | | h | 显示键盘快捷键帮助屏幕 | | j | 向下移动一个单元格 | | k | 向上移动一个单元格 | | m | 将当前单元格格式更改为 markdown | | r | 将当前单元格格式更改为 raw | | s | 保存笔记本 | | v | 将内存内容粘贴到当前单元格下 | | x | 剪切选定的一个或多个单元格 | | y | 将单元格格式更改为代码 | | z | 撤消 | | Ctrl\$1Enter | 运行当前单元格并进入命令模式 | | Shift\$1Enter 或 Alt\$1Enter | 运行当前单元格并在输出下方创建一个新单元格，然后在编辑模式下输入新单元格 | | Space | 向下翻页 | | Shift\$1Space | 向上翻页 | | Shift \$1 L | 切换单元格中行号的可见性 | ## 自定义命令模式快捷键 笔记本编辑器可以选择自定义命令模式键盘快捷键。 **编辑命令模式快捷键** 1. 在笔记本编辑器菜单中选择 **Command palette**（命令面板）。 1. 在命令面板中选择 **Edit command mode keyboard shortcuts**（编辑命令模式键盘快捷键）命令。 1. 使用 **Edit command mode shortcuts**（编辑命令模式快捷键）界面，将所需的命令映射或重新映射到键盘。 要查看编辑命令模式快捷键的说明，请滚动至 **Edit command mode shortcuts**（编辑命令模式快捷键）屏幕底部。 有关在 Athena for Apache Spark 中使用魔术命令的信息，请参阅 [使用魔术命令](notebooks-spark-magics.md)。 **Topics** + [了解笔记本会话和计算](#notebooks-spark-sessions-and-calculations) + [在命令模式和编辑模式之间切换](#notebooks-spark-command-mode-vs-edit-mode) + [使用笔记本编辑器菜单中的操作](#notebooks-spark-notebook-editor-menu) + [使用命令模式键盘快捷键提高工作效率](#notebooks-spark-command-mode-keyboard-shortcuts) + [自定义命令模式快捷键](#notebooks-spark-editing-command-mode-shortcuts) + [使用魔术命令](notebooks-spark-magics.md) # 使用魔术命令 魔术命令，又称魔术，是可在笔记本单元格中运行的特殊命令。例如，`%env` 可在笔记本会话中显示环境变量。Athena 支持 IPython 6.0.3 中的魔术命令函数。 本节显示了 Athena for Apache Spark 中的一些关键魔术命令。 + 要查看 Athena 中的魔术命令列表，在笔记本单元格中运行 **%lsmagic** 命令。 + 有关在 Athena 笔记本中使用魔术创建图表的信息，请参阅 [使用魔术创建数据图表](notebooks-spark-magics-graphs.md)。 + 有关其他魔术命令的更多信息，请参阅 IPython 文档中的[内置魔术命令](https://ipython.readthedocs.io/en/stable/interactive/magics.html)。 **注意** 目前，`%pip` 命令无法执行。这是一个已知问题。 **Topics** + [单元格魔术命令](notebooks-spark-magics-cell-magics.md) + [行魔术命令](notebooks-spark-magics-line-magics.md) + [图表魔术命令](notebooks-spark-magics-graphs.md) # 使用单元格魔术 多行书写的魔术命令前有双百分号（`%%`），称为单元格魔术命令函数或单元格魔术命令。 ## %%sql 此单元格魔术命令允许直接运行 SQL 语句，而无需使用 Spark SQL 语句对其进行装饰。该命令还通过隐式调用 `.show()` 在返回的数据框上显示输出。 ![\[使用%%sql。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/notebooks-spark-magics-1.png) `%%sql` 命令会自动将列输出截断为 20 个字符宽度。目前，无法配置此设置。要绕过此限制，使用以下完整语法并相应地修改 `show` 方法的参数。 ``` spark.sql("""YOUR_SQL""").show(n=number, truncate=number, vertical=bool) ``` + **n** `int`（可选）。要显示的行数。 + **截断** - `bool` 或 `int`（可选）- 如果为 `true`，则截断的字符串长度超过 20 个字符。当设置为大于 1 的数字时，讲按指定长度截断长字符串，并使单元格右对齐。 + **垂直** - `bool`（可选）。如果为 `true`，则垂直发送输出行（每列值一行）。 # 使用行魔术 单行书写的魔术命令前有百分号（`%`），称为行魔术命令函数或行魔术命令。 ## %help 显示可用魔术命令的描述。 ![\[使用%help。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/notebooks-spark-magics-2.png) ## %list\$1session 列出与笔记本相关的会话。每个会话的信息包含会话 ID、会话状态以及会话的开始和结束日期和时间。 ![\[使用%list_sessions。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/notebooks-spark-magics-3.png) ## %session\$1id 检索当前会话 ID。 ![\[使用session_id。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/notebooks-spark-magics-4.png) ## %set\$1log\$1level 设置或重置记录器以使用指定的日志级别。可能的值为 `DEBUG`、`ERROR`、`FATAL`、`INFO` 和 `WARN` 或 `WARNING`。值必须为大写且不得包含在单引号或双引号中。 ![\[使用%set_log_level。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/notebooks-spark-magics-5.png) ## %status 描述当前会话。输出包含会话 ID、会话状态、工作组名称、PySpark 引擎版本和会话开始时间。此魔术命令需要活动会话才能检索会话详细信息。 状态的可能值如下所示： **CREATING** - 会话正在启动，包括获取资源。 **CREATED** - 会话已启动。 **IDLE** - 会话能够接受计算。 **BUSY** - 会话正在处理其他任务，无法接受计算。 **TERMINATING** - 会话正在关闭。 **TERMINATED** - 会话及其资源不再运行。 **DEGRADED** - 会话没有运行正常的协调器。 **FAILED** - 由于故障，会话及其资源不再运行。 ![\[使用%status。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/notebooks-spark-magics-6.png) # 使用魔术创建数据图表 本节中的行魔术专门针对特定类型的数据或与图形库结合使用渲染数据。 ## %table 可使用 `%table` 魔术命令以表格式显示数据框数据。 以下示例创建了一个包含两列和三行数据的数据框，然后以表格式显示数据。 ![\[使用 %table 魔术命令。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/notebooks-spark-magics-graphs-1.png) ## %matplot [Matplotlib](https://matplotlib.org/) 是一个综合库，用于在 Python 中创建静态、动画演示和交互式可视化。在将 matplotlib 库导入笔记本单元格后，可使用 `%matplot` 魔术命令创建图表。 以下示例导入了 matplotlib 库，创建了一组 x 和 y 坐标，然后使用 `%matplot` 魔术命令创建点图。 ``` import matplotlib.pyplot as plt x=[3,4,5,6,7,8,9,10,11,12] y= [9,16,25,36,49,64,81,100,121,144] plt.plot(x,y) %matplot plt ``` ![\[使用 %matplot 魔术命令。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/notebooks-spark-magics-graphs-2.png) ### 同时使用 matplotlib 和 seaborn 库 [Seaborn](https://seaborn.pydata.org/tutorial/introduction) 是一个用于在 Python 中创建统计图形的库。该库基于 matplotlib 构建，并与 [pandas](https://pandas.pydata.org/)（Python 数据分析）数据结构紧密集成。也可以使用 `%matplot` 魔术命令渲染 seaborn 数据。 以下示例使用 matplotlib 和 seaborn 库创建简单的条形图。 ``` import matplotlib.pyplot as plt import seaborn as sns x = ['A', 'B', 'C'] y = [1, 5, 3] sns.barplot(x, y) %matplot plt ``` ![\[使用 %matplot 渲染 seaborn 数据。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/notebooks-spark-magics-graphs-3.png) ## %plotly [Plotly](https://plotly.com/python/) 是一个适用于 Python 的开源图形库，可用于创建交互式图表。可使用 `%ploty` 魔术命令渲染 ploty 数据。 以下示例对股票价格数据使用 [StringIO](https://docs.python.org/3.13/library/io.html#io.StringIO)、plotly 和 pandas 库来创建 2015 年 2 月和 3 月的股票活动图表。 ``` from io import StringIO csvString = """ Date,AAPL.Open,AAPL.High,AAPL.Low,AAPL.Close,AAPL.Volume,AAPL.Adjusted,dn,mavg,up,direction 2015-02-17,127.489998,128.880005,126.919998,127.830002,63152400,122.905254,106.7410523,117.9276669,129.1142814,Increasing 2015-02-18,127.629997,128.779999,127.449997,128.720001,44891700,123.760965,107.842423,118.9403335,130.0382439,Increasing 2015-02-19,128.479996,129.029999,128.330002,128.449997,37362400,123.501363,108.8942449,119.8891668,130.8840887,Decreasing 2015-02-20,128.619995,129.5,128.050003,129.5,48948400,124.510914,109.7854494,120.7635001,131.7415509,Increasing 2015-02-23,130.020004,133,129.660004,133,70974100,127.876074,110.3725162,121.7201668,133.0678174,Increasing 2015-02-24,132.940002,133.600006,131.169998,132.169998,69228100,127.078049,111.0948689,122.6648335,134.2347981,Decreasing 2015-02-25,131.559998,131.600006,128.149994,128.789993,74711700,123.828261,113.2119183,123.6296667,134.0474151,Decreasing 2015-02-26,128.789993,130.869995,126.610001,130.419998,91287500,125.395469,114.1652991,124.2823333,134.3993674,Increasing 2015-02-27,130,130.570007,128.240005,128.460007,62014800,123.510987,114.9668484,124.8426669,134.7184854,Decreasing 2015-03-02,129.25,130.279999,128.300003,129.089996,48096700,124.116706,115.8770904,125.4036668,134.9302432,Decreasing 2015-03-03,128.960007,129.520004,128.089996,129.360001,37816300,124.376308,116.9535132,125.9551669,134.9568205,Increasing 2015-03-04,129.100006,129.559998,128.320007,128.539993,31666300,123.587892,118.0874253,126.4730002,134.8585751,Decreasing 2015-03-05,128.580002,128.75,125.760002,126.410004,56517100,121.539962,119.1048311,126.848667,134.5925029,Decreasing 2015-03-06,128.399994,129.369995,126.260002,126.599998,72842100,121.722637,120.190797,127.2288335,134.26687,Decreasing 2015-03-09,127.959999,129.570007,125.059998,127.139999,88528500,122.241834,121.6289771,127.631167,133.6333568,Decreasing 2015-03-10,126.410004,127.220001,123.800003,124.510002,68856600,119.71316,123.1164763,127.9235004,132.7305246,Decreasing """ csvStringIO = StringIO(csvString) from io import StringIO import plotly.graph_objects as go import pandas as pd from datetime import datetime df = pd.read_csv(csvStringIO) fig = go.Figure(data=[go.Candlestick(x=df['Date'], open=df['AAPL.Open'], high=df['AAPL.High'], low=df['AAPL.Low'], close=df['AAPL.Close'])]) %plotly fig ``` ![\[使用 %ploty 魔术命令。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/notebooks-spark-magics-graphs-4.png)