名前付きマーカーを使用する

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

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

SQL エディター (新規およびレガシー)
ノートブック
AI/BIダッシュボードデータセットエディタ
Genieスペース

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

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

この例では、名前付きクエリを使用するようにハードコードされたクエリを変換します。

クエリを開始します:

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

WHERE句から5削除します。
代わりに:fare_parameterと入力してください。最後の行はfare_amount < :fare_parameter表示されるはずです。
「問題」ウィジェットの近くにある歯車アイコンをクリックします。
タイプ を 「10進数」 に設定してください。
「問題」ウィジェットに値を入力し、 「変更を適用」 をクリックします。
[ 保存 ]をクリックします。

争点の種類

問題設定パネルで問題タイプを設定します。この型により、 Databricks実行時に値をどのように解釈して処理するかが決まります。

タイプ	説明
String	自由形式のテキスト。バックスラッシュ、シングルクォーテーション、ダブルクォーテーションは自動的にエスケープされます。Databricksは値の周りに引用符を追加します。
Integer	整数値。
Decimal	小数値もサポートする数値。
日付	日付の値。カレンダーピッカーを使用し、デフォルトでは現在の日付を選択します。
タイムスタンプ	日付と時刻の値。カレンダーピッカーを使用し、デフォルトでは現在の日時を選択します。

名前付きの構文例

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

日付を挿入

SQL
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

数字を入力してください

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

フィールド名を挿入

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

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

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

複数の論点を指定してIDENTIFIER関数を使用して、ランタイム時にカタログ、スキーマ、テーブルを指定します。

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

IDENTIFIER 句を参照してください。

複数の論点を連結する

format_stringを使用して、問題を単一の書式設定された文字列に結合します。 format_string関数を参照してください。

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

JSON文字列の操作

from_json関数を使用して、問題をキーとして使用してJSON文字列から値を抽出します。 :param値としてaを代入すると1が返されます。

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

インターバルを作成する

時間ベースの計算のために、問題値をINTERVALタイプに変換するには、 CAST使用します。インターバル型を参照してください。

SQL
SELECT CAST(:param AS INTERVAL MINUTE)

`.min`を使用して日付範囲を追加します。 `.max`

日付とタイムスタンプは範囲ウィジェットをサポートしています。範囲の開始位置と終了位置にアクセスするには、 .minと.maxを使用します。

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

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

2 つの問題を使用して日付範囲を追加します

SQL
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保留値として渡します。

SQL
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を使用して、単一の文字列として渡される値のカンマ区切りのリストをフィルターします。 SPLITカンマ区切りの文字列を配列に解析します。TRANSFORM各要素から空白文字を削除します。ARRAY_CONTAINS 、結果の配列にテーブルの値が出現するかどうかを確認します。

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

注記

この例は文字列値に対して有効です。他のデータ型を使用するには、 TRANSFORM操作をCASTで囲んで、要素を目的の型に変換します。

構文移行リファレンス

クエリをMustache構文から名前付き問題マーカーに変換する場合は、このテーブルを使用します。従来の構文の詳細については、「Mustache 構文」を参照してください。

ユースケース	口ひげ構文	名前付きの構文
日付で絞り込む	`WHERE date_field < '{{date_param}}'`	`WHERE date_field < :date_param`
数値で絞り込む	`WHERE price < {{max_price}}`	`WHERE price < :max_price`
文字列を比較する	`WHERE region = '{{region_param}}'`	`WHERE region = :region_param`
テーブルを指定します	`SELECT * FROM {{table_name}}`	`SELECT * FROM IDENTIFIER(:table)` — 3階層のネームスペース全体を使用する
カタログ、スキーマ、およびテーブルを指定します。	`SELECT * FROM {{catalog}}.{{schema}}.{{table}}`	`SELECT * FROM IDENTIFIER(:catalog \|\| '.' \|\| :schema \|\| '.' \|\| :table)`
複数の問題から文字列をフォーマットする	`"({{area_code}}) {{phone_number}}"`	`format_string("(%d) %d", :area_code, :phone_number)`
インターバルを作成してください	`SELECT INTERVAL {{p}} MINUTE`	`SELECT CAST(format_string("INTERVAL '%s' MINUTE", :param) AS INTERVAL MINUTE)`

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

争点の種類​

名前付きの構文例​

日付を挿入​

数字を入力してください​

フィールド名を挿入​

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

複数の論点を連結する​

JSON文字列の操作​

インターバルを作成する​

.minを使用して日付範囲を追加します。 .max​

2 つの問題を使用して日付範囲を追加します​

ロールアップの粒度をパラメータ化する​

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

構文移行リファレンス​