本地项目导入功能是一项实验性的实验室功能,可用于从本地 LookML 项目导入文件。实验性功能尚未完全开发,可能会发生显著变化或被彻底移除。
从远程或本地 LookML 项目导入文件目前与模型本地化不兼容。
您可以将其他 LookML 项目和外部代码库中的文件导入当前项目中。这样一来,您就可以在多个项目中使用模型文件、查看文件和其他文件。
有几个用例。例如:
在已安装的 Looker Block 之上构建,无需直接对其进行更改。如果 Looker 对代码块进行更改,您可以轻松提取更改,因为您添加到其中的所有 LookML 都会保存在单独的代码库中。
维护基于数据库架构自动生成的基本项目。您可以将所有自定义维度、衡量指标等放置到单独的项目中,而该项目会从自动生成的项目导入所有 LookML。您可以在数据库架构发生变化时定期重新生成基础项目,而不会覆盖所有的自定义 LookML。
将共享对象封装在单个项目中,然后将其导入多个其他项目中。例如,如果您的某个表在多个数据库中是通用的,您可以将它的视图放在一个项目中,并维护这个位置。然后,再将多个表导入这些项目,以便多个其他项目使用它。
如需导入其他项目中的文件,请执行以下任务:
- 创建项目清单文件。
- 指定要导入的本地或远程项目。
- 查看导入的项目中的文件。
- 包含导入的项目中的文件。
然后,您可以引用导入的项目的文件中的字段,并替换导入的项目中定义的常量的值(如果常量允许替换)。
创建项目清单文件
从其他项目导入文件的任何项目都必须具有项目清单文件。如果您的项目还没有清单文件,您可以通过 Looker IDE 中文件浏览器顶部的 + 图标创建一个。
如需导入项目,请在清单中指定这些项目。您可以指定本地或远程项目,如以下部分所述。
导入本地项目
您的 Looker 管理员必须启用本地项目导入实验室功能,才能将本地文件导入到项目中。
只有当导入的项目位于同一 Looker 实例上时,才能使用本地项目导入功能。此外,建议开发者对导入的项目的模型拥有模型权限。如果您的开发者在导入的项目中拥有模型权限,则版本控制将是动态的,也就是说,导入的项目中的更改将立即影响导入该项目的项目。这样一来,开发者便可以在推送至正式版之前验证这两个项目中的更改。此外,对于在两个项目中都拥有模型权限的开发者,导入的项目文件将反映开发者的开发模式状态。因此,如果开发者处于开发模式,Looker IDE 会显示所导入项目的文件的开发模式。如果开发者处于生产模式,Looker IDE 将显示导入项目的生产模式。
如需在本地导入,请使用 project_name
参数指定当前项目。使用一个或多个 local_dependency
参数指定要导入的一个或多个项目:
# This project
project_name: "my_project"
# The project to import
local_dependency: {
project: "my_other_project"
}
在以下情况下,您应使用远程项目导入,而不是本地项目导入:
- 您的开发者在导入的项目的模型中没有模型权限。在这种情况下,Looker 会克隆导入项目的生产模式,并在 IDE 中显示该文件的静态版本。此静态版本绝不会显示文件的开发模式版本,并且可能已在当前的生产模式下过时,但不会提醒开发者。最好使用远程产品导入功能,并提供在远程项目中指定 Git 分支或 Git 版本的
ref
。如果您执行此操作,Looker 将自动检测远程项目中的新提交,以便您的开发者收到提醒,并随后导入最新版本的远程项目文件。 - 您的开发者需要始终使用导入项目的正式版。
- 您的开发者需要处理所导入项目的静态版本。
导入远程项目
在远程导入中,导入的项目不需要位于同一实例上。而是通过其远程 Git 代码库导入项目。
如需导入远程代码库,请使用 remote_dependency
参数提供远程代码库的信息。remote_dependency
参数接受以下信息和子参数:
- 导入的项目的名称,可以是您喜欢的任意名称。在下面的示例中,项目的名称为
ga_360_block
。您可以在include
语句中使用此名称引用 LookML 项目中导入的文件。该名称还会用作 Looker IDE 的imported_projects
文件夹下的文件夹名称。 url
子参数,您可以在其中指定外部 Git 代码库的地址。使用代码库的主网址。ref
子参数,您可以在其中指定 Git 分支、Git 版本标记或 Git 代码库中提交的 SHA。如果您想要进行静态版本控制,则可以指定提交 SHA,这样导入的项目中的更改便不会自动反映在项目中(这是适用于 Looker Blocks 的一个不错的选项)。或者,如果您希望 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
参数后,Android Studio 也会显示 Update Dependencies 按钮:
点击该按钮以导入远程项目文件。如果这是您已添加到项目中的第一个远程依赖项,则更新依赖项时,系统也会提示 Looker 创建清单锁定文件。Looker 使用清单锁定文件来跟踪远程项目的版本。
如果您在 ref
子参数中指定 Git 分支或 Git 版本标记,每当 Looker IDE 刷新时(当 Looker 开发者进入开发模式时)、在 IDE 中执行 Git 操作或刷新浏览器时,Looker 都会检查是否有新的提交内容。
如果有新的提交,Looker 将在 IDE 的 Git 操作面板中显示 Update Dependencies 选项:
选择 Update Dependencies 选项,可将最新的远程项目文件导入您的项目。
有了最新文件后,您可以验证 LookML 以验证项目的所有引用是否都可以与更新后的远程项目文件配合使用。然后,您可以修复任何损坏的参考文件,并在不停机的情况下部署更改。
清单锁定文件
Looker 使用清单锁定文件来跟踪远程导入项目的版本:
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 分支的
为专用远程代码库配置身份验证凭据
导入凭据设置会显示已在项目清单文件中定义的每个远程代码库的网址列表、用于代码库的身份验证类型(https
或 ssh
),以及 Looker 是否能够成功连接到代码库。
添加身份验证凭据
如需为代码库添加身份验证凭据,请执行以下操作:
将鼠标悬停在代码库名称上以显示测试和配置按钮,然后点击配置。
Looker 会显示一个对话框,允许您为远程代码库配置凭据。该对话框会指明该特定代码库所需的凭据类型。
如果代码库要求使用用户名和密码(或个人访问令牌)进行身份验证,请输入用户名和密码或令牌,然后点击保存更改。
如果代码库需要 SSH 密钥(如上面的示例所示),Looker 会显示一个对话框,显示本地 SSH 密钥。点击复制密钥将 SSH 密钥复制到剪贴板,并将其添加到代码库的密钥列表中。
如果您的远程项目是 LookML 代码库,则可能已经有 SSH 密钥,例如在 LookML 项目最初连接到 Git 时添加到代码库的 SSH 密钥。在将新的 SSH 密钥添加到代码库时,保留所有现有的 SSH 密钥。
保存凭据后,点击 Test 按钮以测试 Looker 对代码库的访问权限:
通过连接测试并连接到代码库后,导入凭据部分会在代码库名称旁边显示一个绿色对勾标记。
修改身份验证凭据
如需修改代码库的身份验证凭据,请执行以下操作:
将鼠标悬停在已配置身份验证凭据的代码库上方,以显示测试和修改按钮,然后点击修改:
如果代码库要求使用用户名和密码(或个人访问令牌)进行身份验证,请点击清除凭据,然后在弹出的确认窗口中点击是,清除凭据。
在配置 Git 身份验证弹出式窗口中,输入新凭据,然后点击保存更改。
查看导入的项目中的文件
Looker IDE 在左侧导航窗格中的 imported_projects
文件夹中显示导入的项目文件。您可以点击导入的项目文件以查看其内容:
本地项目和远程项目中的文件会列在 imported_projects
文件夹中。
由于无法修改 IDE 中的文件,因此导入的项目文件不可见。
您还可以通过对象浏览器查看导入的项目文件中的已包含项目的对象。从 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 文件夹的路径,请参阅在 IDE 中使用文件夹文档页面的路径语法部分。
您可以使用通配符来包含多个文件。例如,如需在导入的 e_flights
项目的 /views/
目录中包含所有视图文件,请使用以下代码:
include: "//e_flights/views/*.view"
此外,您可以使用通配符以限定到特定的目录级别,或导入所导入项目中的递归目录:
include: "//e_flights/**/*.view.lkml"
include: "//e_commerce/*/*.view.lkml"
如需了解如何在启用 IDE 文件夹的情况下使用通配符,请参阅在 IDE 中使用文件夹文档页面的通配符示例部分。
包括模型文件
您不能添加其他项目中的模型文件。如果您想跨项目重复使用、优化或扩展“探索”,可以在导入的项目中创建一个单独的探索文件,然后将该探索文件添加到其他项目中。如需了解详情,请参阅 include
参数文档页面的将探索功能添加到模型中部分。
包括包含其他文件的文件
如果您添加了包含其他文件的文件,系统会先解析所有包含项,然后再将文件传递到包含该文件的下一个项目。
例如,在当前项目中,您从另一个项目 (proj_A
) 导入文件 (A
),并且导入的文件包含 include
参数(包含项目 proj_B
中的文件)时,系统会将文件 A
添加到文件 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
子参数为该常量提供新值,只要该常量在其原始项目中设置为 export
或 override_required
即可。当您替换导入的项目中的常量值时,您的项目将使用您通过 override_constant
参数指定的值。
常量仅适用于最初定义项目中的文件。因此,在已导入文件的项目中定义的常量只能由导入的文件使用,而不能供导入项目中定义的文件使用。
如果要在导入项目的文件中使用常量,则应使用
constant
参数在导入项目的清单文件中定义新的常量。以这种方式定义的常量仅适用于导入项目中定义的文件。
例如,假设您要在同一个 Looker 实例上管理多个数据库,其中每个数据库都有一个单独的项目。在此示例中,我们还假设每个数据库的数据架构都相同,您的目标是定义一次分析,然后将其应用于每个数据集。
在此示例中,假设 proj_core
是您在其中定义了要导入其他项目的视图的基础项目。此外,您想要导入的视图之一是 orders
视图,其定义如下:
view: orders {
sql_table_name: "@{schema_name}.orders"
}
orders
视图所依赖的架构使用 schema_name
常量在 sql_table_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
表。