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 檔案。自訂地圖圖層僅支援線和多邊形幾何圖形,不支援點幾何圖形。如要使用經緯度座標在地圖上繪製點資料,請改為定義 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:適用於字串欄位,該欄位為美國郡縣的五字元 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/ 目錄中的檔案為 "/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。

搭配 IDE 資料夾使用 map_layer

如果專案已啟用 IDE 資料夾,則為 map_layer 指定專案檔案時,必須使用路徑:

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