名前付きパラメーター マーカーを使用する

名前付きパラメーター マーカーを使用すると、実行時に SQL クエリに変数値を挿入できます。 特定の値をハードコーディングする代わりに、クエリの実行時にユーザーが入力する型指定されたプレースホルダーを定義します。 これにより、クエリの再利用が向上し、SQL インジェクションが防止され、柔軟で対話型のクエリの構築が容易になります。

名前付きパラメーター マーカーは、次の Databricks サーフェスで機能します。

• SQL エディター (新規およびレガシ)
• Notebooks
• AI/BI ダッシュボード データセット エディター
• ジーニースペース

名前付きパラメーター マーカーを追加する

コロンの後にパラメーター名 ( :parameter_nameなど) を入力して、パラメーターを挿入します。 名前付きパラメーター マーカーをクエリに追加すると、パラメーターの種類と値を設定できるウィジェットが表示されます。 「パラメーター ウィジェットの操作」を参照してください。

この例では、ハードコーディングされたクエリを変換して、名前付きパラメーターを使用します。

クエリの開始:

SELECT
  trip_distance,
  fare_amount
FROM
  samples.nyctaxi.trips
WHERE
  fare_amount < 5

1. 5句からWHEREを削除します。
2. :fare_parameterをその場所に入力します。 最後の行はfare_amount < :fare_parameterと表示されるべきです。
3. パラメーター ウィジェットの近くにある歯車アイコンをクリックします。
4. 型を Decimal に設定します。
5. パラメーター ウィジェットに値を入力し、[ 変更の適用] をクリックします。
6. 保存 をクリックします。

パラメーターの種類

パラメーター設定パネルでパラメーターの種類を設定します。 この型によって、Databricks が実行時に値を解釈して処理する方法が決まります。

名前付きパラメーター構文の例

次の例は、名前付きパラメーター マーカーの一般的なパターンを示しています。

日付を挿入する

SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  sum(o_totalprice) AS `Total Price`
FROM
  samples.tpch.orders
WHERE
  o_orderdate > :date_param
GROUP BY 1, 2

数値を挿入する

SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  o_totalprice AS Price
FROM
  samples.tpch.orders
WHERE
  o_totalprice > :num_param

フィールド名を挿入する

IDENTIFIER関数を使用して、列名をパラメーターとして渡します。 パラメーター値は、クエリで使用されるテーブルの列名にする必要があります。

SELECT * FROM samples.tpch.orders
WHERE IDENTIFIER(:field_param) < 10000

データベース オブジェクトを挿入する

IDENTIFIER関数を複数のパラメーターと共に使用して、実行時にカタログ、スキーマ、およびテーブルを指定します。

SELECT *
FROM IDENTIFIER(:catalog || '.' || :schema || '.' || :table)

IDENTIFIER の条文を参照してください。

複数のパラメーターを連結する

パラメーターを 1 つの書式設定された文字列に結合するには、 format_string を使用します。 関数format_string参照してください。

SELECT o_orderkey, o_clerk
FROM samples.tpch.orders
WHERE o_clerk LIKE format_string('%s%s', :title, :emp_number)

JSON 文字列を操作する

パラメーターをキーとして使用して JSON 文字列から値を抽出するには、 from_json 関数 を使用します。 aを:paramの値に置き換える場合、1が返されます。

SELECT from_json('{"a": 1}', 'map<string, int>') [:param]

間隔を作成する

CASTを使用して、時間ベースの計算のためにパラメーター値をINTERVAL型に変換します。 「 間隔の種類」を参照してください。

SELECT CAST(:param AS INTERVAL MINUTE)

.minを使用して日付範囲を追加する.max

日付とタイムスタンプのパラメーターは、範囲ウィジェットをサポートします。 .minと.maxを使用して、範囲の先頭と末尾にアクセスします。

SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN :date_range.min AND :date_range.max

パラメーターの種類を Date または Timestamp に設定し、ウィジェットの種類を Range に設定します。

2 つのパラメーターを使用して日付範囲を追加する

SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN CAST(:date_range_min AS TIMESTAMP) AND CAST(:date_range_max AS TIMESTAMP)

ロールアップの細分性をパラメーター化する

DATE_TRUNCを使用して、ユーザーが選択した粒度レベルで結果を集計します。 パラメーター値として DAY、 MONTH、または YEAR を渡します。

SELECT
  DATE_TRUNC(:date_granularity, tpep_pickup_datetime) AS date_rollup,
  COUNT(*) AS total_trips
FROM samples.nyctaxi.trips
GROUP BY date_rollup

複数の値を文字列として渡す

ARRAY_CONTAINS、SPLIT、およびTRANSFORMを使用して、1 つの文字列パラメーターとして渡される値のコンマ区切りのリストでフィルター処理します。 SPLIT は、コンマ区切りの文字列を配列に解析します。 TRANSFORM 各要素から空白をトリミングします。 ARRAY_CONTAINS は、結果の配列にテーブル値が表示されるかどうかを確認します。

SELECT * FROM samples.nyctaxi.trips WHERE
  array_contains(
    TRANSFORM(SPLIT(:list_parameter, ','), s -> TRIM(s)),
    CAST(dropoff_zip AS STRING)
  )

構文移行リファレンス

このテーブルは、クエリを口ひげ構文から名前付きパラメーター マーカーに変換する場合に使用します。 レガシ構文の詳細については、 Mustache パラメーター の構文を参照してください。