从其他项目导入文件

您可以将文件从其他 LookML 项目和外部代码库导入当前项目。这样,您就可以在多个项目中使用模型文件、查看文件和其他文件。

这有多种使用情形。例如:

  • 在已安装的观看者屏蔽功能块的基础上进行构建,而无需直接对其进行更改。如果 Looker 对该块进行更改,您可以拉取更改,因为您添加到该块中的所有 LookML 都存储在单独的代码库中。

  • 维护根据数据库架构自动生成的基础项目。您可以将所有自定义维度、测量值等内容放在单独的项目中,从自动生成的项目中导入所有 LookML。您可以根据数据库架构的变化定期重新生成基础项目,而不会覆盖所有自定义 LookML。

  • 在单个项目中封装共享对象,然后将其导入多个其他项目。例如,如果您有多个数据库中都通用的表,则可以将该表的视图放在一个项目中,并在该位置进行维护。然后,让多个其他项目通过将表导入这些项目来使用它。

如需从其他项目导入文件,请执行以下任务:

  1. 创建项目清单文件
  2. 指定要导入的本地远程项目。
  3. 查看已导入项目中的文件
  4. 包含导入项目中的文件

然后,您就可以引用导入的项目文件中的字段,并替换导入的项目中定义的常量的值(如果常量允许替换)。

创建项目清单文件

任何从其他项目导入文件的项目都必须具有项目清单文件。如果您的项目尚无清单文件,您可以通过 Looker IDE 中的文件浏览器顶部的 + 图标创建一个

如需导入项目,请在清单中指定它们。您可以指定本地项目或远程项目,如以下部分所述。

导入本地项目

只有当导入的项目位于同一 Looker 实例中时,才能使用本地项目导入功能。此外,还建议开发者对导入项目的模型拥有模型权限。如果您的开发者在导入的项目中拥有模型权限,版本控制将是动态的,这意味着导入的项目中的更改将立即影响导入该项目的项目。这样,开发者可以在推送到生产环境之前验证两个项目中的更改。此外,对于在两个项目中都拥有模型权限的开发者,导入的项目文件将反映开发者的开发模式状态。因此,如果开发者处于开发模式,Looker IDE 将显示所导入项目文件的开发模式。如果开发者处于正式版模式,Looker IDE 将显示导入项目的正式版模式。

在清单文件中,project_name 参数用于指定当前项目的名称(Looker 会在您为项目创建清单文件时自动填充此参数)。如需将本地项目导入当前项目,请使用一个或多个 local_dependency 参数指定要导入的项目:

# This project
project_name: "my_project"

# The project to import
local_dependency: {
  project: "my_other_project"
}

在以下情况下,您应该使用远程项目导入,而不是本地项目导入:

  • 您的开发者对导入的项目的模型没有模型权限。在这种情况下,Looker 会克隆导入项目的生产模式,并在 IDE 中显示文件的静态版本。此静态版本绝不会显示文件的开发模式版本,并且可能与当前的正式版不一致,而不会向开发者发出提醒。最好使用远程项目导入,并提供一个 ref 来指定远程项目中的 Git 分支或 Git 版本。如果您这样做,Looker 会自动检测远程项目中的新提交内容,以便开发者收到提醒,然后引入最新版本的远程项目文件。
  • 开发者始终需要使用导入项目的正式版。
  • 您的开发者需要使用导入的项目文件的静态版本。

导入远程项目

在远程导入中,导入的项目不需要位于同一实例上。而是通过其远程 Git 代码库导入项目。

如需导入远程仓库,请使用 remote_dependency 参数提供远程仓库的信息。remote_dependency 参数接受以下信息和子参数:

  • 已导入项目的名称,可以是您喜欢的任何名称。在下面的示例中,项目名称为 ga_360_block。您可以在 include 语句中使用此名称引用 LookML 项目中导入的文件。该名称还用作 Looker IDE 的 imported_projects 文件夹下的文件夹名称。
  • url 子参数,您可以在其中指定外部 Git 代码库的地址。使用代码库的主网址。
  • ref 子参数,用于指定 Git 分支、Git 发布标记或 Git 代码库中提交的 SHA。如果您希望进行静态版本控制,可以指定提交 SHA,这样导入的项目中的更改不会自动反映在您的项目中(对于 Looker 块而言,这是一个不错的选项)。或者,如果您希望 Looker 自动检测远程项目中的新提交内容,则可以指定 Git 分支或 Git 版本标记。如需了解详情,请参阅本页面上的自动检测远程项目的新版本部分。
  • override_constant 子参数,这是一个可选子参数,可让您替换在导入的项目中定义的常量的值。

以下是项目清单文件中的 remote_dependency 参数的示例。此示例使用 HTTPS 连接:

remote_dependency: ga360_block {
  url: "https://github.com/llooker/google_ga360"
  ref: "master"
  override_constant: connection {
    value: "importing_project_connection"
  }
}

您还可以使用 SSH:

remote_dependency: ga360_block {
  url: "git@github.com:llooker/google_ga360.git"
  ref: "master"
  override_constant: connection {
    value: "importing_project_connection"
  }
}

添加远程依赖项后,您可能需要为远程项目配置导入凭据,请参阅本页面上的为私有远程代码库配置身份验证凭据部分。

自动检测远程项目的新版本

如果您在清单文件中 remote_dependencyref 子参数中指定了 Git 分支或 Git 版本标记,则可以让 Looker 自动检测远程项目中的新提交。

例如,以下远程依赖项会在 ref 子参数中指定 master 分支:

remote_dependency: exchange_rate {
  url: "https://github.com/llooker/datablocks-exchangerate.git"
  ref: "master"
}

之后,当 master 分支使用新提交内容进行更新时,Looker 会自动检测更改。

以下是指定了 v1.0 版本标记的示例:

remote_dependency: e_faa_original {
  url: "https://github.com/llooker/google_ga360"
  ref: "v1.0"
}

无论您为 ref 参数指定的值类型如何(即使是提交 SHA),当您向项目添加 remote_dependency 参数时,IDE 都会在项目顶部的导航栏中显示更新依赖项按钮。

点击 Update Dependencies 以导入远程项目文件。如果这是您向项目添加的第一个远程依赖项,更新依赖项还会提示 Looker 创建清单锁定文件。Looker 使用清单锁定文件来跟踪远程项目的版本。

如果您在 ref 子参数中指定了 Git 分支或 Git 版本标记,那么每当 Looker IDE 刷新时,Looker 都会检查是否有新的提交内容。Looker IDE 刷新的情况包括:Looker 开发者进入开发模式、在 IDE 中执行 Git 操作或刷新浏览器。

如果存在新的提交内容,Looker 会在 IDE 的“Git 操作”面板中显示 Update Dependencies 选项。

选择 Update Dependencies 选项,将最新的远程项目文件引入到您的项目中。

获取最新文件后,您可以验证 LookML,以验证项目的所有引用是否与更新后的远程项目文件兼容。然后,您可以修复任何损坏的引用并部署更改,而无需停机。

清单锁定文件

Looker 使用文件名为 manifest_lock.lkml 的清单锁定文件来跟踪远程导入项目的版本。Looker IDE 的文件浏览器面板中会列出清单锁定文件。

Looker 开发者无需创建或修改清单锁定文件,因为锁定文件由 Looker 自动管理。

清单锁定文件会显示每个远程项目,由包含 urlref 子参数的 remote_dependency 条目表示:

  • remote_dependency 参数表示 Looker 开发者在清单文件中指定的远程项目的名称。
  • url 子参数表示 Looker 开发者在清单文件中指定的外部 Git 代码库的地址。
  • ref 子参数显示 Looker 在项目中使用的项目版本(以提交 SHA 表示):
    • 如果清单文件中使用 Git 分支或 Git 版本标记的 ref 定义了远程项目,则 ref 参数会显示您的项目当前使用的文件版本(远程项目提交 SHA)。如果远程项目中有新的提交,Looker 会在 IDE 中显示 Update Dependencies 按钮,以便您导入最新的远程项目文件。然后,清单锁定文件中的 ref 值将更新为显示相应分支或版本标记的最新提交 SHA。
    • 如果在清单文件中使用特定提交 SHA 的 ref 定义了远程项目,则清单锁定文件中的 ref 参数将是相同的提交 SHA。

为专用远程仓库配置身份验证凭据

如需为专用远程仓库配置身份验证凭据,请在 IDE 左侧导航窗格中选择 Settings ,以前往 Import Credentials 页面。

导入凭据设置会显示项目清单文件中已定义的每个远程代码库的网址列表、用于代码库的身份验证类型(httpsssh),以及 Looker 能否成功连接到代码库。

添加身份验证凭据

如需为代码库添加身份验证凭据,请执行以下操作:

  1. 导入凭据页面的 URL 标题下,将光标悬停在某个代码库名称上,以显示 TestConfigure 按钮,然后点击 Configure

  2. Looker 会显示配置 Git 身份验证 (Configure Git Authentication) 对话框,允许您为远程代码库配置凭据。该对话框将指明该特定代码库所需的凭据类型。

    • 如果代码库要求提供用户名和密码(或个人访问令牌)进行身份验证,请输入您的用户名和密码或令牌,然后点击保存更改

    • 如果代码库需要 SSH 密钥(例如本页面上文中介绍的使用 SSH 导入远程项目示例),Looker 会显示一个对话框,其中显示您的本地 SSH 密钥。点击复制密钥,将 SSH 密钥复制到剪贴板,并将其添加到代码库的密钥列表中。

  3. 保存凭据后,点击测试以测试 Looker 对代码库的访问权限。

    通过连接测试并连接到代码库后,导入凭据部分的代码库名称旁边会显示一个绿色对勾标记。

修改身份验证凭据

如需修改仓库的身份验证凭据,请执行以下操作:

  1. 如需显示 TestEdit 按钮,请将指针悬停在已配置身份验证凭据的代码库上,然后点击 Edit

  2. 如果代码库要求提供用户名和密码(或个人访问令牌)进行身份验证,请点击 Clear Credentials(清除凭据),然后在确认对话框中点击 Yes, clear credentials(是,清除凭据)。

  3. 配置 Git 身份验证对话框中输入新的凭据,然后点击保存更改

查看导入项目中的文件

Looker IDE 在左侧导航窗格的 imported_projects 文件夹中显示导入的项目文件。您可以选择导入的项目文件以查看其内容。

本地项目远程项目中的文件会列在 imported_projects 文件夹中。

此外,您还可以通过对象浏览器查看已导入项目文件中的对象,这些对象包含在活动项目中。从 Looker IDE 的导航栏访问对象浏览器。

此外,拥有 develop 权限的用户可以使用元数据面板查看导入的项目中的对象的相关信息,包括用于导航到定义对象的导入文件的链接。如需了解详情,请参阅 LookML 对象的元数据文档页面。

包括已导入项目中的文件

模型文件中的 include 参数指定了可供该模型使用的项目文件。在清单文件中指定本地远程导入的项目后,您可以在模型文件中使用 include 参数指定导入项目中的文件。只能添加其项目列在清单文件中的文件。

如需 include 其他项目中的文件,请使用带有两个正斜杠 (//) 的文件名和导入的项目的名称。在导入的项目名称后面添加一个正斜线 (/) 和要添加的文件的完整路径。

例如,以下 include 命令分别表示从 e_flights 导入的项目中的 users 视图文件以及从 e_commerce 导入的项目中的 orders 视图:

include: "//e_flights/views/users.view.lkml"
include: "//e_commerce/public/orders.view.lkml"

如需了解如何在启用 IDE 文件夹的情况下指定路径,请参阅 include 参数页面的路径语法部分。

您可以使用通配符包含多个文件。例如,如需包含 e_flights 已导入项目的 /views/ 目录中的所有视图文件,请运行以下命令:

include: "//e_flights/views/*.view"

此外,您可以使用通配符将范围限定为特定目录级别或导入项目中的递归目录:

include: "//e_flights/*/*.view.lkml"
include: "//e_commerce/*/*.view.lkml"

如需了解如何在启用 IDE 文件夹的情况下使用通配符,请参阅 include 参数页面的通配符示例部分。

添加模型文件

您无法添加其他项目中的模型文件。不过,如果您想跨项目重复使用、优化扩展探索,则可以在导入的项目中创建单独的探索文件,然后将该探索文件添加到其他项目中。如需了解详情,请参阅 include 参数文档页面的在模型中添加探索部分。

添加包含其他文件的文件

如果添加的文件包含其他文件,则在将该文件传递到包含它的下一个项目之前,系统会先解析所有包含内容。

例如,如果您在当前项目中从其他项目 (proj_A) 导入文件 (A),并且导入的文件包含一个 include 参数,该参数包含项目 proj_B 中的文件 B,则在文件 A 导入到当前项目之前,系统会将文件 B 包含到文件 A 中。

导入数据文件

存储在项目的“数据”部分的文件不会被导入。如需引用导入的项目中的数据文件(例如在 map_layer 参数中),请使用文件的完整路径和文件名。例如:

map_layer: json_from_imported_project {
  file: "//path_to_imported_project/folder/filename.topojson"
  ...
}

从已导入的项目中引用文件

将视图文件导入项目后,您可以使用语法 ${view_name.field_name} 引用导入的视图的字段,就像该视图文件是该项目的一部分一样。例如,假设您已在项目清单文件中导入 ga_360_block 项目,并且您的模型文件中包含以下 include 语句:

include: "//ga_360_block/ga_block.view"

您可以使用语法 ${ga_block.hits_total} 引用包含的 ga_block 视图中的 hits_total 字段。

在已导入项目的文件中使用常量

借助 LookML 常量,您可以在项目的清单文件中定义一个值,该值可在整个项目中重复使用。constant 参数的 export 子参数用于指定在引用某个常量的文件被导入到另一个项目中时,是否可以替换该常量的值。

export 参数具有以下可能的值:

  • noneexport 的默认值。您无法在导入的项目中替换常量的值。导入项目会使用导入项目的清单文件中指定的常量值。
  • override_optional:可以选择在导入项目中替换常量的值。如果导入项目的清单文件中未提供值,则系统会使用导入项目中的原始值。
  • override_required:导入项目必须替换最初在导入项目的清单文件中指定的常量值。如果在导入的项目中未提供新的常量值,Looker 将显示错误。

将引用常量的文件导入项目时,您可以使用项目清单文件中 local_dependencyremote_dependencyoverride_constant 子参数为该常量提供新值,前提是该常量在其原始项目中已设置为 override_optionaloverride_requiredexport当您替换导入的项目中的常量的值时,您的项目将使用您使用 override_constant 参数指定的值。

例如,假设您在单个 Looker 实例上管理多个数据库,并且每个数据库都有一个单独的项目。另外,还假设每个数据库的数据架构都相同,并且您的目标是定义一次分析,然后将其应用于每个数据集。

在此示例中,假设 proj_core 是基础项目,您在其中定义了要导入其他项目的视图。此外,您要导入的视图之一是 orders 视图,该视图的定义如下:


view: orders {
  sql_table_name: "@{schema_name}.orders"
}

orders 视图所依据的架构在 sql_table_name 参数中使用 proj_core 清单文件中定义的 schema_name 常量指定。在以下示例中,由于 schema_name 常量设置为 export: override_required,因此任何导入 schema_name 的项目都必须使用 override_constant 参数替换其值:


constant: schema_name {
  value: "proj_core_schema"
  export: override_required
}

例如,假设您要将 orders 视图导入名为 proj_a 的本地项目。在 proj_a 的数据库中,还有一个名为 orders 的表,其结构与基本项目 proj_core 中的 orders 表完全相同。

由于 proj_coreproj_a 位于同一实例中,因此您可以使用 local_dependencyorders 视图导入 proj_a。然后,您可以使用 local_dependencyoverride_constant 子参数更新 schema_name 常量,使其指向 proj_a 清单文件中的架构 proj_a_schema


project_name: "proj_a"

local_dependency: {
  project: "proj_core"
  override_constant: schema_name {
    value: "proj_a_schema"
  }
}

在此示例中,由于 schema_name 常量在 project_core 中设置为 export: override_required,因此如果您未在 proj_a(导入项目)中替换其值,Looker 将显示错误。

通过替换 proj_a 中的 schema_name 常量,您可以在 proj_core 中使用在 orders 视图中定义的字段,而无需创建新的视图文件并从头开始定义字段。在此示例中,orders 视图对应于每个项目的不同表:

  • proj_core 中,orders 视图基于数据库中的 proj_core_schema.orders 表。
  • proj_a 中,orders 视图基于数据库中的 proj_a_schema.orders 表。