範本篩選器和 Liquid 參數

這是進階主題，適用於已具備 SQL 和 LookML 知識的使用者。

Looker 會自動為使用者提供建立篩選器的功能，讓他們可以根據維度和計量項目操作查詢。雖然這種方法適用於許多用途，但無法滿足所有分析需求。範本篩選器和 Liquid 參數可大幅擴大支援的可能用途。

從 SQL 的角度來看，維度和測量指標只能變更查詢中最外層的 WHERE 或 HAVING 子句。不過，您可能會發現，您想讓使用者操作 SQL 的其他部分。您可以使用範本篩選器和 Liquid 參數調整衍生資料表的部分內容、調整要查詢的資料庫資料表，或建立多用途維度和篩選器等功能。

範本式篩選器和 Liquid 參數會使用 Liquid 範本語言，將使用者輸入內容插入 SQL 查詢。首先，您可以使用 LookML 參數建立欄位，供使用者進行互動。接著，您可以使用 Liquid 變數，將使用者輸入內容插入 SQL 查詢。

範例

以下舉幾個範例，說明範本式篩選器和 Liquid 參數的價值。

使用範本篩選器建立動態衍生表

請考慮衍生表，該表會計算北東區內顧客的終身支出：

view: customer_facts {
  derived_table: {
    sql:
      SELECT
        customer_id,                        -- Can be made a dimension
        SUM(sale_price) AS lifetime_spend   -- Can be made a dimension
      FROM
        order
      WHERE
        region = 'northeast'                -- Can NOT be made a dimension
      GROUP BY 1
    ;;
  }
}

在這個查詢中，您可以使用 customer_id 和 lifetime_spend 建立維度。不過，假設您希望使用者能夠指定 region，而不是將其硬式編碼為「northeast」。region 無法以維度形式顯示，因此使用者無法正常篩選。

其中一個選項是使用範本篩選器，如下所示：

view: customer_facts {
  derived_table: {
    sql:
      SELECT
        customer_id,
        SUM(sale_price) AS lifetime_spend
      FROM
        order
      WHERE
        {% condition order_region %} order.region {% endcondition %}
      GROUP BY 1
    ;;
  }

  filter: order_region {
    type: string
  }
}

如需詳細的逐步操作說明，請參閱「基本用法」一節。

使用 Liquid 參數建立動態評估指標

請考慮使用加總售出褲子數量的篩除指標：

measure: pants_count {
  filters: [category: "pants"]
}

這很簡單，但如果有數十個類別，就必須為每個類別建立一項評量指標，這會很費時。此外，這可能會讓使用者在探索中看到過多內容。

您也可以建立動態評估指標，如下所示：

measure: category_count {
  type: sum
  sql:
    CASE
      WHEN ${category} = '{% parameter category_to_count %}'
      THEN 1
      ELSE 0
    END
  ;;
}

parameter: category_to_count {
  type: string
}

如需詳細的逐步操作說明，請參閱「基本使用方式」一節。

基本用法

步驟一：建立使用者可互動的內容

  • 如果是範本篩選器，請新增 filter。
  • 針對 Liquid 參數，請新增 parameter。

無論是哪種情況，使用者都會在欄位挑選器的「Filter-Only Fields」部分看到這些欄位。

filter 和 parameter 欄位皆可接受一系列子參數，讓您自訂其運作方式。如需完整清單，請參閱「欄位參數」說明文件頁面。parameter 欄位有兩個特別值得一提的選項。

首先，parameter 欄位可以有一種稱為「未標示」的特殊類型：

parameter: table_name {
  type: unquoted
}

這類型可讓您在 SQL 中插入值，而不需要像字串那樣以引號括住。當您需要插入 SQL 值 (例如資料表名稱) 時，這項功能就很實用。

其次，parameter 欄位有一個名為「允許的值」的選項，可讓您將友善的名稱與要插入的值建立關聯。例如：

  parameter: sale_price_metric_picker {
    description: "Use with the Sale Price Metric measure"
    type: unquoted
    allowed_value: {
      label: "Total Sale Price"
      value: "SUM"
    }
    allowed_value: {
      label: "Average Sale Price"
      value: "AVG"
    }
    allowed_value: {
      label: "Maximum Sale Price"
      value: "MAX"
    }
    allowed_value: {
      label: "Minimum Sale Price"
      value: "MIN"
    }
  }

步驟二：套用使用者輸入內容

第二步是使用 Liquid，視需要新增範本篩選器或 Liquid 參數。

範本篩選器

範本篩選器的語法如下：

{% condition filter_name %} sql_or_lookml_reference {% endcondition %}
  • condition 和 endcondition 這兩個字詞永遠不會變更。
  • 將 filter_name 替換為您在第一步驟中建立的篩選器名稱。如果您未建立僅限篩選器的欄位，也可以使用維度。
  • 將 sql_or_lookml_reference 替換為應設為與使用者輸入內容「相等」的 SQL 或 LookML (本節後續會進一步說明)。如果使用 LookML，請使用 ${view_name.field_name} LookML 語法。

在上一個範例「使用範本篩選器建立動態衍生資料表」中，我們使用了：

{% condition order_region %} order.region {% endcondition %}

請務必瞭解 Liquid 標記與您在標記之間撰寫的 SQL 之間的互動關係。這些範本篩選器標記一律會轉換為邏輯運算式。舉例來說，如果使用者在 order_region 篩選器中輸入「Northeast」，Looker 就會將這些標記轉換為以下格式：

order.region = 'Northeast'

換句話說，Looker 會解讀使用者輸入內容，並產生適當的邏輯運算式。

由於範本篩選器會傳回邏輯運算式，因此您可以將這些篩選器與其他在 SQL WHERE 陳述式中有效的邏輯運算子和邏輯運算式搭配使用。以上述範例為例，如果您想傳回使用者選取的區域「以外」的所有值，可以在 WHERE 陳述式中使用以下語法：

NOT ({% condition order_region %} order.region {% endcondition %})

您也可以使用 LookML 欄位做為篩選器條件。任何直接套用至 LookML 欄位的篩選器，都會決定 WHERE 陳述式的值：

view: customer_facts {
  derived_table: {
    sql:
      SELECT
        customer_id,
        SUM(sale_price) AS lifetime_spend
      FROM
        order
      WHERE
        {% condition region %} order.region {% endcondition %}
      GROUP BY 1
    ;;
  }

  dimension: region {
    type: string
    sql: ${TABLE}.region ;;
}

液體參數

Liquid 參數的語法如下：

{% parameter parameter_name %}
  • parameter 這個字詞永遠不會變更。
  • 將 parameter_name 替換為您在第一步驟中建立的 parameter 名稱。

舉例來說，如要套用 第一步中 parameter 欄位的輸入內容，您可以建立如下的評估項目：

  measure: sale_price_metric {
    description: "Use with the Sale Price Metric Picker filter-only field"
    type: number
    label_from_parameter: sale_price_metric_picker
    sql: {% parameter sale_price_metric_picker %}(${sale_price}) ;;
    value_format_name: usd
  }

選擇使用範本篩選器或 Liquid 參數

雖然範本篩選器和 Liquid 參數類似，但兩者之間有一個重要差異：

  • Liquid 參數會直接插入使用者輸入內容 (或使用您透過允許的值定義的值)。
  • 範本篩選器會將值插入為邏輯陳述式，詳情請參閱「範本篩選器」一節。

如果您想為使用者提供更彈性的輸入方式 (例如各種日期範圍或字串搜尋)，請盡可能使用範本篩選器。Looker 可解讀使用者輸入內容，並在幕後撰寫適當的 SQL。這樣一來，您就不必考量所有可能的使用者輸入類型。

如果無法插入邏輯陳述式，或是您知道使用者可能輸入的選項有限，請使用 Liquid 參數。