Visual Studio Code 用 Databricks Driver for SQLTools

重要

この機能はパブリック プレビュー段階にあります。

Databricks Driver for SQLTools を使用すると、Visual Studio Code用 SQLTools 拡張機能を使用して SQL オブジェクトを参照したり、リモートの Azure Databricks ワークスペースで SQL クエリを実行したりできます。

開始する前に

Databricks Driver for SQLTools を使用できる前に、Azure Databricks ワークスペースとローカル開発マシンが次の要件を満たしている必要があります。

• ワークスペースの要件
• ローカル開発マシンの要件
• 認証
  • Azure Databricks 個人用アクセス トークン認証
  • Azure Databricks OAuth マシン間 (M2M) 認証
  • Azure Databricks OAuth ユーザー対マシン (U2M) 認証
  • Azure CLI 認証

ワークスペースの要件

少なくとも 1 つの Azure Databricks ワークスペースを使用でき、ワークスペースが次の要件を満たしている必要があります：

• ワークスペースには、少なくとも 1 つの Databricks SQL ウェアハウスが含まれている必要があります。

  注意

  Azure Databricks クラスター は、Databricks Driver for SQLTools ではサポートされていません。

• Unity Catalog で有効になっているワークスペースの場合、ワークスペースには少なくとも 1 つのカタログが含まれている必要があり、そのカタログ内には少なくとも 1 つのスキーマ (正式にはデータベースと呼ばれます) が含まれている必要があります。

  • データベース オブジェクトを探索する。
  • カタログを作成する。
  • スキーマを作成する。

• Unity Catalog が有効になっていないワークスペースの場合、ワークスペースには少なくとも 1 つのスキーマ (以前はデータベースと呼ばれた) が含まれている必要があります。

  • データベース オブジェクトを探索する。
  • スキーマを作成する。

ローカル開発マシンの要件

ローカル開発マシンには、次のものが必要です：

• Visual Studio Code バージョン 1.70かそれ以降。 インストールされているバージョンを表示するには、Linux または macOS の manin メニューから [Code]> [About Visual Studio Code] をクリックし、Windows の [ヘルプ]> メニューの に関して をクリックします。 Visual Studio Code をダウンロード、インストール、構成するには、Visual Studio Code のセットアップを参照してください。
• Visual Studio Code 用 SQLTools 拡張機能。
• Visual Studio Code 用 Databricks Driver for SQLTools 拡張機能。

SQLTools 拡張機能をインストールするには、SQLTools に移動し、[インストール] をクリックするか、次の 手順を実行します：

1. Visual Studio Code で、メイン メニューの [ビュー]> [拡張機能] をクリックします。

2. [Marketplace で拡張機能を検索する] ボックスに、「SQLTools」と入力します。

3. [Matheus Teixeira] から [SQLTools] エントリをクリックします。

   注意

   複数の [SQLTools] エントリが リストに表示されている可能性があります。 必ず Matheus Teixeiraのエントリをクリックしてください。

4. [インストール] をクリックします。

Databricks Driver for SQLTools 拡張機能をインストールするには、Databricks Driver for SQLTools に移動し、[インストール] をクリックするか、次の手順を実行します：

1. Visual Studio Code で、メイン メニューの [ビュー]> [拡張機能] をクリックします。
2. [Marketplace で拡張機能を検索する] ボックスに、「Databricks Driver for SQLTools」と入力します。
3. [Databricks Driver for SQLTools] エントリをクリックします。
4. [インストール] をクリックします。

認証

Databricks Driver for SQLTools の認証は、次のように設定する必要があります。

Databricks Driver for SQLTools では、次の Azure Databricks 認証の種類がサポートされています。

• Azure Databricks 個人用アクセス トークン認証
• Azure Databricks OAuth マシン間 (M2M) 認証
• Azure Databricks OAuth ユーザー対マシン (U2M) 認証
• Azure CLI 認証

Note

Databricks Driver for SQLTools は、Microsoft Entra ID トークンをサポートしていません。

Azure Databricks 個人用アクセス トークン認証

Databricks Driver for SQLTools を Azure Databricks の個人用アクセス トークン認証で使用するには、Azure Databricks 個人用アクセス トークンが必要です。 個人用アクセス トークンを作成するには、次の操作を行います。

1. Azure Databricks ワークスペースの上部バーで、目的の Azure Databricks ユーザー名をクリックし、次にドロップダウンから [設定] を選択します。
2. [開発者] をクリックします。
3. [アクセス トークン] の横にある [管理] をクリックします。
4. [新しいトークンの生成] をクリックします。
5. (省略可能) 将来このトークンを識別するのに役立つコメントを入力し、トークンの既定の有効期間 90 日を変更します。 有効期間のないトークンを作成するには (推奨されません)、[有効期間 (日)] ボックスを空のままにします。
6. [Generate](生成) をクリックします。
7. 表示されたトークンを安全な場所にコピーし、[完了] をクリックします。

Note

コピーしたトークンは必ず安全な場所に保存してください。 コピーしたトークンは他人に見せないでください。 コピーしたトークンを失った場合、それとまったく同じトークンは再生成できません。 代わりに、この手順を繰り返して新しいトークンを作成する必要があります。 コピーしたトークンを紛失した場合や、トークンが侵害されていると思われる場合、Databricks では、[アクセス トークン] ページのトークンの横にあるごみ箱 ([取り消し]) アイコンをクリックして、ワークスペースからそのトークンをすぐに削除することを強くお勧めします。

ワークスペースでトークンを作成することや使用することができない場合は、ワークスペース管理者によってトークンが無効にされているか、トークンを作成または使用する権限が作業者に付与されていない可能性があります。 ワークスペース管理者に連絡するか、以下のトピックを参照してください。

• ワークスペースの個人アクセス トークン認証を有効または無効にする
• 個人用アクセス トークンのアクセス許可

Azure Databricks OAuth マシン間 (M2M) 認証

次のように、Azure Databricks OAuth マシン間 (M2M) 認証を使用して、Databricks Driver for SQLTools で認証することができます。

Note

Azure Databricks OAuth M2M 認証は、Databricks Driver for SQLTools バージョン 0.4.2 以上で使用することができます。

1. OAuth M2M 認証の構成手順を完了します。 「OAuth マシン間 (M2M) 認証」を参照してください。
2. OAuth M2M 認証構成設定を使用して、Azure Databricks 構成プロファイルを作成します。 「OAuth マシン間 (M2M) 認証」の「構成」セクションをご参照ください。
3. ローカル開発マシンに Visual Studio Code 用の Databricks 拡張機能をインストールして開きます。
4. Visual Studio Code 用の Databricks 拡張機能で、[構成] ウィンドウの [構成] ボタンをクリックします。 [構成] ボタンが表示されない場合は、代わりに歯車 (ワークスペースの構成) アイコンをクリックします。
5. コマンド パレット内の [Databricks Host] に、Azure Databricks のワークスペースごとの URL (例: https://adb-1234567890123456.7.azuredatabricks.net) を入力して、Enter キーを押します。
6. 手順 2 で作成したものと一致する構成プロファイル エントリを選択します。
7. Web ブラウザー内で画面の指示を実行して、Azure Databricks アカウントで認証を完了します。

Azure Databricks OAuth ユーザー対マシン (U2M) 認証

次のように、Azure Databricks OAuth ユーザー対マシン (U2M) 認証を使用して、Databricks Driver for SQLTools で認証することができます。

Note

Azure Databricks OAuth U2M 認証は、Databricks Driver for SQLTools バージョン 0.4.2 以上で使用することができます。

1. ローカル開発マシンに Visual Studio Code 用の Databricks 拡張機能をインストールして開きます。
2. Visual Studio Code 用の Databricks 拡張機能で、[構成] ウィンドウの [構成] ボタンをクリックします。 [構成] ボタンが表示されない場合は、代わりに歯車 (ワークスペースの構成) アイコンをクリックします。
3. コマンド パレットの Databricks Host に、Azure Databricks のワークスペースごとの URL (例: https://adb-1234567890123456.7.azuredatabricks.net) を入力します。 次に、Enter キーを押します。
4. [OAuth (user to machine)] を選択します。
5. Web ブラウザー内で画面の指示を実行して、Azure Databricks アカウントで認証を完了します。 ダイアログが表示されたら、all-apis アクセスを許可します。

Azure CLI 認証

次のように、Azure CLI を使って Databricks Driver for SQLTools で認証できます。

Note

Azure CLI を使用した認証は、試験段階の機能の状態です。 この機能は、Databricks Driver for SQLTools バージョン 0.4.2 以降で利用できます。

1. ローカル開発マシンに Azure CLI をインストールします (まだインストールしていない場合)。
2. ローカル開発マシンに Visual Studio Code 用の Databricks 拡張機能をインストールして開きます。
3. Visual Studio Code 用の Databricks 拡張機能で、[構成] ウィンドウの [構成] ボタンをクリックします。 [構成] ボタンが表示されない場合は、代わりに歯車 (ワークスペースの構成) アイコンをクリックします。
4. コマンド パレットの Databricks Host に、Azure Databricks のワークスペースごとの URL (例: https://adb-1234567890123456.7.azuredatabricks.net) を入力します。 次に、Enter キーを押します。
5. [Azure CLI] を選びます。
6. 画面上のプロンプトに従って、Azure CLI での認証を完了します。

スキーマに接続する

1. Visual Studio Code、のサイドバーで、[SQLTools] アイコンをクリックします。
2. [SQLTools] ビューの [接続] ウィンドウで、SQLTools 拡張機能を初めて使用する場合は、[新しい接続の追加] をクリックします。 それ以外の場合は、ウィンドウのタイトル バーの [新しい接続の追加] アイコンをクリックします。
3. [SQLTools の設定] タブの [データベース ドライバーの選択] ステップで、[Databricks] アイコンをクリックします。
4. [接続設定] ステップで、ウェアハウス、カタログ、スキーマに関する次の情報を入力します：

   1. [接続名] には、この接続に一意な名前を入力します。

   2. (省略可能) [接続グループ] に、そのグループに新しい接続を追加する既存の接続グループの名前を入力します。 または、一意の名前を入力して、新しい接続を使用して新しい接続グループを作成します。 接続グループを使用すると、拡張機能で接続を簡単に見つけることができます。

   3. [接続方法] で、次のいずれかを選択します。

      • 認証に Azure Databricks 個人用アクセス トークンを使用するには、[ホスト名とトークン] を選択します。
      • Databricks Driver for SQLTools バージョン 0.4.2 以上の場合、OAuth U2M または M2M または Azure CLI 認証を使用するには、[VS Code extension (beta)] を選択します。

   4. [接続に使用する認証] で [ホスト名とトークン] を選択した場合は、[ホスト] に、ウェアハウスの [サーバー ホスト名] 設定を入力します。 ウェアハウスのサーバー ホスト名設定を取得するには、「Azure Databricks コンピューティング リソースの接続の詳細を取得する」を参照してください。

   5. [パス] に、ウェアハウスまたはクラスター、の HTTP パス設定を入力します。 ウェアハウスの HTTP パス設定を取得するには、「Azure Databricks コンピューティング リソースの接続の詳細を取得する」を参照してください。

   6. [Connect using] で [Hostname and Token] を選択した場合は、[Token] 内に Azure Databricks 個人用アクセス トークンの値を入力します。

   7. [カタログ] に、カタログの名前を入力します。

      注意

      Unity Catalog が有効になっていないワークスペースの場合は、Catalog を空白のままにして hive_metastore の既定値を使用できます。

   8. [スキーマ] に、スキーマの名前を入力します。

   9. (省略可能) [レコードの既定の 制限を表示する] では、50 の既定値のままにして、各クエリの最初の 50 行のみを表示するか、別の制限を入力します。

5. [接続テスト]をクリックします。
6. 接続テストに成功した場合、[接続の保存] をクリックします。

接続の設定を変更する

このプロシージャでは、少なくとも 1 つのウェアハウスに正常に接続されていることを前提としています。

1. [SQLTools] ビューが表示されない場合は、Visual Studio Code、のサイドバーで、[SQLTools] アイコンをクリックします。
2. [接続] ウィンドウで、ターゲット接続に対して接続グループが存在する場合は展開します。
3. 接続を右クリックし、[Edit Connection] (接続の編集) をクリックします。
4. ターゲット設定を変更します。
5. [接続テスト]をクリックします。
6. 接続テストに成功した場合、[接続の保存] をクリックします。

スキーマのオブジェクトを参照する

1. [接続] ウィンドウで、ターゲット接続に対して接続グループが存在する場合は展開します。
2. ウェアハウスのターゲット接続をダブルクリックまたは展開します。
3. 接続用にターゲット データベース (スキーマ)が存在する場合は、ターゲット データベース (スキーマ) を展開します。
4. データベース (スキーマ) に 1 つ以上のテーブルまたはビューが存在する場合は、[テーブル] または [ビュー] を展開します。
5. ターゲット テーブルまたはビューを展開して、テーブルまたはビューの列を表示します。

テーブルまたはビューの行またはスキーマを表示する

[接続] ウィンドウで [テーブル] または [ビュー] を展開した状態で、次のいずれかの操作を行います：

• テーブルまたはビューの行を表示するには、テーブルまたはビューを右クリックし、[テーブル レコードの表示] または [ビュー レコードの表示] をクリックします。
• テーブルまたはビューのスキーマを表示するには、テーブルまたはビューを右クリックし、[テーブルの説明] または [ビュー の説明] をクリックします。

テーブルの挿入クエリを生成する

1. 挿入クエリを追加したい場所に、既存のエディターにカーソルを置きます。
2. [接続] ウィンドウで [テーブル] を展開した状態で、テーブルを右クリックし、[クエリの挿入の生成] をクリックします。 挿入クエリの定義は、カーソルの挿入ポイントに追加されます。

クエリを作成して実行する

このプロシージャでは、少なくとも 1 つのウェアハウスに正常に接続されていることを前提としています。

1. [接続] ウィンドウで、ターゲット接続に対して接続グループが存在する場合は展開します。
2. ウェアハウスのターゲット接続をダブルクリックまたは展開します。
3. 接続を選択した状態で、[接続]ウィンドウのタイトル バーで [新しい SQL ファイル] をクリックします。 新しいエディター タブが表示されます。
4. 新しいエディターで SQL クエリを入力します。
5. SQL クエリを実行するには、エディターの [アクティブな接続で実行] をクリックします。 クエリの結果が新しいエディター タブに表示されます。

既存のクエリを実行する

このプロシージャでは、少なくとも 1 つのウェアハウスに正常に接続されていることを前提としています。

1. [接続] ウィンドウで、ターゲット接続に対して接続グループが存在する場合は展開します。
2. ウェアハウスのターゲット接続をダブルクリックまたは展開します。
3. 接続を選択した状態で、.sql のファイル拡張子でファイルを開くか、以前に開いた任意のエディターで連続 SQL ステートメントの任意のグループを選択します。
4. 開いている .sql ファイルから SQL クエリを実行し、.sql ファイルのコンテンツをエディターに表示するには、エディターで [アクティブな接続で実行] をクリックします。 クエリの結果が新しいエディター タブに表示されます。
5. 以前に開いたエディターで、選択した連続 SQL ステートメントのグループを実行するには、選択内容を右クリックし、[選択したクエリの実行] をクリックします。 クエリの結果が新しいエディター タブに表示されます。

使用状況ログを Databricks に送信する

Databricks Driver for SQLTools の使用中に問題が発生した場合は、次の手順を実行して、使用状況ログと関連情報を Databricks サポートに送信することができます。

1. ローカル開発マシンに Visual Studio Code 用の Databricks 拡張機能をインストールします。
2. 「Visual Studio Code 用 Databricks 拡張機能の設定」で説明されているように、[ログ: 有効] 設定をオンにするか、databricks.logs.enabled を true に設定してログを有効にします。ログを有効にしたら、必ず Visual Studio Code を再起動してください。
3. 問題の再現を試みます。
4. コマンド パレット (メイン メニューから[ビュー] > [コマンド パレット]) から、Databricks: Open full logs コマンドを実行します。
5. 表示されるファイル Databricks Logs.log、databricks-cli-logs.json、sdk-and-extension-logs.json を Databricks サポートに送信します。
6. また、問題のコンテキストでターミナル ([ビュー] > [ターミナル]) のコンテンツをコピーし、このコンテンツを Databricks サポートに送信します。

[Logs: Enabled] (ログ: 有効) がオンになっているか、databricks.logs.enabled が true に設定されている場合、[出力] ビュー ([表示] > [Output, Databricks Logs] (出力、Databricks ログ)) には不完全な情報が表示されます。 詳細を表示するには、「Visual Studio Code 用 Databricks 拡張機能の設定」で説明されているように、次の設定を変更します。

• [Logs: Max Array Length](ログ: 配列の最大長) または databricks.logs.maxArrayLength
• [Logs: Max Field Length](ログ: 最大フィールド長) または databricks.logs.maxFieldLength
• [Logs: Truncation Depth](ログ: 切り詰めの深さ) または databricks.logs.truncationDepth

その他のリソース

• SQLTools のドキュメント
• GitHub の [Databricks Driver for SQLTools]