用法
map_layer: company_regions {
feature_key: "ISO_A3"
file: "/map_folder/regions.json"
format: topojson
label: "desired label for chart visualization"
max_zoom_level: 12
min_zoom_level: 2
projection: airy
property_key: "ISO_A3"
property_label_key: "NAME"
}
|
层次结构
map_layer |
默认值
无
接受
地图图层的标识符,以及定义地图图层属性的子参数。
|
定义
借助 map_layer 参数,您可以定义自定义地图图层,然后使用该图层在 Looker 中绘制区域数据(例如县或邮政编码),并创建地图图表。
如果存在地图图层,通常会选择交互式地图可视化图表作为默认地图可视化图表。唯一的例外是美国各州地图,Looker 默认使用静态地图区域图表,因为它会为阿拉斯加和夏威夷使用插图。
地图图层可以接受 TopoJSON 或 GeoJSON 文件。自定义地图图层仅支持线和多边形几何图形,不支持点几何图形。如需使用纬度和经度坐标在地图上绘制点数据,请改为定义 type: location 维度。
如需详细了解如何创建自定义地图图层文件,请参阅创建自定义地图区域最佳实践页面。
Looker 建议您将自定义地图图层文件的大小控制在 5 MB 以下,以免用户浏览器标签页超载。
内置地图图层
Looker 包含多个内置地图图层。在创建自己的地图图层之前,请先检查是否可以使用以下内置地图图层之一:
countries和us_states内置地图图层会使用正确的大小写形式来显示国家/地区和州的名称。数据会以区分大小写的方式绘制到地图图层中,因此您的数据也必须使用正确的大小写,才能使用这些内置地图图层。例如,如果您的数据集使用小写“new delhi”,则数据将无法在内置地图图层上正确绘制,因为内置地图图层使用的是“New Delhi”。
countries- 接受完整的国家/地区名称、ISO 3166-1 alpha-3 三字母国家/地区代码或 ISO 3166-1 alpha-2 双字母国家/地区代码。请注意,您在数据集中只能使用这三个选项中的一个,不能混合使用。如果您的数据使用 ISO 3166-1 alpha-2,请在国家/地区维度的定义中添加
map_layer_name参数,以确保 Looker 将您的数据识别为国家/地区代码,而不会将数据错误地解读为州/省级行政区代码。例如:
dimension: country {
type: string
map_layer_name: countries
sql: ${TABLE}.country ;;
}
uk_postcode_areas- 接受英国邮政编码区(例如,L表示利物浦,RH表示雷德希尔,EH表示爱丁堡)。us_states- 接受完整的州名和两个字母的州名缩写。us_counties_fips- 适用于包含美国县的 5 字符 FIPS 县代码的字符串字段。此图层仅适用于互动式地图。us_zipcode_tabulation_areas- 适用于包含 5 位美国邮政编码的字符串字段。type: zipcode的维度会自动使用us_zipcode_tabulation_areas地图图层。邮政编码区域基于 2010 年邮政编码统计区域 (ZCTA),因此该地图图层不包含许多邮政编码,例如分配给邮政信箱的邮政编码,这些邮政编码不会直接映射到区域。
指定地图图层
您可以使用文件名或网址来指定映射的位置。
使用 GeoJSON 文件时,您必须使用 file 或 url 子参数。您也可以选择使用 property_key 和 property_label_key。GeoJSON 文件不支持 feature_key 子参数。添加 GeoJSON 地图图层的一般语法如下:
map_layer: identifier {
file: "/file_path/file_name.geojson" # or use the url subparameter
url: "string" # or use the file subparameter
property_key: "string"
property_label_key: "string"
}
添加 TopoJSON 地图图层的一般语法如下:
map_layer: identifier {
extents_json_url: "string"
feature_key: "string"
file: "/file_path/file_name.json" # or use the url subparameter
format: topojson | vector_tile_region
label: "string"
max_zoom_level: number
min_zoom_level: number
projection: airy # or one of many other choices
property_key: "string"
property_label_key: "string"
url: "string" # or use the file subparameter
}
其中:
| 参数 | 类型 | 说明 |
|---|---|---|
identifier |
字符串 | 您在 LookML 中引用的地图名称。 |
file |
字符串 | 地图的位置,由 LookML 项目中 JSON 文件的名称指定。该文件必须采用 TopoJSON 或 GeoJSON 格式,并使用以下扩展名之一:.json、.geojson 或 .topojson。您必须使用 JSON 文件的完整路径,例如 /maps/ 目录中文件的 "/maps/countryobjects.json"。如果 JSON 文件位于根目录中,而不是在文件夹中,您可以使用单个正斜线表示根目录,如下所示:"/countryobjects.json"如果您的项目未启用文件夹,Looker 会在 LookML IDE 文件列表的数据部分中显示 JSON 文件。如需查看上述每种场景的 LookML,请参阅本页面后面的示例部分。 |
extents_json_url |
字符串 | 指向 JSON 文件的网址,该文件定义了地图图层中每个可用区域的地理范围。这些数据用于自动将地图居中显示在可用数据上,以便进行可视化。JSON 文件必须是 JSON 对象,其中键是特征的映射值(由 property_key 指定),值是表示区域的西经、南纬、东经和北纬范围的四个数字组成的数组。该对象必须包含 property_key 的每个可能值的键。例如 extents_json_url: "https://mycompany.com/mapserver/json-extent.js"。如果使用此参数,您必须使用 url 参数指定地图位置。 |
feature_key |
字符串 | 地图图层引用的 TopoJSON 对象的名称。如果未指定,系统将使用第一个对象。 |
format |
关键字topojson 或 vector_tile_region |
区域信息的数据格式。通常,人们会使用 topojson。 |
label |
字符串 | 显示在图表配置界面中。 |
max_zoom_level |
数字 | 地图图层放大时的最大缩放级别(适用于支持缩放的可视化图表)。 |
min_zoom_level |
数字 | 在地图图层中放大时的最小缩放级别(适用于支持缩放的可视化图表)。 |
projection |
关键字 | 在支持多种地理投影的可视化图表中显示时,地图图层的首选地理投影。当您添加投影参数时,LookML 编辑器会列出许多可用的投影。 |
property_key |
字符串 | TopoJSON 数据中要绘制的属性。TopoJSON 支持每个区域的任意元数据。默认情况下,系统会使用第一个匹配的属性。如果您想根据特定元数据属性进行绘制,请在此处指定。 |
property_label_key |
字符串 | TopoJSON 数据中用于为区域添加标签的属性。当映射值(由 property_key 定义)不太容易理解时,此属性非常有用。 |
url |
字符串 | 地图的位置,由包含地图文件的网址指定。 |
示例
请尽可能将映射文件添加到项目中,然后使用 file 参数指向该映射文件。
您必须使用 JSON 文件的完整路径。如果您的项目未启用文件夹,Looker 会在 LookML IDE 文件列表的数据部分中显示 JSON 文件。
例如,如果您的项目已启用文件夹,并且您在名为 maps 的目录中有一个名为 my_neighborhoods.json 的自定义地图,则可以使用如下完整路径:
map_layer: neighborhoods {
file: "/maps/my_neighborhoods.json"
}
如果您的项目不使用文件夹,则上传的地图文件会显示在项目的数据部分中。在这种情况下,您只需提供 my_neighborhoods.json 文件的名称:
map_layer: neighborhoods {
file: "my_neighborhoods.json"
}
或者,您也可以指定自定义 neighborhoods 映射托管在其他位置,例如 https://wherever.com/my_neighborhoods.json:
map_layer: neighborhoods {
url: "https://wherever.com/my_neighborhoods.json"
}
定义地图图层(通过指定文件或使用 url 参数)后,您可以指定应将维度的值与自定义地图上的地理区域相关联。在维度中,使用 map_layer_name 参数指定您在 map_layer 参数中使用的名称。
dimension: neighborhood {
type: string
map_layer_name: neighborhoods # this is your map layer
sql: ${TABLE}.neighborhood_code
}
当您查询此维度并打开可视化图表部分时,Looker 会使用 neighborhoods JSON 文件(如模型文件中的 map_layer 参数所定义)绘制数据图表。
注意事项
静态地图(区域)图表
在静态地图(区域)图表中将地图设置为自动,需要依赖于在 LookML 模型中指定 map_layer,以指定地图图层。如果未设置该参数,用户在选择自动时会收到错误消息,但仍可以使用 Looker 的内置地图。
GeoJSON 文件
与 TopoJSON 文件类似,GeoJSON 文件可以使用 .geojson 或 .json 文件扩展名,但必须包含 GeoJSON 格式的地理数据。使用 GeoJSON 文件时,您必须使用 file 或 url 子参数,并且可以选择使用 property_key 和 property_label_key。
将 map_layer 与 IDE 文件夹搭配使用
如果您为项目启用了 IDE 文件夹,则在为 map_layer 指定项目文件时需要使用路径:
map_layer: neighborhoods {
file: "/maps/my_neighborhoods.json"
}