注意:以下翻译的准确性尚未经过验证。这是使用 AIP ↗ 从原始英文文本进行的机器翻译。
本指南将通过代码仓库应用程序引导您完成一个简单的数据变换示例。您将学习如何编写和编辑SQL代码以及搭建您的数据集。您还将学习如何在分支上工作,以便与同事协作。
首先创建一个新仓库。为此,导航到Foundry中的项目,在右上角选择**+ 新建**,然后选择代码仓库。
在本指南中,我们将编写一个SQL变换。为您的仓库命名,然后在语言模板下拉菜单中选择SQL。然后,选择初始化仓库。
如果您已经导入了一个要使用的原始数据集,可以继续下一步。否则,您可以下载此示例数据集:
请参考手动数据上传指南,了解如何将此数据集上传到您的项目中,与您的仓库一起使用。
通过创建个人分支来更改,而不是直接编辑代码的主版本,您可以安全地与同事在同一个代码仓库中协作。您可以跟踪和撤销更改,以及将更改合并到主代码中。代码可以逐行审查,这意味着可以轻松地在团队成员之间讨论生产管道的更改。要了解有关Foundry中分支的更多信息,请参阅此页面。
当您导航到代码仓库时,您默认会在master
分支上。最佳实践是保护master
分支,这意味着无法直接在该分支上编辑代码。请注意,您可以读取受保护分支上的文件,但不能编辑或创建文件。
在您可以向代码仓库添加更改之前,您必须首先创建包含master
分支代码副本的分支。要创建分支,请点击当前分支名称旁边的图标。
这将打开一个对话框,用于选择现有分支并为新分支选择一个自定义名称:
创建新分支后,您将在左侧看到一个相同的文件树。您只需创建了一个master
分支代码的副本。现在,您可以在您的分支中编辑文件。
现在您在自己的分支中工作,通过在文件夹上将鼠标悬停并点击省略号图标,然后选择新文件来创建一个新的SQL文件。一旦选择新文件,系统将提示您选择文件类型并为其命名。在本示例中,选择SQL变换并选择一个文件名(不含空格或特殊字符):
请注意,您的新SQL文件在文件树中的位置被高亮显示,表示构建时生成的数据集将存在的位置。
如果文件树中的文件名是绿色的,则表示这是您分支中新创建的文件,在开始的主分支中不存在。如果文件名是橙色的,则表示这是一个在master
中存在但在您的分支中已被修改的文件。
您新创建的.sql
文件将根据您提供的文件名声明一个输出数据集。例如,如果您的仓库位于/Public/Authoring
目录下,并且您创建了titanicAnalysis.sql
,则新文件将自动声明一个输出数据集/Public/Authoring/titanicAnalysis
。
接下来,用您的实际数据变换代码替换占位符文本。首先,用实际输入数据集的路径替换`SOURCE_DATASET_PATH`
。在本示例中,您将使用在本教程第(2)步中导入的titanic
数据集。
请注意,当您开始输入反引号时,自动完成将向您显示一个交互菜单,列出您可以使用的数据集。当您从列表中选择一个数据集时,数据集引用将被替换为该数据集的唯一ID。这使得即使数据集稍后被移动,您的变换代码仍然可以继续工作。
在反引号中输入您的项目名称,找到titanic
数据集,并从菜单中选择它。
继续编写SQL代码以对您的数据进行变换。当您输入SQL函数时,您将看到各种帮助对话框。例如,假设您想要在您的“titanic”数据集中创建一个包含乘客性别缩写的新列。您可以查看有关如何使用SUBSTRING
函数的信息:
在继续之前,完成编写您的数据变换代码,以选择“Name”、“Age”、“Survived”和“Ticket”列以及一个名为“Gender”的派生列。“Gender”列表示乘客的性别缩写;要创建此列,请在“Sex”列上调用SUBSTRING
函数。
请注意,您必须为在SQL中创建的任何派生列定义一个别名。有关编写SQL数据变换的更多信息,请参阅Spark SQL语言参考。
在Foundry中,数据集可以分支(类似于代码)。这对于测试多步骤数据管道的设计非常有用。例如,您可以在不破坏下游依赖关系的情况下,单独测试数据管道的部分更改。
现在您已经编写了数据变换代码,您应该在分支中测试所做的更改。在将更改合并到master
分支之前,测试您的更改非常重要,以确保您的代码按预期工作。
在编写代码时,您可以使用预览功能加快开发周期并快速迭代更改。预览在采样输入上运行您的代码,并提供一个样本输出,而无需提交更改、运行检查或在Foundry中实现数据集。样本输出可能不代表构建结果,但它们可以提供一种确认代码工作并产生预期结果的方法。
要使用,请从标题中单击预览,或在代码编辑器底部打开预览助手。可以预览基于文件的数据集或具有模式的数据集。
对于具有模式的数据集,您可以通过单击要编辑的输入的设置图标来自定义预览更改时使用的输入。选项包括:
首次在包含文件的数据集上运行预览时,必须配置将在样本中使用的文件。选择样本文件后,可以通过选择相关输入重新配置它们。保存配置后,预览将在选择的文件样本上执行代码。
再次运行预览时,无需重新配置输入文件。预览执行后,您可以查看样本输出作为行或文件。如果您拥有所需的权限,还可以选择下载输出文件。
编写新代码后,您可以提交更改。在代码仓库中,当您想要标记所做的工作时提交更改。即使在您提交之前,您的工作也会默认自动保存。提交专门标记您在达到停止点时所做的更改集。
单击提交按钮提交您的更改并在代码上运行自动检查。单击构建按钮也会提交您的更改。具体来说,单击构建会运行自动代码检查并开始构建您的输出数据集。如果您想快速测试更改而不构建数据集以确保代码通过代码检查,请单击提交。否则,您可以跳到在分支上构建您的数据集。
要提交所做的更改,请单击右上角的按钮并输入您所做更改的摘要。提交更改会触发自动检查以运行您的代码。右上角的图标指示这些检查的状态;将鼠标悬停在其上以查看更多详细信息。
要测试更改,请单击屏幕顶部的按钮。
一旦单击构建按钮,会发生两件事:自动检查运行您的代码并开始构建您的输出数据集。在此期间,将从分支中的代码创建一个新的输出数据集,或者更新现有的输出数据集以反映您的更改。您可以在构建助手中查看运行任务的进度。一旦任务完成,图标表明每个任务已成功完成。如果您看到
图标,请单击详情按钮以了解出了什么问题。这将带您到检查选项卡,您可以在其中查找错误消息并重新触发构建。
以下是测试更改和构建数据集的重要信息:
一旦任务成功完成并且数据集构建完成,您可以在构建助手中预览构建的数据集:
单击构建助手中的数据集链接以打开完整数据集。
现在,您已经在自己的分支上构建了数据集。继续阅读本指南的其余部分,了解如何将数据变换代码合并到主分支中。
到目前为止,您已经:
现在,您将提出您的更改以供同事审核。在测试了您的更改并对生成的输出数据集感到满意后,您可以提出您的更改以供同事审核。
具有所有者权限的用户在创建_pull request_时将能够启用“自动合并更改”选项。仅当为仓库分支配置并通过至少一个必需检查时,才会提供此选项。如果启用“自动合并更改”选项,在创建_pull request_后,您的_pull request_将自动合并到主代码中。一旦从分支合并到主代码,您的分支也将自动删除。
要创建新的拉取请求,请单击右上角的按钮。这将打开“新建拉取请求”页面,您可以在其中编写更改说明并单击创建拉取请求按钮。
这将创建一个包含您提出更改的新拉取请求。拉取请求页面提供了广泛的工具,您可以用来查看提出的更改将如何影响数据管道:
一般来说,在将更改合并到主分支之前,邀请他人审查您的更改非常重要。用户可以逐文件批准或拒绝,以跟踪在拉取请求合并之前仍需调整的文件。要查看哪些用户已批准或拒绝特定文件,请将鼠标悬停在相应的指示图标上。
使用单个文件审查按钮是可选的,但当您拒绝一个文件时,这会自动拒绝拉取请求。同样,当您批准拉取请求时,所有单个文件都会被批准。
master
分支一旦您的更改已被审查,具有适当权限的用户(默认情况下为所有者和编辑者)可以_合并_拉取请求中的更改以将其合并到master
中。
在本教程的目的中,继续选择屏幕右下角的压缩并合并按钮,然后在确认对话框中再次选择压缩并合并。
您的仓库可能在合并更改之前必须满足不同的策略。策略由仓库所有者在分支设置页面中定义,并在拉取请求页面中呈现给代码作者。
一旦您的提出的更改被接受,您应该验证在分支中所做的更改是否反映在master
分支上。为此,请单击代码选项卡,选择master
分支并浏览文件。确保看到您在分支中所做的更改。
不要删除您未创建的任何分支。对于其他在同一代码仓库中工作的人,这可能会导致工作丢失!
现在,您可以删除在本教程开始时创建的分支以减少混乱。由于您的更改已合并到master
分支,因此无需保留您的分支。导航到分支选项卡,并在“个人分支”下查找。通过单击图标删除创建的分支:
拉取请求页面提供“合并后删除分支”选项,以便快速清理分支。此选项对于受保护的分支不可用。
要删除受保护的分支,您首先需要取消保护然后按照上述步骤操作。
master
分支上构建数据集最后一步是在master
分支上构建您的新数据集。类似于在分支上构建数据集,当选择您的SQL代码文件时,单击屏幕顶部的按钮。
一旦任务成功完成并且数据集构建完成,您可以单击构建助手中的数据集链接以打开完整数据集。
恭喜!您已经成功创建了新的数据变换并使用代码仓库发布了更改。以下是一些继续学习的可能步骤:
如果您注意到已经合并到主分支的代码更改存在问题,有一种简单的方法可以撤销这些更改。您可以通过在主分支的提交历史记录中找到特定提交来撤销该提交。在仓库的分支选项卡上,单击master
以查看所有提交的时间顺序列表。
您可以通过单击提交哈希查看某个提交的代码更改。一旦找到要撤销的提交,请单击撤销。这将打开一个进入主分支的拉取请求,您可以审核并合并。