クエリー parameters

クエリ パラメーターを使用すると、実行時にクエリに値を代入できます。 二重中かっこ {{ }} で囲まれた文字列は、クエリ パラメーターとして扱われます。 結果ウィンドウの上にウィジェットが表示され、そこでパラメーター値を設定します。 クエリ パラメーターはクエリ フィルターよりも柔軟性が高く、クエリ フィルターが十分でない場合にのみ使用する必要があります。

クエリー パラメーターを追加する

1. Cmd + Iと入力します。パラメーターがテキストキャレットに挿入され、[ パラメーターの追加 ] ダイアログが表示されます。

   • キーワード: クエリー内のパラメーターを表すキーワード。

   • タイトル: ウィジェット上に表示されるタイトル。 デフォルトでは、タイトルはキーワードと同じです。

   • タイプ: サポートされているタイプは、テキスト、数値、日付、日付と時刻、日付と時刻(秒付き)、ドロップダウンリスト、およびクエリーベースのドロップダウンリストです。 デフォルトは [テキスト] です。

2. キーワードを入力し、必要に応じてタイトルをオーバーライドして、パラメーター タイプを選択します。

3. [ パラメーターの追加] をクリックします。

4. パラメーター ウィジェットで、パラメーター値を設定します。

5. [ 変更の適用] をクリックします。

6. [保存]をクリックします。

または、二重中括弧 {{ }} と入力し、パラメーター ウィジェットの近くにある歯車アイコンをクリックして設定を編集します。

別のパラメーター値でクエリーを再実行するには、ウィジェットに値を入力し、[ 変更の適用] をクリックします。

クエリーパラメータの編集

パラメーターを編集するには、パラメーターウィジェットの横にある歯車アイコンをクリックします。 クエリーを所有していないユーザーがパラメーターを変更できないようにするには、[ 結果のみ表示] をクリックします。 <Keyword> パラメーターダイアログが表示されます。

クエリ パラメーターを削除する

クエリ パラメーターを削除するには、クエリからパラメーターを削除します。 パラメーター ウィジェットが消え、静的な値を使用してクエリを書き換えることができます。

パラメーターの順序を変更する

パラメーターが表示される順序を変更するには、各パラメーターをクリックして目的の位置にドラッグします。

クエリー パラメーターの型

テキスト

文字列を入力として受け取ります。 円記号、一重引用符、二重引用符はエスケープされ、Databricks によってこのパラメーターに引用符が追加されます。 たとえば、 mr's Li"s のような文字列は 'mr\'s Li\"s' これを使用する例は、

SELECT * FROM users WHERE name={{ text_param }}

数

数値を入力として受け取ります。 これを使用する例は次のとおりです。

SELECT * FROM users WHERE age={{ number_param }}

ドロップダウンリスト

クエリの実行時に使用可能なパラメーター値の範囲を制限するには、 ドロップダウン リスト パラメーターの種類を使用します。 たとえば、 SELECT * FROM users WHERE name='{{ dropdown_param }}'です。 パラメーター設定パネルから選択すると、許可された値を入力するテキストボックスが表示され、各値は新しい行で区切られます。 ドロップダウン リストはテキスト パラメーターです。 ドロップダウンリストで日付または日付と時刻を使用するには、データソースに必要な形式で入力します。 文字列はエスケープされません。 単一値または複数値のドロップダウンを選択できます。

• 単一値: パラメーターを単一引用符で囲む必要があります。

• 複数値: [ 複数の値を許可] オプションを切り替えます。 [ 引用符 ] ドロップダウンで、パラメーターを入力したままにするか (引用符なし)、パラメーターを一重引用符または二重引用符で囲むかを選択します。 引用符を選択した場合は、パラメーターを引用符で囲む必要はありません。

クエリで IN キーワードを使用するように WHERE 句を変更します。

SELECT ...
FROM   ...
WHERE field IN ( {{ Multi Select Parameter }} )

パラメーター複数選択ウィジェットを使用すると、複数の値をデータベースに渡すことができます。 [引用符] パラメーターに [二重引用符] オプションを選択すると、クエリーは次の形式を反映します。 WHERE IN ("value1", "value2", "value3")

クエリベースのドロップダウンリスト

クエリの結果を入力として受け取ります。 これは、 ドロップダウン リスト パラメーターと同じ動作をします。 Databricks SQL ドロップダウン リスト クエリを保存して、別のクエリの入力として使用する必要があります。

1. 設定パネルの「 タイプ 」の下にある 「クエリー・ベースのドロップダウン・リスト」 をクリックします。

2. [ クエリ ] フィールドをクリックし、クエリを選択します。 ターゲットクエリが多数のレコードを返すと、パフォーマンスが低下します。

ターゲット クエリーが複数の列を返す場合、Databricks SQL は 最初の 列を使用します。 ターゲット クエリーが name 列と value 列を返す場合、Databricks SQL はパラメーター選択ウィジェットに name 列を設定しますが、関連付けられた valueを使用してクエリーを実行します。

たとえば、次のクエリーがテーブル内のデータを返すとします。

SELECT user_uuid AS 'value', username AS 'name'
FROM users

値	名前
1001	ジョン・スミス
1002	ジェーン・ドウ
1003	ボビーテーブル

Databricks がクエリを実行すると、データベースに渡される値は 1001、1002、または 1003 になります。

日付と時刻

Databricks には、時間範囲のパラメーター化を簡略化するオプションなど、日付とタイムスタンプの値をパラメーター化するオプションがいくつかあります。 精度の異なる 3 つのオプションから選択します。

オプション	精度	タイプ
日付	日	DATE
日付と時刻	分	TIMESTAMP
日付と時刻 (秒単位)	秒	TIMESTAMP

[範囲パラメーター] オプションを選択する場合は、.start と .end のサフィックスで指定された 2 つのパラメーターを作成します。すべてのオプションは、パラメーターを文字列リテラルとしてクエリに渡します。Databricks では、日付と時刻の値を単一引用符 (') で囲む必要があります。 例えば：

-- Date parameter
SELECT *
FROM usage_logs
WHERE date = '{{ date_param }}'

-- Date and Time Range parameter
SELECT *
FROM usage_logs
WHERE modified_time > '{{ date_range.start }}' and modified_time < '{{ date_range.end }}'

Date パラメーターは、カレンダー選択インターフェイスを使用し、既定値は現在の日付と時刻です。

注

日付範囲パラメーターは、 DATE 型の列に対してのみ正しい結果を返します。 TIMESTAMP 列の場合は、[日付と時刻の範囲] オプションのいずれかを使用します。

動的な日付および日付範囲の値

クエリーに日付または日付範囲のパラメーターを追加すると、選択ウィジェットに青い稲妻アイコンが表示されます。 クリックすると、 today、 yesterday、 this week、 last week、 last month、 last yearなどの動的な値が表示されます。 これらの値は動的に更新されます。

重要

動的な日付と日付範囲は、スケジュールされたクエリーと互換性がありません。

ダッシュボードでのクエリー パラメーターの使用

必要に応じて、クエリでパラメーターまたは静的な値を使用できます。 パラメーター化されたクエリに基づくビジュアリゼーションをダッシュボードに追加すると、ビジュアリゼーションは次のいずれかを使用するように構成できます。

• ウィジェットパラメーター

  ウィジェット パラメーターは、ダッシュボード内の 1 つのビジュアリゼーションに固有であり、ビジュアリゼーション パネルに表示され、指定されたパラメーター値は、ビジュアリゼーションの基になるクエリにのみ適用されます。

• ダッシュボード パラメーター

  ダッシュボード パラメーターは、複数のビジュアリゼーションに適用できます。 パラメーター化されたクエリに基づくビジュアリゼーションをダッシュボードに追加すると、そのパラメーターはデフォルトによってダッシュボード パラメーターとして追加されます。 ダッシュボード パラメーターは、ダッシュボード内の 1 つ以上のビジュアリゼーションに対して構成され、ダッシュボードの上部に表示されます。 ダッシュボード パラメーターに指定されたパラメーター値は、その特定のダッシュボード パラメーターを再利用するビジュアリゼーションに適用されます。 ダッシュボードには複数のパラメーターを含めることができ、各パラメーターは一部のビジュアリゼーションに適用し、他のビジュアリゼーションには適用できません。

• 静的な値

  静的な値は、変更に応答するパラメーターの代わりに使用されます。 静的な値を使用すると、パラメーターの代わりに値をハードコードでき、パラメーターが以前に表示されていたダッシュボードまたはウィジェットからパラメーターが「消える」ようになります。

パラメーター化されたクエリーを含むビジュアリゼーションを追加する場合、適切な鉛筆アイコンをクリックして、ビジュアリゼーション クエリー内のパラメーターのタイトルとソースを選択できます。 キーワードとデフォルト値を選択することもできます。 パラメーターのプロパティを参照してください。

ビジュアリゼーションをダッシュボードに追加した後、ダッシュボード ウィジェットの右上にある縦の省略記号をクリックし、[ ウィジェット設定の変更] をクリックして、パラメーター マッピング インターフェイスにアクセスします。

パラメーターのプロパティ

• タイトル: ダッシュボードの値セレクタの横に表示される表示名。 パラメータ キーワードにデフォルト設定します。 編集するには、鉛筆アイコン をクリックします。 静的ダッシュボード パラメーターのタイトルは、値セレクターが非表示になっているため表示されません。 「値のソース」として「静的な値」を選択した場合、「タイトル」フィールドはグレー表示されます。

• キーワード: 基になるクエリ内のこのパラメーターの文字列リテラル。 これは、ダッシュボードが期待した結果を返さない場合のデバッグに役立ちます。

• デフォルト値: 他の値が指定されていない場合に使用される値。 クエリ画面からこれを変更するには、目的のパラメーター値でクエリを実行し、[ 保存 ] ボタンをクリックします。

• 値のソース: パラメーター値のソース。 鉛筆アイコン をクリックしてソースを選択します。

  • 新しいダッシュボード パラメーター: 新しいダッシュボード レベルのパラメーターを作成します。 これにより、ダッシュボードの 1 か所でパラメーター値を設定し、それを複数のビジュアリゼーションにマップできます。

  • 既存のダッシュボード パラメーター: パラメーターを既存のダッシュボード パラメーターにマップします。 既存のダッシュボード パラメーターを指定する必要があります。

  • ウィジェットパラメーター: ダッシュボードウィジェット内に値セレクターを表示します。 これは、ウィジェット間で共有されない 1 回限りのパラメーターに役立ちます。

  • 静的な値: 他のウィジェットで使用されている値に関係なく、ウィジェットの静的な値を選択します。 静的にマッピングされたパラメーター値は、ダッシュボードのどこにも値セレクターを表示せず、よりコンパクトになります。 これにより、特定のパラメーターが頻繁に変更されることが予想される場合に、ダッシュボード上のユーザー インターフェイスを乱雑にすることなく、クエリ パラメーターの柔軟性を活用できます。

  

よくある質問（FAQ）

1 つのクエリーで同じパラメーターを複数回再利用できますか?

はい。中括弧で囲んで同じ識別子を使用します。 この例では、 {{org_id}} パラメーターを 2 回使用します。

SELECT {{org_id}}, count(0)
FROM queries
WHERE org_id = {{org_id}}

1つのクエリーで複数のパラメーターを使用できますか?

はい。各パラメーターに一意の名前を使用します。 この例では、 {{org_id}} と {{start_date}}の 2 つのパラメーターを使用します。

SELECT count(0)
FROM queries
WHERE org_id = {{org_id}} AND created_at > '{{start_date}}'