次の方法で共有

クエリ パラメーター

  • [アーティクル]

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

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

  1. 「 Cmd + I」と入力します。 パラメーターがテキスト キャレットの位置に挿入され、[パラメーターの追加] ダイアログが表示されます。
    • キーワード: クエリ内のパラメーターを表すキーワード。
    • タイトル: ウィジェットの上に表示されるタイトル。 既定では、タイトルはキーワードと同じです。
    • 種類: サポートされる型は、テキスト、数値、日付、日付と時刻、日付と時刻 (秒を含む)、ドロップダウン リスト、およびクエリ ベースのドロップダウン リストです。 既定値は Text です。
  2. キーワードを入力し、必要に応じてタイトルをオーバーライドして、パラメーターの種類を選択します。
  3. [パラメーター の追加] をクリックします。
  4. パラメーター ウィジェットで、パラメーター値を設定します。
  5. [変更の適用]をクリックします。
  6. [保存] をクリックします。

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

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

クエリ パラメーターを編集する。

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

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

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

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

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

クエリ パラメーターの型

Text

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

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

Number

入力として数値を取ります。 これを使用する例を次に示します。

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

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

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

クエリで 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
value name
1001 John Smith
1002 Jane Doe
1003 Bobby Tables

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

日付と時刻

Azure Databricks には、日付とタイムスタンプの値をパラメーター化するためのオプションがいくつか用意されています。これには、時間範囲のパラメーター化を簡略化するためのオプションも含まれています。 さまざまな精度の 3 つのオプションから選択します。

オプション Precision Type
日付 day DATE
日付と時刻 分 TIMESTAMP
日付と時刻 (秒付き) 秒 TIMESTAMP

Range パラメーター オプションを選択する場合は、.start と .end というサフィックスで指定された 2 つのパラメーターを作成します。 すべてのオプションで、文字列リテラルとしてパラメーターがクエリに渡されます。Azure 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 }}'

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

Note

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

動的な日付と日付範囲の値

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

重要

動的な日付と日付範囲は、スケジュールされたクエリには使用できません。

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

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

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

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

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

    ダッシュボード パラメーターは、複数の視覚化に適用できます。 パラメーター化クエリに基づく視覚化をダッシュボードに追加すると、既定でパラメーターがダッシュボード パラメーターとして追加されます。 ダッシュボード パラメーターは、ダッシュボード内の 1 つ以上の視覚化用に構成され、ダッシュボードの上部に表示されます。 ダッシュボード パラメーターに指定されたパラメーター値は、その特定のダッシュボード パラメーターを再利用する視覚化に適用されます。 ダッシュボードには複数のパラメーターを含めることができます。そのうち、視覚化に適用できるものと、できないものがあります。

  • 静的な値

    静的値は、変更に対応するパラメーターの代わりに使われます。 静的値を使用すると、パラメーターの代わりに値をハード コーディングでき、以前に表示されたダッシュボードまたはウィジェットからパラメーターを "非表示" にします。

パラメーター化クエリを含む視覚化を追加する場合は、適切な鉛筆アイコン をクリックして、視覚化クエリのパラメーターのタイトルとソースを選択できます。 キーワードと既定値を選択することもできます。 「パラメーターのプロパティ」を参照してください。

ダッシュボードに視覚化を追加した後は、ダッシュボード ウィジェットの右上にあるケバブ メニューをクリックし、[ウィジェット設定の変更] をクリックするとパラメーター マッピング インターフェイスにアクセスします。

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

  • タイトル: ダッシュボードの値セレクターの横に表示される表示名。 既定値は Keyword パラメーターです。 編集するには、鉛筆アイコン 鉛筆アイコン をクリックします。 値セレクターが非表示のため、静的ダッシュボード パラメーターのタイトルは表示されません。 [値のソース] として [静的な値] を選んだ場合、[タイトル] フィールドは淡色表示されます。

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

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

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

    • 新しいダッシュボード パラメーター: 新しいダッシュボード レベルのパラメーターを作成します。 これにより、ダッシュボードの 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}}'