map_layer

用法

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"
}