Databricks Driver for SQLTools for Visual Studio Code

プレビュー

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

SQLTools 用 Databrick s ドライバーを使用すると 、 Visual Studio Cod e の SQLTool s 拡張機能を使用して、SQL オブジェクトを参照し、リモート Databricks ワークスペースで SQL クエリーを実行できます。

始める前に

SQLTools 用データブリック ドライバーを使用するには、Databricks ワークスペースとローカル開発コンピューターが次の要件を満たしている必要があります。

ワークスペースの要件

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

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

  注

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

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

  • データベース・オブジェクトを探索します。

  • カタログを作成します。

  • スキーマを作成します。

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

  • データベース・オブジェクトを探索します。

  • スキーマを作成します。

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

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

• Visual Studio Code バージョン 1.70 以降。 インストールされているバージョンを表示するには、Linux または macOS のマニュアル メニューから [コード] > [ Visual Studio コード について] をクリックし、Windows の場合は [ バージョン情報] > をクリックします。 Visual Studio Code をダウンロード、インストール、および構成するには、「 Visual Studio Code のセットアップ」を参照してください。

• Visual Studio Code の SQLTools 拡張機能。

• Databricks Driver for SQLTools 拡張機能 for Visual Studio Code

SQLTools 拡張機能をインストールするには、[ SQLTools ] に移動し、[ インストール] をクリックするか、または次の操作を行います。

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

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

3. マテウス・テイシェイラ の SQLTools エントリをクリックします。

   注

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

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

Databricks ドライバー for SQLTools 拡張機能をインストールするには、[Databricks ドライバー for SQLTools ] に移動し、[インストール] をクリックするか、または次の操作を行います。

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

2. [ Marketplace内の拡張機能の検索] ボックスに、「 Databricks Driver for SQLTools」と入力します。

3. [SQLDatabricks ドライバーの [SQLTools 用] エントリをクリックします。

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

認証

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

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

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

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

• Databricks OAuth user-to-machine (U2M) 認証

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

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

1. Databricks ワークスペースで、上部のバーにある Databricks ユーザー名をクリックし、ドロップダウンから[設定]を選択します。

2. [ 開発者] をクリックします。

3. [アクセストークン] の横にある [管理] をクリックします。

4. [ 新しいトークンの生成] をクリックします。

5. （任意）今後このトークンを識別するのに役立つコメントを入力し、トークンのデフォルトの有効期間である90日を変更します。有効期間のないトークンを作成するには（非推奨）、[有効期間 (日) ] ボックスを空白のままにしてください。

6. [生成] をクリックします。

7. 表示されたトークンを安全な場所にコピーし、[完了] をクリックします。

注

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

ワークスペースでトークンを作成または使用できない場合は、ワークスペース管理者がトークンを無効にしたか、トークンを作成または使用する権限を与えていないことが原因である可能性があります。ワークスペース管理者に問い合わせるか、以下をご覧ください。

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

• 個人用アクセストークンのアクセス許可

Databricks OAuth マシン間 (M2M) 認証

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

注

Databricks OAuth M2M 認証は、SQLTools バージョン 0.4.2 以降の Databricks ドライバーで使用できます。

1. OAuth M2M 認証の構成ステップを完了します。 「OAuth マシン間 (M2M) 認証」を参照してください。

2. OAuth M2M 認証構成設定を使用して Databricks 構成プロファイルを作成します。 OAuth マシン間 (M2M) 認証の「構成」セクションを参照してください。

3. Visual Studio Code 用の Databricks 拡張機能をローカル開発マシンにインストールして開きます 。

4. Visual Studio Code の Databricks 拡張機能で、 [構成] ウィンドウの [構成] ボタンをクリックします。「 構成 」ボタンが表示されない場合は、代わりに歯車 (ワークスペースの構成) アイコンをクリックします。

5. [コマンド パレット]の[Databricks Host]に、Databricks ワークスペース インスタンスの URL (例: https://1234567890123456.7.gcp.databricks.comを入力し、 Enterを押します。

6. ステップ 2 で作成したものと一致する構成プロファイル エントリを選択します。

7. Web ブラウザーで画面上の指示を完了して、Databricks アカウントの認証を完了します。

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

次のように、Databricks OAuth user-to-machine (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://1234567890123456.7.gcp.databricks.com)。次に、 Enter キーを押します。

4. [OAuth (ユーザーからマシンへ)] を選択します。

5. Web ブラウザーで画面の指示を完了して、Databricks アカウントでの認証を完了します。 プロンプトが表示されたら、 all-apis アクセスを許可します。

スキーマに接続する

1. Visual Studio Code のサイドバーで、[ SQLTools ] アイコンをクリックします。

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

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

   6. を使用して接続するためにホスト名とトークンを選択した場合は、Databricks の個人アクセス人権値をTokenに入力します。

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

      注

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

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

   9. (オプション)[ レコードの既定の制限を表示] で、既定の 50 のままにして、クエリーごとに最初の 50 行までのみを表示するか、別の制限を入力します。

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

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

接続の設定を変更する

この手順では、少なくとも 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.enabledtrue設定をチェックするか、 を に設定してログ記録をオンにします。ログ記録をオンにした後は、必ず 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に設定されている場合、出力ビュー ([表示] > [出力]、[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 のドキュメント

• Databricks Driver for SQLTools on GitHub