型生成

AppKit は SQL query の TypeScript 型を自動生成し、データベースから UI まで一貫した型安全性を実現します。

目的

query キー、パラメータ、結果行の型安全な TypeScript 宣言を生成します。

生成されるファイルはすべて shared/appkit-types/ に配置され、関心事ごとに 1 ファイルに分かれています。analytics.d.ts (SQL query の型) 、serving.d.ts (モデルサービング endpoint の型) 、metric-views.d.ts (メトリック view の型) の 3 つです。1 つのコマンド (および Vite plugin) で、これらをまとめて一度に生成します。メトリック view の型を参照してください。これらのファイルは declare module で既存のインターフェースを拡張するため、型はグローバルに適用され、import は一切不要です。tsconfig の "include": ["shared/appkit-types"] により、TypeScript が自動的に検出します。

Vite plugin: appKitTypesPlugin

推奨されるのは Vite plugin を使う方法です。SQL ファイルを監視し、開発中に型を自動的に再生成します。

設定

• outFile?: string - 出力ファイルのパス (デフォルト: shared/appkit-types/analytics.d.ts)
• watchFolders?: string[] - SQL ファイルを監視するフォルダ (デフォルト: ["../config/queries"])

例

// client/vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { appKitTypesPlugin } from "@databricks/appkit";

export default defineConfig({
  plugins: [
    react(),
    appKitTypesPlugin({
      watchFolders: ["../config/queries"],
    }),
  ],
});

重要な注意点

開発モードで AppKit 経由でフロントエンドを配信する場合、AppKit の開発サーバーには appKitTypesPlugin() がすでに内部的に組み込まれています。ただし、vite build を個別に実行する場合は、クライアント側のビルド pipeline にも追加しておく必要があります。

CLI: npx @databricks/appkit generate-types

手動での型生成や CI/CD pipeline では、次の CLI コマンドを使用します。

# DATABRICKS_WAREHOUSE_ID が必要（または第3引数として指定）
npx @databricks/appkit generate-types [rootDir] [outFile] [warehouseId]

例

• 環境変数の warehouse ID を使って型を生成する

  npx @databricks/appkit generate-types . shared/appkit-types/analytics.d.ts

• warehouse ID を明示的に指定して型を生成する

  npx @databricks/appkit generate-types . shared/appkit-types/analytics.d.ts abc123...

• 強制的に再生成する (キャッシュをスキップ)

  npx @databricks/appkit generate-types --no-cache

warehouse の準備状態と --wait フラグ

デフォルトでは、generate-types はノンブロッキングです。SQL warehouse を待つことはなく、warehouse が原因で失敗することもありません。その時点で可能な限り最良の型をすぐに書き出し (query に変更がなければキャッシュされた型を再利用し、それ以外は result: unknown) 、その後デタッチされたバックグラウンドワーカーを起動して、warehouse の準備が整った時点で実際の型を refresh します。これにより、npm install (postinstall) や npm run dev (predev) は高速なまま、コールド状態や一時的に到達できない warehouse でも問題なく動作します。開発用の Vite plugin も同じ挙動で、型はすぐに生成され、warehouse が稼働した時点でその場で refresh されます。

ビルドを進める前に正確な型が揃っている必要がある CI や本番ビルドでは、--wait を指定してください:

npx @databricks/appkit generate-types --wait

CIの耐障害性: フォールバックとしてのコミット済み型

ブロッキングモード (--wait) では、ジェネレーターはwarehouseから実際の型の取得を試みますが、warehouseに到達できない場合はコミット済みの型ファイル (shared/appkit-types/analytics.d.ts、およびMetric Viewsが設定されている場合は shared/appkit-types/metric-views.d.ts) へフォールバックします。これらの生成ファイルはリポジトリに含めておいてください。CIでの新規チェックアウト時でも、すべてのビルドはまずwarehouseに対してDESCRIBEを試み、それが完了できなかった場合にのみコミット済みの型が使われます。

ジェネレーターが劣化した型 (result: unknown) でコミット済みの型を上書きすることは決してありません — 実際の型を書き込むか、何も書き込まないかのどちらかです。

ビルドがクラッシュするか、コミット済みの型にフォールバックするかは、失敗を2つに分類した体系によって決まります。

• 確定的な失敗 (常にクラッシュ) : queriesのSQL構文エラー (到達可能なwarehouseに対する正真正銘のDESCRIBE失敗) 、HTTP 404 (誤ったwarehouse IDまたは不明なID) 、HTTP 400 (不正な形式のリクエスト) 。これらは開発者または設定に起因するエラーであり、コミット済みの型で覆い隠してはなりません。
• 環境的な失敗 (コミット済みの型の有無で判定) : 認証の失敗 (401/403) 、ネットワーク到達不能、warehouseの利用不可 (コールド、削除中、削除済み) 、RUNNING 待機のタイムアウト、その他の認識できない失敗。アプリが必要とする型ファイルがすべて揃っていれば、ビルドはそれらをそのまま使い、stderrに目立つ警告を出力したうえで成功します (終了コード0) 。必要なファイルが欠けている場合、ビルドはクラッシュし、 (到達可能なwarehouseに対して) ローカルで npx @databricks/appkit generate-types --wait を実行し、生成された型ファイルをコミットするよう促すメッセージを表示します。

この目立つ警告は、大まかな原因 (認証がブロックされた / warehouseに到達できない / warehouseが利用不可) とwarehouse IDを示す、grepしやすい1行のstderr出力です。これにより、ビルドがコミット済みの型にフォールバックしたことをCIのlogsから把握できます。

Metric Viewsを使うアプリでは、環境的な失敗時にフォールバックを成功させるために、事前に metric-views.d.ts が存在している必要があります。analytics.d.ts だけでは条件を満たせません。

アプリのテンプレートには、この仕組みがあらかじめ組み込まれています。postinstall と predev は非ブロッキングのデフォルトを実行し、prebuild は --wait を実行します。

メトリック view の型

generate-types (および Vite plugin) は、メトリックビューの型を追加的に出力します。専用のコマンドはありません。config/metric-views/definitions.json ファイルがある場合、query の型を生成するのと同じ run のなかで、宣言された各 UC Metric View に対して DESCRIBE を実行し、次の 2 つの成果物を書き出します。

• shared/appkit-types/metric-views.d.ts — MetricRegistry インターフェースを拡張し、useMetricView('<key>', …) で自動補完と型チェックが効くようにします。各ビューのメジャー、ディメンション、およびそれらのセマンティックメタデータ (SQL 型、表示名、フォーマット、時間粒度) が型レベルでエンコードされます。選択された行のキーには、実際の JSON_ARRAY のワイヤ値型 (string | null) が使われます。SQL 型はメタデータ側に残るため、意図的なパースやフォーマットに利用できます。
• config/metric-views/metadata.generated.json — 同じ処理の runtime 側にあたる成果物で、列ごとのメタデータを、手書きの definitions.json と並ぶ値として保持します。metric ルートがこれを自動的に検出し、要求された列のメタデータをレスポンスペイロードに付加するため、plugin 側の配線は不要です。生成された型と合わせてコミットしてください。生成物なので手で編集しないでください。

config/metric-views/definitions.json がない場合、メトリック側の処理は休止したままです (何も出力されません) 。存在する場合は、query の型と同じ warehouse 準備状態の契約に従います。既定のノンブロッキングな run では、まだ DESCRIBE できないビュー — warehouse がコールドな場合や、ソースが不正・到達不能な場合 — は寛容な型と警告付きで書き出されます。一方 --wait を指定した場合、メトリックビューは2 分類のタクソノミーに従います (環境起因の失敗はコミット済みの metric-views.d.ts にフォールバックして警告し、定義の不正のような決定的な失敗はビルドを失敗させます) 。不正な definitions.json (無効な JSON、または 3 パート構成の UC FQN になっていないソース) は、どのモードでも即座に失敗します。

definitions.json はメトリックキーをキーとし、各エントリではビューの 3 パート構成の UC FQN と、任意で実行主体 (既定は app_service_principal、もしくは user) を指定します。

{
  "$schema": "https://databricks.github.io/appkit/schemas/metric-source.schema.json",
  "metricViews": {
    "revenue": { "source": "catalog.schema.revenue_metrics" },
    "customers": {
      "source": "catalog.schema.customer_metrics",
      "executor": "user"
    }
  }
}

省略可能な $schema 行を追加すると、エディターでの自動補完と、公開スキーマに基づく検証が利用できるようになります。

仕組み

型ジェネレーターは次の処理を行います。

1. config/queries/ フォルダー内の .sql ファイルをスキャンする
2. SQL のパラメータアノテーション (例: -- @param startDate DATE) を解析する
3. Databricks SQL Warehouse に接続し、結果列の型を推論する
4. query のパラメータと結果に対応する TypeScript インターフェースを生成する
5. 型安全な query 実行のための QueryRegistry 型を作成する

DESCRIBE QUERY 実行時のパラメータ

型生成では、実際のパラメータをバインドせずに各 query を describe するため、すべての :param にプレースホルダーの既定値 (文字列なら '' など) が代入されます。そのため、値によって query の構造が変わる query は正しく動作しません。特に問題となるのが、IDENTIFIER(:catalog || '.schema.table') による動的なテーブル名の指定です。このようなパラメータにはサンプル値 (-- @param catalog STRING = main) を注釈として付与し、describe 呼び出しが実在するテーブルを解決できるようにしてください。サンプル値は型生成時にのみ使用され、runtime の query では引き続き実際のパラメータがバインドされます。詳しくは SQL パラメータ → サンプル値 を参照してください。

生成された型を使う

型を生成すると、IDE で自動補完と型チェックが利用できるようになります。

import { useAnalyticsQuery } from "@databricks/appkit-ui/react";
import { sql } from "@databricks/appkit-ui/js";

// TypeScript は "users_list" が有効な query キーであることと、
// 受け取るパラメータを把握しています
const { data } = useAnalyticsQuery("users_list", {
  status: sql.string("active"),
  limit: sql.number(50),
});

// TypeScript は結果行の型を把握しています
data?.forEach((row) => {
  console.log(row.email); // ✓ 自動補完が効きます
});

関連項目

• Plugins - Analytics プラグインの設定
• API Reference - UI コンポーネントの API ドキュメント (完全版)