您可以将文件从其他 LookML 项目和外部代码库导入当前项目。这样,您就可以在多个项目中使用模型文件、查看文件和其他文件。
这有多种使用情形。例如:
在已安装的 Looker Block 之上构建,而无需直接更改。如果 Looker 对块进行了更改,您可以将更改导入,因为您添加到其中的所有 LookML 都保存在单独的代码库中。
维护一个根据数据库架构自动生成的基础项目。您可以将所有自定义维度、测量值等内容放在单独的项目中,从自动生成的项目中导入所有 LookML。您可以在数据库架构发生变化时定期重新生成基本项目,而无需覆盖所有自定义 LookML。
将共享对象封装在单个项目中,然后将其导入到多个其他项目中。例如,如果您有一个由多个数据库共用的表,则可以将该表的视图放在一个项目中并在同一位置对其进行维护。然后,让多个其他项目通过将表导入这些项目来使用它。
如需从其他项目导入文件,请执行以下任务:
- 创建项目清单文件。
- 指定要导入的本地或远程项目。
- 查看已导入项目中的文件。
- 包含导入项目中的文件。
然后,您就可以引用已导入项目文件中的字段,并替换已导入项目中定义的常量的值(如果这些常量允许替换)。
创建项目清单文件
从其他项目导入文件的任何项目都必须具有项目清单文件。如果您的项目还没有清单文件,您可以使用 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_dependency
的 ref
子参数中指定了 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 按钮。
点击 Update Dependencies 以导入远程项目文件。如果这是您向项目添加的第一个远程依赖项,更新依赖项时也会提示 Looker 创建清单锁定文件。Looker 使用清单锁文件来跟踪远程项目的版本。
如果您在 ref
子参数中指定了 Git 分支或 Git 发布标记,Looker 会在 Looker IDE 刷新时检查是否有新的提交内容。当 Looker 开发者进入开发模式、在 IDE 中执行 Git 操作或刷新浏览器时,就会发生此情况。
如果存在新的提交内容,Looker 会在 IDE 的“Git 操作”面板中显示 Update Dependencies 选项。
选择 Update Dependencies 选项,将最新的远程项目文件导入到项目中。
获得最新文件后,您可以验证 LookML,以验证所有项目引用都适用于更新后的远程项目文件。然后,您可以修复任何损坏的引用并部署更改,而无需停机。
清单锁定文件
Looker 使用文件名为 manifest_lock.lkml
的清单锁定文件来跟踪远程导入项目的版本。Looker IDE 的文件浏览器面板中会列出清单锁定文件。
Looker 开发者无需创建或修改清单锁定文件,因为锁定文件由 Looker 自动管理。
清单锁定文件会显示每个远程项目,由包含 url
和 ref
子参数的 remote_dependency
条目表示:
remote_dependency
参数表示 Looker 开发者在清单文件中指定的远程项目的名称。url
子参数表示 Looker 开发者在清单文件中指定的外部 Git 代码库的地址。ref
子参数显示 Looker 在项目中使用的项目版本(以提交 SHA 表示):- 如果远程项目是使用 Git 分支的
ref
或 Git 发布标记在清单文件中定义的,则ref
参数会显示您的项目当前使用的文件版本(远程项目提交 SHA)。如果远程项目中有新的提交内容,Looker 会在 IDE 中显示 Update Dependencies 按钮,以便您导入最新的远程项目文件。然后,系统会更新清单锁定文件中的ref
值,以显示该分支或版本标记的最新提交 SHA。 - 如果在清单文件中使用特定提交 SHA 的
ref
定义了远程项目,则清单锁定文件中的ref
参数将是相同的提交 SHA。
- 如果远程项目是使用 Git 分支的
为专用远程仓库配置身份验证凭据
如需为专用远程仓库配置身份验证凭据,请在 IDE 左侧导航窗格中选择 Settings
,以前往 Import Credentials 页面。导入凭据设置会显示项目清单文件中已定义的每个远程代码库的网址列表、用于代码库的身份验证类型(https
或 ssh
),以及 Looker 能否成功连接到代码库。
添加身份验证凭据
如需为代码库添加身份验证凭据,请执行以下操作:
在导入凭据页面的网址标题下,将指针悬停在代码库名称上以显示测试和配置按钮,然后点击配置。
Looker 会显示配置 Git 身份验证 (Configure Git Authentication) 对话框,允许您为远程代码库配置凭据。该对话框将指明该特定代码库所需的凭据类型。
如果代码库要求提供用户名和密码(或个人访问令牌)进行身份验证,请输入您的用户名和密码或令牌,然后点击保存更改。
如果代码库需要 SSH 密钥(如本页前面介绍的使用 SSH 导入远程项目的示例中所述),Looker 会显示一个对话框,其中会显示您的本地 SSH 密钥。点击复制密钥,将 SSH 密钥复制到剪贴板,并将其添加到代码库的密钥列表中。
保存凭据后,点击测试以测试 Looker 对代码库的访问权限。
通过连接测试并连接到代码库后,Import Credentials 部分会在代码库名称旁边显示一个绿色对勾标记。
修改身份验证凭据
如需修改代码库的身份验证凭据,请执行以下操作:
如需显示 Test 和 Edit 按钮,请将指针悬停在已配置身份验证凭据的代码库上,然后点击 Edit。
如果代码库要求提供用户名和密码(或个人访问令牌)进行身份验证,请点击 Clear Credentials(清除凭据),然后在确认对话框中点击 Yes, clear credentials(是,清除凭据)。
在 Configure Git Authentication(配置 Git 身份验证)对话框中输入新凭据,然后点击 Save Changes(保存更改)。
查看导入项目中的文件
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
),则文件 B
将包含在 A
文件中,然后文件 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
参数具有以下可能的值:
none
:export
的默认值。在导入项目中无法替换该常量的值。导入项目会使用导入项目的清单文件中指定的常量值。override_optional
:可以选择在导入项目中替换常量的值。如果导入项目的清单文件中未提供值,系统将使用所导入项目中的原始值。override_required
:导入项目必须替换最初在导入项目的清单文件中指定的常量值。如果导入项目中未提供新的常量值,Looker 会显示错误。
将引用常量的文件导入项目时,您可以使用项目清单文件中 local_dependency
或 remote_dependency
的 override_constant
子参数为该常量提供新值,前提是该常量在其原始项目中已设置为 override_optional
或 override_required
。export
如果您替换已导入项目中的常量值,项目将使用您通过 override_constant
参数指定的值。
例如,假设您在单个 Looker 实例上管理多个数据库,并且每个数据库都有一个单独的项目。另外,还假设每个数据库的数据架构都相同,并且您的目标是定义一次分析,然后将其应用于每个数据集。
在此示例中,假设 proj_core
是基础项目,您在其中定义了要导入其他项目的视图。此外,您要导入的其中一个视图是 orders
视图,其定义如下:
view: orders {
sql_table_name: "@{schema_name}.orders"
}
orders
视图所依据的架构在 sql_table_name
参数中使用 schema_name
常量指定,该常量在 proj_core
清单文件中定义。在以下示例中,由于 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_core
和 proj_a
位于同一实例上,因此您可以使用 local_dependency
将 orders
视图导入 proj_a
中。然后,您可以使用 local_dependency
的 override_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"
}
}
在此示例中,由于 project_core
中的 schema_name
常量设置为 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
表。