Databricks Driver for SQLTools for Visual Studio Code

備考

プレビュー

この機能は パブリック プレビュー段階です。

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

始める前に

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

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

ワークスペースの要件

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

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

注記

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

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

  • データベースオブジェクトを調べてください。
  • カタログを作成します。
  • スキーマを作成します。

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

  • データベースオブジェクトを調べてください。
  • スキーマを作成します。

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

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

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

SQLTools拡張機能をインストールするには、SQLToolsに行き、「インストール」をクリックしてください。または、

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

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

3. Matheus Teixeira の SQLTools エントリをクリックします。

注記

複数の SQLTools エントリがリストされている場合があります。 マテウス・テイシェイラ のエントリーを必ずクリックしてください。

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ドライバーfor SQLToolsは、次のDatabricks認証タイプをサポートしています。

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

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

Databricks 個人用アクセス トークン認証で SQLTools 用の Databricks ドライバーを使用するには、Databricks 個人用アクセス トークンが必要です。 個人用アクセス トークンを作成するには、「ワークスペース ユーザー向けの個人用アクセス トークンDatabricks」の手順に従います。

Databricks OAuth マシン間 (M2M) 認証

Databricks OAuth マシン間 (M2M) 認証 を使用して、次のように SQLTools 用の Databricks ドライバーで認証できます。

注記

Databricks OAuth M2M 認証は、Databricks Driver for SQLTools バージョン 0.4.2 以降で使用できます。

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

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

Databricks OAuth ユーザー間 (U2M) 認証 を使用して、次のように Databricks Driver for SQLTools で認証できます。

注記

Databricks OAuth U2M 認証は、Databricks Driver for SQLTools バージョン 0.4.2 以降で使用できます。

1. Visual Studio Code 用の Databricks 拡張機能をローカル開発マシンにインストールして開きます 。
2. Visual Studio Code の Databricks 拡張機能で、[ 構成 ] ウィンドウの [構成 ] ボタンをクリックします。 [構成 ] ボタンが表示されない場合は、代わりに歯車 ( ワークスペースの構成 ) アイコンをクリックします。
3. コマンド パレット の [Databricks ホスト ] に、Databricks ワークスペース インスタンスの URL を入力します (例: https://dbc-a1b2345c-d6e7.cloud.databricks.com)。次に 、Enter キーを押します。
4. [OAuth (ユーザーからマシン)] を選択します。
5. Web ブラウザーの画面に表示される指示を完了して、Databricks アカウントでの認証を完了します。 プロンプトが表示されたら、 all-apis アクセスを許可します。

スキーマへの接続

1. ビジュアルスタジオコードのサイドバーで、 SQLToolsアイコンをクリックします 。

2. SQLTools ビューで、SQLTools 拡張機能を初めて使用する場合は、[ 接続 ] ペイン内の [ 新しい接続の追加 ] をクリックします。それ以外の場合は、ペインのタイトルバーにある [ Add New Connection ] アイコンをクリックします。

3. [SQLTools 設定 ] タブの [ データベース ドライバーの選択 ] ステップで、[ Databricks ] アイコンをクリックします。

4. [ 接続設定 ] ステップで、ウェアハウス、カタログ、およびスキーマに関する次の情報を入力します。

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

   2. (オプション) [接続グループ ] に、既存の接続グループの名前を入力して、新しい接続をそのグループに追加します。 または、一意の名前を入力します。新しい接続で新しい接続グループを作成します。 接続グループを使用すると、拡張機能で接続を見つけやすくなります。

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

      • 認証に Databricks 個人用アクセス トークンを使用するには、 [ホスト名とトークン ] を選択します。

      • Databricks Driver for SQLTools バージョン 0.4.2 以降で OAuth U2M または M2M 認証を使用するには、 VS Code 拡張機能 (ベータ版) を選択します。

   4. [Connect using ] で [Hostname and token ] を選択した場合は、[ Host ] にウェアハウスの [Server hostname ] 設定を入力します。ウェアハウスの サーバー ホスト名 設定を取得するには、「Databricks コンピュート リソースの接続の詳細を取得する」を参照してください。

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

   6. [接続に使用する 文字列] で [ホスト名とトークン ] を選択した場合は、Databricks 個人用アクセス トークンの値を [トークン ] に入力します。

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

注記

Unity Catalogが有効になっていないワークスペースの場合は、 カタログ を空白のままにして、デフォルトの値 hive_metastore を使用できます。

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

6. (オプション)[ Show records default limit ] で、クエリごとに最初の 50 行までのみを表示するように [ 50 ] のデフォルトのままにするか、別の制限を入力します。

7. [ テスト接続 ] をクリックします。

8. 接続テストが成功したら、[ 接続を保存 ] をクリックします。

接続の設定を変更する

この手順は、少なくとも 1 つのウェアハウスに正常に接続していることを前提としています。

1. SQLTools ビューが表示されない場合は、Visual Studio Code のサイドバーで SQLTools アイコンをクリックします。
2. [ 接続 ] ペインで、ターゲット接続に接続グループが存在する場合は、接続グループを展開します。
3. 接続を右クリックして、[ 接続の編集 ] をクリックします。
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. また、問題のコンテキストで ターミナル ( View > Terminal ) の内容をコピーし、この内容を Databricks サポートに送信します。

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

• Logs: Max Array Length または databricks.logs.maxArrayLength
• ログ: 最大フィールド長 または databricks.logs.maxFieldLength
• ログ:切り捨ての深さまたは databricks.logs.truncationDepth

追加のリソース

• SQLTools のドキュメント
• Databricks Driver for SQLTools をGitHubで