Databricks SQLは、Databricksのレイクハウス上のテーブルにSQLで問い合わせるためのデータウェアハウス機能です。クエリを実際に処理するのはSQLウェアハウスと呼ばれる計算資源で、その種類とサイズの決め方が速度と費用の大半を左右します。この記事では2026年11月15日時点の公式ドキュメント(AWS版)をもとに、サーバーレス・Pro・Classicの違い、サイズと自動停止の決め方、CLIでの作成、SQLエディタ・REST API・Pythonからのクエリ実行、実行履歴を使った見直しまでをコード付きで整理します。
まとめ:Databricks SQLはサーバーレスのウェアハウスを大きめに作って絞る
結論は3点です。1つ目は、使えるリージョンならサーバーレスのSQLウェアハウスを選ぶことです。起動が数秒で済み、混雑に応じたスケールも自動で行われます。2つ目は、APIやCLIで作るときに種類を必ず明示することです。APIの既定はClassicで、何も指定しないと画面で作った場合と違う種類になります。
3つ目は、サイズを勘で決めず、実行履歴の待ち時間とスピルの量で見直すことです。公式も、大きめに作ってから縮める進め方を勧めています。Databricks全体の機能とDBU課金の考え方は、親記事のDatabricksとは?できること・DBU課金の料金と業種別の費用・導入事例にまとめています。
Databricks SQLの構成要素とSQLウェアハウスが担う役割を確かめる
Databricks SQLは単独の製品というより、いくつかの部品の組み合わせです。役割を分けて押さえておくと、どこで遅くなり、どこで費用がかかるのかを切り分けやすくなります。
SQLウェアハウス・SQLエディタ・Unity Catalogの役割分担
- SQLウェアハウス:クエリを処理する計算資源。起動している時間に応じてDBUが課金される
- SQLエディタ:ブラウザでSQLを書いて実行する画面。実行先のウェアハウスを選んで使う
- Unity Catalog:テーブルの置き場所と権限の管理。
カタログ.スキーマ.テーブルの3階層で指定する - ダッシュボード・アラート・Genie:ウェアハウスの上で動く利用者向けの機能
テーブルの権限はウェアハウスではなくUnity Catalogで付与します。権限の継承の考え方はUnity Catalogとは?3レベル名前空間と権限継承・移行判断で解説しました。自然言語の質問からSQLを組み立てるGenieも裏では同じウェアハウスでクエリを流しており、設定手順はDatabricks Genieの使い方にまとめています。
ノートブック用の汎用クラスタとSQLウェアハウスの処理別の使い分け
Databricksには、PythonやScalaのノートブックを動かす汎用のコンピュートもあります。SQLウェアハウスはSQLの実行に絞った計算資源で、BIツールやアプリからの接続先として使う前提で作られています。データの取り込みや加工をPythonで書く処理は汎用のコンピュートやジョブに置き、加工済みのテーブルを読む処理をSQLウェアハウスに寄せる、という分担が基本です。ノートブックからテーブルを作る手順はDatabricksの使い方で扱っています。
サーバーレス・Pro・Classicの違いとSQLウェアハウスの種類の選び方
公式のSQL warehouse typesのページ(2026年10月30日更新)では、3種類の違いが次のように整理されています。
3種類のSQLウェアハウスの機能・計算資源の場所・起動時間の比較
| 項目 | サーバーレス | Pro | Classic |
|---|---|---|---|
| Photon | 対応 | 対応 | 対応 |
| Predictive IO | 対応 | 対応 | 非対応 |
| IWMによる自動調整 | 対応 | 非対応 | 非対応 |
| 計算資源の場所 | Databricks側 | 自社のAWS | 自社のAWS |
| 起動時間の目安 | 2〜6秒 | 約4分 | 約4分 |
IWM(Intelligent Workload Management)は、待ち行列の状況を見てクラスタを足し引きする仕組みです。ProとClassicは計算資源が自社のAWSアカウント側で起動するため、DatabricksのDBUとは別に、EC2などの費用がAWSから請求されます。費用を比べるときは、この2つの請求を合算して見る必要があります。
APIの既定がClassicの場合のサーバーレス作成時の種類指定
画面から作ると、サーバーレスが使えるワークスペースでは既定でサーバーレスになります。一方でAPIの既定はClassicです。APIでサーバーレスを作るには、enable_serverless_computeをtrue、warehouse_typeをPROにします。公式の推奨も、この項目を常に明示して指定する方法です。Terraformやスクリプトで作ったウェアハウスだけ起動が遅い、という場合はまずここを疑います。
サーバーレスの利用条件を踏まえたProとClassicの選択基準
Proは、サーバーレスが自社のリージョンで使えない場合や、ネットワークを自社で細かく構成する必要がある場合の選択肢です。Classicは公式でもエントリーレベルの性能と位置づけられ、対話的なデータ探索向けとされています。レガシーの外部Hiveメタストアを使っているワークスペースではサーバーレスを使えない点にも注意します。新しく作るなら、サーバーレスが使えない理由が無い限りサーバーレスを選ぶ、で迷うことはほぼありません。
SQLウェアハウスをCLIで作成し、サイズ・自動停止・クラスタ数を設定する
作成できるのは、ワークスペース管理者か、クラスタを無制限に作成できる権限を持つユーザーです。設定項目のうち、費用と速度に効くのはサイズ、自動停止、クラスタ数の3つです。
2X-Smallから5X-Largeまでのサイズ表と画面の既定値
サイジングのページ(2026年11月5日更新)には、ProとClassicのサイズごとの構成が載っています。サーバーレスではインスタンスの種類が異なる場合があると注記されています。
| サイズ | ドライバ | ワーカー数 |
|---|---|---|
| 2X-Small | i3.2xlarge | 1 |
| X-Small | i3.2xlarge | 2 |
| Small | i3.4xlarge | 4 |
| Medium | i3.8xlarge | 8 |
| Large | i3.8xlarge | 16 |
| X-Large | i3.16xlarge | 32 |
| 2X-Large以上 | i3.16xlarge | 64〜512 |
ワーカーはすべてi3.2xlargeで、サイズが1段上がるごとにワーカー数がおおむね倍になります。5X-Largeはパブリックプレビューの扱いです。作成手順のページ(2026年9月11日更新)によると、画面の既定サイズはX-Largeで、試しに作っただけでも32台分のワーカーが動く設定になっています。
SQLウェアハウスの自動停止の分数とクラスタ数の上限を決める目安
自動停止の既定は、ProとClassicが45分(最小10分)、サーバーレスが10分です。サーバーレスは画面で5分、APIなら1分まで縮められます。起動が数秒で済むサーバーレスは短めにしても待たされにくく、起動に約4分かかるProとClassicは短くしすぎると利用者が毎回待つことになります。
クラスタ数の既定は最小1・最大1です。公式の目安は、同時に流れるクエリ10本ごとにクラスタ1台です。BIツールから朝に一斉にアクセスが来るなら、その時間帯の同時実行数から最大値を決めます。待ち行列に入れるクエリはどの種類でも1,000本が上限です。
databricks warehouses createでサーバーレスを作る
画面で作ると設定の経緯が残らないため、CLIのwarehousesコマンドで作り、コマンドをリポジトリに残しておく方法を勧めます。CLIの導入と認証プロファイルはDatabricks CLIの使い方で解説しています。
# BI向けのサーバーレスSQLウェアハウスを作る(種類は必ず明示する)
databricks warehouses create \
--name "bi-serverless" \
--cluster-size "Small" \
--min-num-clusters 1 \
--max-num-clusters 3 \
--auto-stop-mins 10 \
--enable-serverless-compute \
--enable-photon \
--warehouse-type PRO \
-p dev
# 作成済みのウェアハウスのIDと状態を一覧する
databricks warehouses list -p dev -o json | jq -r '.[] | "\(.id)\t\(.name)\t\(.state)"'
# 使い終わったら止める(自動停止を待たない)
databricks warehouses stop 1234567890abcdef -p dev
Smallから始めているのは、下の章で実行履歴を見てサイズを決め直す前提だからです。最初から本番の負荷が分かっている場合は、公式の勧めどおり大きめのサイズで作り、余裕を確かめてから下げます。
SQLエディタとREST API・Pythonコネクタでクエリを実行する手順
同じウェアハウスに、画面・HTTP・Pythonの3つの経路からクエリを送れます。人が試す段階は画面、アプリやバッチから呼ぶ段階はAPIかコネクタ、と使い分けます。
SQLエディタのクエリ実行とLimit 1000解除後の結果上限
SQLエディタの手順(2026年10月27日更新)では、ウェアハウスを選び、Ctrl(Macは Cmd)とEnterを押すか[Run (1000)]を押して実行します。既定では[Run all statements]と[Limit 1000]が有効で、結果は1,000行で打ち切られます。ドロップダウンからLimit 1000を外しても、画面に返るのは64,000行か10MBの小さい方までです。それ以上の行を扱うなら、画面ではなく次のAPIかコネクタで取り出します。
Statement Execution APIでパラメータ付きのSQLを送る
アプリからHTTPでSQLを送るときは、Statement Execution API(2026年10月6日更新)を使います。値は文字列に埋め込まず、:名前のパラメータで渡すと、SQLインジェクションを防げます。公式のサンプルデータsamples.tpchを使った例です。
# OAuthでログイン済みのプロファイルからアクセストークンを取り出す
export DATABRICKS_HOST=dbc-xxxxxxxx-xxxx.cloud.databricks.com
export DATABRICKS_TOKEN=$(databricks auth token -p dev | jq -r .access_token)
export WAREHOUSE_ID=1234567890abcdef
# 30秒まで待ち、終わらなければ実行を続けたままstatement_idを返す
curl -s -X POST "https://${DATABRICKS_HOST}/api/2.0/sql/statements/" \
-H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"warehouse_id": "'"${WAREHOUSE_ID}"'",
"catalog": "samples",
"schema": "tpch",
"statement": "SELECT l_orderkey, l_extendedprice FROM lineitem WHERE l_shipdate > :ship_date LIMIT 10",
"parameters": [ { "name": "ship_date", "value": "1995-01-01", "type": "DATE" } ],
"wait_timeout": "30s",
"on_wait_timeout": "CONTINUE"
}' > res.json
jq '.status.state' res.json
# PENDINGやRUNNINGのときは、IDで状態と結果を取り直す
curl -s "https://${DATABRICKS_HOST}/api/2.0/sql/statements/$(jq -r .statement_id res.json)" \
-H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq '.status.state, .result.data_array'
wait_timeoutの既定は10秒で、5秒から50秒の間か、すぐに戻す0sを指定できます。結果を応答に含める既定のINLINEは25MiBが上限で、上限を超えた場合はステートメント全体が失敗する仕様です。大きな結果はdispositionをEXTERNAL_LINKSにし、ARROW_STREAMかCSVの形式でダウンロード用のURLから取ります。このURLは短時間だけ有効な署名付きURLで、取得するときにAuthorizationヘッダーを付けてはいけないとされています。
databricks-sql-connectorでPythonから結果を取り出す
Pythonのバッチやアプリからは、Databricks SQL Connector for Pythonを使います。PyPIで確かめた最新版は2026年11月4日公開の4.9.0で、対応するPythonは3.10以上です。公式の解説(2026年11月12日更新)によると、3.0.0以上はサーバー側でパラメータを扱うネイティブ方式に対応しています。接続に使うhttp_pathは、ウェアハウスの画面の接続の詳細タブで確かめられます。
# pip install "databricks-sql-connector>=4.9,<5"
import os
from databricks import sql
with sql.connect(
server_hostname=os.getenv("DATABRICKS_SERVER_HOSTNAME"),
http_path=os.getenv("DATABRICKS_HTTP_PATH"), # ウェアハウスの接続の詳細タブの値
access_token=os.getenv("DATABRICKS_TOKEN"),
) as conn:
with conn.cursor() as cursor:
cursor.execute(
"SELECT l_orderkey, l_extendedprice FROM samples.tpch.lineitem "
"WHERE l_shipdate > :ship_date LIMIT 10",
{"ship_date": "1995-01-01"},
)
for row in cursor.fetchall():
print(row.l_orderkey, row.l_extendedprice)
上の例は個人アクセストークンを環境変数で渡す最小の形です。本番のバッチでは、公式の手順どおりサービスプリンシパルのOAuth(credentials_provider)に置き換えます。トークンを人に紐づけたままにすると、担当者の異動や退職でバッチが止まるためです。
system.query.historyで待ち時間とスピルを測り、サイズを見直す
サイズとクラスタ数が合っているかは、実際に流れたクエリの記録で判断します。クエリ履歴のシステムテーブル(2026年11月4日更新)には、ウェアハウスで実行された文ごとの時間や読み込み量が残ります。記録が反映されるまでの時間は、通常1時間以内です。
ウェアハウスごとの待ち時間とスピル量を直近7日間で集計するSQL
-- 直近7日間を、ウェアハウスと1時間単位で集計する
SELECT
compute.warehouse_id,
date_trunc('HOUR', start_time) AS hour_utc,
count(*) AS queries,
round(percentile(total_duration_ms, 0.95) / 1000, 1) AS p95_sec,
round(sum(waiting_at_capacity_duration_ms) / 1000, 1) AS queued_sec,
round(sum(spilled_local_bytes) / power(1024, 3), 2) AS spilled_gib
FROM system.query.history
WHERE compute.type = 'WAREHOUSE'
AND start_time >= current_timestamp() - INTERVAL 7 DAYS
GROUP BY ALL
ORDER BY queued_sec DESC
LIMIT 50;
waiting_at_capacity_duration_msは計算資源の空きを待って並んでいた時間、spilled_local_bytesはメモリに収まらずディスクへ書き出した量です。時刻はUTCで記録されるため、日本時間の業務時間帯と照らすときは9時間ずらして読みます。SQLの本文を表すstatement_textは既定で伏せられ、全文を読めるのはアカウント管理者とdatabricks_pii_accessグループのメンバーに限られます。
クエリ履歴の待ち時間とスピル量に基づくクラスタ数・サイズの調整基準
集計の結果は、次の基準で読みます。
- queued_secが特定の時間帯にだけ大きい:同時実行が足りない。最大クラスタ数を上げる
- spilled_gibが出ていて、p95_secも長い:1本のクエリに対して小さすぎる。サイズを1段上げる
- どちらも0に近く、稼働時間が長い:大きすぎるか、自動停止が長すぎる。サイズか自動停止の分数を下げる
公式も、ウェアハウスの監視画面のPeak Queued Queriesが継続して0を超えるならサイズかクラスタ数を増やし、スピルが出るならサイズを上げるよう案内しています。ProとClassicでは、処理し切るまでの見込み時間が2〜6分ならクラスタを1台、6〜12分なら2台足すといった規則でスケールし、負荷の低い状態が15分続くと縮みます。この規則は、朝の集中時にクラスタが増えるまで何分遅れるかを見積もる際の判断材料です。
Databricks SQLの採用条件と他のDWH・汎用クラスタで足りる場面
判断の軸は、データがすでにDatabricksのテーブルにあるかと、SQLを流す主体がBIツールや業務アプリかの2つです。
Deltaテーブルを複数のBIやアプリから読むならSQLウェアハウスを採用する判断
採用すべきなのは、取り込みと加工をDatabricksで行い、その結果を複数のBIツールや社内アプリから読ませる構成です。データを別のDWHへ複製せずに済み、権限もUnity Catalogで一元管理できます。BIツール側はSQLウェアハウスを接続先にするだけでよく、利用にあたってDatabricksの内部構成の知識は不要です。OSSのBIから接続する例はRedashとは?SQLで作るOSS BIの使い方で紹介しています。Snowflakeなど他のDWHと課金の仕組みを比べたい場合はDatabricksとSnowflakeの違いを参照してください。
SQLだけで済まない処理や小規模な用途でDatabricks SQLを見送る判断
次の場合は、SQLウェアハウスを中心に据えません。
- 処理の大半がPythonでの前処理や機械学習で、SQLは補助にとどまる(汎用のコンピュートやジョブで足りる)
- データが数GB程度で、既存のRDBやクラウドのDWHで問題なく回っている(Databricksを入れる理由が薄い)
- 個人で機能を試すだけ(無料のDatabricks Free Editionで十分)
ProやClassicを使う場合の前提になるAWS側のネットワークとIAMの設定は、Databricks on AWSの構築手順にまとめています。ウェアハウスの種類とサイズの設計から、Unity Catalogの権限、BIの接続、費用の監視までまとめて任せたい場合は、一創のデータ分析基盤構築・MLOps構築支援で引き受けています。
Databricks SQLのウェアハウス選びと料金で迷う点のよくある質問
databricks sql を使い始めるときによく聞かれる質問に、2026年11月15日時点の公式ドキュメントをもとに答えます。
Databricks SQLの料金はどのように決まりますか?
SQLウェアハウスが起動している時間に応じて、DBUという単位で課金されます。単価を左右する条件は、種類(サーバーレス・Pro・Classic)、クラウド、リージョン、契約です。ProとClassicは計算資源が自社のAWSアカウントで動くため、DBUとは別にAWSの利用料もかかります。クエリが流れていない時間も自動停止までは課金されるので、自動停止の分数は費用を大きく左右する設定です。DBU課金の全体像は親記事のDatabricksとはで解説しています。
最初のサイズは何から始めればよいですか?
公式は、必要と思うより大きめのサイズから始めて、試しながら縮める方法を勧めています。小さく始めて上げるより効率がよい、というのが公式の説明です。ただし画面の既定のX-Largeのまま放置すると費用がかさむため、作成時に自動停止を短めに設定し、1〜2週間分のsystem.query.historyを見てから決め直します。
SQLウェアハウスの起動待ちを減らすにはどうしますか?
サーバーレスに切り替えるのがもっとも確実です。起動の目安はサーバーレスが2〜6秒、ProとClassicが約4分です。Proのまま使う事情がある場合は、利用の多い時間帯だけ自動停止を長めにする、朝の利用前にジョブで起動しておく、といった運用で待ち時間を隠します。
SQLエディタで1,000行を超える結果を取り出せますか?
Limit 1000を外せば、64,000行か10MBの小さい方まで画面に返ります。それを超える量を取り出す手段は、Statement Execution APIのEXTERNAL_LINKSか、Pythonのコネクタです。定期的に出力するなら、結果をテーブルやボリュームに書き出すジョブにした方が扱いやすくなります。
Genieやダッシュボードも同じSQLウェアハウスを使いますか?
はい、どちらもSQLウェアハウスの上で動く機能です。ウェアハウスを指定して動くため、利用者が増えるとウェアハウスの同時実行数と費用に効いてきます。分析担当者が使うウェアハウスと、ダッシュボードやGenieで業務部門が使うウェアハウスを分けておくと、system.query.historyで負荷と費用を部門ごとに切り分けられます。ダッシュボードの作成・共有・外部埋め込みの手順はDatabricksダッシュボードの作り方:AI/BIの作成・共有・外部埋め込みとPower BIとの使い分けで解説しています。
関連記事
- Databricksとは?できること・DBU課金の料金と業種別の費用・導入事例【2026年10月】:Databricks全体の機能とDBU単価
- Databricks Genieの使い方:Genie Agentの設定とSQL精度を上げるメタデータ整備【2026年11月】:SQLウェアハウス上で動く自然言語の問い合わせ
- Databricks CLIの使い方:インストール・OAuth認証・バンドルでのCI/CD設定【2026年11月】:warehousesコマンドとトークン取得の前提
- Databricksの使い方:ノートブック作成からDeltaテーブル・ジョブ化までの手順【2026年11月】:SQLで読むテーブルの作り方
- DatabricksとSnowflakeの違い:DBUとクレジットの課金差とIceberg相互参照の設定で決める選び方【2026年版】:他のDWHとの比較