通过

适用于 R 的 Databricks Connect

  • 项目

注意

本文介绍与适用于 Databricks Runtime 13.0 及更高版本的 Databricks Connect 的 sparklyr 集成。 Databricks 既不提供，也不直接支持此集成。

如有问题，请转到 Posit 社区。

若要报告问题，请转到 GitHub 中 sparklyr 存储库的“问题”部分。

有关详细信息，请参阅 sparklyr 文档中的 Databricks Connect v2。

本文演示如何使用 R、sparklyr 和 RStudio Desktop 快速开始使用 Databricks Connect。

可以使用 Databricks Connect 将热门的 IDE（例如 RStudio Desktop、笔记本服务器和其他自定义应用程序）连接到 Azure Databricks 群集。 请参阅什么是 Databricks Connect？。

教程

此教程使用 RStudio Desktop 和 Python 3.10。 如果尚未安装它们，请安装 R 和 RStudio Desktop 以及 Python 3.10。

有关本教程的补充信息，请参阅 sparklyr 网站上的 Spark Connect 和 Databricks Connect v2 的“Databricks Connect”部分。

要求

若要完成此教程，必须满足以下要求：

  • 目标 Azure Databricks 工作区和群集必须满足 Databricks Connect 群集配置的要求。
  • 必须提供群集 ID。 若要获取你的群集 ID，请在工作区中单击边栏上的“计算”，然后单击群集的名称。 在 Web 浏览器的地址栏中，复制 URL 中 clusters 和 configuration 之间的字符串。

步骤 1：创建个人访问令牌

注意

适用于 R 的 Databricks Connect 身份验证目前仅支持 Azure Databricks 个人访问令牌。

本教程使用 Azure Databricks 个人访问令牌身份验证向 Azure Databricks 工作区进行身份验证。

如果已有 Azure Databricks 个人访问令牌，请跳到步骤 2。 如果不确定是否已拥有 Azure Databricks 个人访问令牌，则可以按照此步骤操作，而不会影响用户帐户中的任何其他 Azure Databricks 个人访问令牌。

创建个人访问令牌：

  1. 在 Azure Databricks 工作区中，单击顶部栏中的 Azure Databricks 用户名，然后从下拉列表中选择“设置”。
  2. 单击“开发人员”。
  3. 在“访问令牌”旁边，单击“管理”。
  4. 单击“生成新令牌”。
  5. （可选）输入有助于将来识别此令牌的注释，并将令牌的默认生存期更改为 90 天。 若要创建没有生存期的令牌（不建议），请将“生存期(天)”框留空（保留空白）。
  6. 单击“生成” 。
  7. 将显示的令牌复制到安全位置，然后单击“完成”。

注意

请务必将复制的令牌保存到安全的位置。 请勿与他人共享复制的令牌。 如果丢失了复制的令牌，你将无法重新生成完全相同的令牌， 而必须重复此过程来创建新令牌。 如果丢失了复制的令牌，或者认为令牌已泄露，Databricks 强烈建议通过单击“访问令牌”页上令牌旁边的垃圾桶（撤销）图标立即从工作区中删除该令牌。

如果你无法在工作区中创建或使用令牌，可能是因为工作区管理员已禁用令牌或未授予你创建或使用令牌的权限。 请与工作区管理员联系，或参阅以下主题：

步骤 2：创建项目

  1. 启动 RStudio Desktop。
  2. 在主菜单上，单击“文件”>“新建项目”。
  3. 选择“新建目录”。
  4. 选择“新建项目”。
  5. 对于目录名称和创建项目作为子目录，请输入新项目目录的名称以及创建新项目目录的位置。
  6. 选择“将 renv 与此项目配合使用”。 如果系统提示安装更新的 renv 包版本，请单击“是”。
  7. 单击“创建项目”。

创建 RStudio Desktop 项目

步骤 3：添加 Databricks Connect 包和其他依赖项

  1. 在 RStudio Desktop 主菜单上，单击“工具”>“安装包”。

  2. 将“从…安装”保持设置为“存储库 (CRAN)”。

  3. 对于“包”，请输入以下包列表，这些包是 Databricks Connect 包和本教程的先决条件：

    sparklyr,pysparklyr,reticulate,usethis,dplyr,dbplyr

  4. 将“安装到库”保持设置为 R 虚拟环境。

  5. 确保已选择“安装依赖项”。

  6. 单击“安装” 。

安装 Databricks Connect 包依赖项

  1. 当“控制台”视图中提示你（“视图”>“将焦点移到控制台”）继续安装时，请输入 Y。 R 虚拟环境中安装了 sparklyr 和 pysparklyr 包及其依赖项。

  2. 在“控制台”窗格中，使用 reticulate 通过运行以下命令来安装 Python。 （适用于 R 的 Databricks Connect 需要先安装 Python 和 reticulate。）在以下命令中，将 3.10 替换为 Azure Databricks 群集上安装的 Python 版本的主要版本和次要版本。 若要查找此主要版本和次要版本，请参阅 Databricks Runtime 发行说明版本和兼容性，查看你的群集的 Databricks Runtime 版本的发行说明的“系统环境”部分。

    reticulate::install_python(version = "3.10")

  3. 在“控制台”窗格中，运行以下命令安装 Databricks Connect 包。 在以下命令中，将 13.3 替换为 Azure Databricks 群集上安装的 Databricks Runtime 版本。 若要查找此版本，请在你的 Azure Databricks 工作区的群集详细信息页上的“配置”选项卡上，查看“Databricks Runtime 版本”框。

    pysparklyr::install_databricks(version = "13.3")

    如果不知道群集的 Databricks Runtime 版本或不想查找它，可以改为运行以下命令，pysparklyr 会查询群集以确定要使用的正确 Databricks Runtime 版本：

    pysparklyr::install_databricks(cluster_id = "<cluster-id>")

    如果希望项目稍后连接到不同群集，且该群集的 Databricks Runtime 版本与刚才指定的版本相同，pysparklyr 将使用相同的 Python 环境。 如果新群集具有不同的 Databricks Runtime 版本，则应使用新的 Databricks Runtime 版本或群集 ID 再次运行 pysparklyr::install_databricks 命令。

步骤 4：为工作区 URL、访问令牌和群集 ID 设置环境变量

Databricks 不建议将敏感值或更改值（例如 Azure Databricks 工作区 URL、Azure Databricks 个人访问令牌或 Azure Databricks 群集 ID）硬编码写入 R 脚本。 请单独存储这些值，例如存储在本地环境变量中。 本教程使用 RStudio Desktop 的内置支持将环境变量存储在 .Renviron 文件中。

  1. 创建一个 .Renviron 文件来存储环境变量（如果此文件尚不存在），然后打开此文件进行编辑：在 RStudio Desktop“控制台”中运行以下命令：

    usethis::edit_r_environ()

  2. 在出现的 .Renviron 文件中（“查看”>“将焦点移到源”），输入以下内容。 在此内容中，替换以下占位符：

    • 将 <workspace-url> 替换为每工作区 URL，例如 https://adb-1234567890123456.7.databricks.azure.cn。
    • 将 <personal-access-token> 替换为你在步骤 1 中的 Azure Databricks 个人访问令牌。
    • 将 <cluster-id> 替换为本教程要求中的群集 ID。
    DATABRICKS_HOST=<workspace-url>
DATABRICKS_TOKEN=<personal-access-token>
DATABRICKS_CLUSTER_ID=<cluster-id>

  3. 保存 .Renviron 文件。

  4. 将环境变量加载到 R 中：在主菜单上，单击“会话”>“重启 R”。

设置 Databricks Connect 的环境变量

步骤 5：添加代码

  1. 在 RStudio Desktop 主菜单中，单击“文件”>“新建文件”>“R 脚本”。

  2. 在文件中输入以下代码，然后将该文件保存为 demo.R（“文件”>“保存”）：

    library(sparklyr)
library(dplyr)
library(dbplyr)

sc <- sparklyr::spark_connect(
  master     = Sys.getenv("DATABRICKS_HOST"),
  cluster_id = Sys.getenv("DATABRICKS_CLUSTER_ID"),
  token      = Sys.getenv("DATABRICKS_TOKEN"),
  method     = "databricks_connect",
  envname    = "r-reticulate"
)

trips <- dplyr::tbl(
  sc,
  dbplyr::in_catalog("samples", "nyctaxi", "trips")
)

print(trips, n = 5)

步骤 6：运行代码

  1. 在 RStudio Desktop 上 demo.R 文件的工具栏中，单击“源”。

    运行 RStudio Desktop 项目

  2. 在“控制台”中，将显示 trips 表的前五行。

  3. 在“连接”视图（“视图”>“显示连接”）中，可以浏览可用的目录、架构、表和视图。

    项目的“连接”视图

步骤 7：调试代码

  1. 在 demo.R 文件中，单击 print(trips, n = 5) 旁边的装订线以设置断点。
  2. 在 demo.R 文件的工具栏中，单击“源”。
  3. 当代码在断点暂停运行时，可以在“环境”视图中检查变量（“查看”>“显示环境”）。
  4. 在主菜单上，单击“调试”>“继续”。
  5. 在“控制台”中，将显示 trips 表的前五行。

调试 RStudio Desktop 项目