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

預設值 無 接受 地圖圖層的 ID，以及定義地圖圖層屬性的子參數。

定義

map_layer 參數可讓您定義自訂地圖圖層，然後在 Looker 中繪製區域資料 (例如縣市或郵遞區號)，並建立地圖圖表。

如果地圖圖層存在，系統通常會選擇互動式地圖圖表做為預設地圖圖表。但美國州別地圖是例外，因為阿拉斯加和夏威夷使用插頁，因此 Looker 預設會使用靜態地圖區域圖表。

地圖圖層可接受 TopoJSON 或 GeoJSON 檔案。

如要進一步瞭解如何建立自訂地圖圖層檔案，請參閱「建立自訂地圖區域」最佳做法頁面。

為避免使用者瀏覽器分頁負載過重，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 - 適用於美國郡的五個字元 FIPS 郡代碼字串欄位。這個圖層僅適用於互動式地圖。

• us_zipcode_tabulation_areas：適用於五位數的美國郵遞區號字串欄位。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/countryobjects.json" (適用於 /maps/ 目錄中的檔案)。如果 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	字串	顯示在圖表設定 UI 中。
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。

搭配 IDE 資料夾使用 map_layer

如果專案已啟用 IDE 資料夾，指定 map_layer 的專案檔案時，必須使用路徑：

map_layer: neighborhoods {
  file: "/maps/my_neighborhoods.json"
}