全質問データ取得

メソッド

REST メソッドを採用しています。参照系のみで、更新系のエンドポイントはありません。

HTTP メソッド

GET: 集計済みビューからの読み取り

命名規則

クエリパラメータとノードの命名を統一し、可読性を向上させるため、リクエスト時の URI と JSON 内のノードには snake_case を使用します。

エンドポイントは /api/catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}/... という階層で、Unity Catalog の構造をそのまま URI に写しています。

リクエストとレスポンス

ヘッダー

リクエストヘッダー

Content-Type: application/json

アプリケーション独自の認証ヘッダーはありません（「認証要件」を参照）。

レスポンスヘッダー

Content-Type: application/json

全質問データ取得

指定したテーブルの全設問を、設問ごとに行をまとめた形で返します。フロントエンドのグリッド表示・ヒートマップ表示はこのエンドポイントを使います。

URI

/api/catalogs/{catalog_name}/schemas/{schema_name}/tables/{table_name}/all_questions

パスパラメータ・クエリパラメータ

GET のためリクエストボディはありません。

種別	名前	説明
パス	catalog_name	Unity Catalog のカタログ名。フロントエンドは `cs` 固定。
パス	schema_name	スキーマ名。フロントエンドは `cs_dm` 固定。
パス	table_name	テーブル名。UI で選択する。
クエリ	question_type	`Text Select` / `Free Text` で絞り込む。省略時は絞り込まない。

バリデーションルール

フィールド	ルール
catalog_name	必須。`^[A-Za-z0-9_]+$`。違反すると 400。
schema_name	必須。`^[A-Za-z0-9_]+$`。違反すると 400。
table_name	必須。`^[A-Za-z0-9_]+$`。違反すると 400。
question_type	任意。値は `?` プレースホルダで SQL に渡されるため書式制約なし。

なお、集計値のクエリは常に is_comp = 'すべての有効回答' で絞り込まれます。この条件はパラメータ化されていません。

レスポンス（200 OK）

レスポンスは JSON です。schema フィールドは Pydantic 上 schema_name ですが、alias="schema" により JSON では schema になります。

{
  "catalog": "cs",
  "schema": "cs_dm",
  "table": "dm_vis_jreslso_tokyo23_comp_test",
  "questions": [
    {
      "question": "現在の勤務形態について教えてください",
      "question_number": "03",
      "question_type": "Text Select",
      "data": [
        {
          "question_number": "03",
          "question_type": "Text Select",
          "question": "現在の勤務形態について教えてください",
          "choice_text": "出社のみ",
          "sum_answer": 412,
          "total": 1000,
          "rate": 0.412,
          "n": 1000,
          "is_comp": "すべての有効回答"
        }
      ]
    }
  ]
}

data の各行は extra="allow" のため、テーブル固有の追加列がそのまま含まれることがあります。

その他のエンドポイント

URI	概要	主なパラメータ
`GET /api/health`	ヘルスチェック。`{"status": "healthy"}` を返す	-
`GET /api/catalogs/{catalog_name}/schemas`	カタログ配下のスキーマ一覧（Workspace API 経由）	-
`GET /api/catalogs/{catalog_name}/schemas/{schema_name}/tables`	スキーマ配下のテーブル一覧（Workspace API 経由）	-
`GET /api/catalogs/{c}/schemas/{s}/tables/{t}/questions`	テーブル内の設問一覧（`SELECT DISTINCT`）	`question_type`
`GET /api/catalogs/{c}/schemas/{s}/tables/{t}/questions/{question}`	単一設問の行を返す	-
`GET /api/data_sql`	開発用サンプル。`cs.cs_dm.dm_vis_jreslso_tokyo23_comp_test` の `question_number='03'` を固定で返す	-
`GET /api/dm_vis_jreslso_tokyo23_comp_test`	開発用サンプル。同ビューをフィルタ付きで返す	`question_number`（既定 `03`）、`is_comp`（既定 `すべての有効回答`）

すべてのエンドポイントの詳細は Swagger UI（http://localhost:8000/api/docs）で確認できます。

認証要件

アプリケーション独自の認証機構はありません。エンドユーザーのアクセス制御は Databricks Apps 側に委譲しています。

アプリから Databricks への接続は OAuth service principal（M2M）で行い、DATABRICKS_CLIENT_ID / DATABRICKS_CLIENT_SECRET を使います。参照できるデータの範囲はこのサービスプリンシパルに付与された Unity Catalog の権限で決まります。

例外処理

例外時のステータスコードは次のとおりです。routes/ の各ハンドラで例外種別からマップしています。

説明	ステータスコード	ステータス名
識別子が allowlist に違反（`ValueError`）	400	Bad Request
FastAPI のリクエストバリデーション失敗	422	Unprocessable Entity
サーバ内部エラー	500	Internal Server Error
設定不足・依存ライブラリ未インストール（`RuntimeError`）	503	Service Unavailable

処理フロー

シーケンス図

sequenceDiagram
    participant Client
    participant API as FastAPI (routes)
    participant SQL as backend/sql
    participant Warehouse as SQL Warehouse

    Client->>API: GET .../all_questions?question_type=Text Select
    API->>SQL: asyncio.to_thread(fetch_all_questions)
    SQL->>SQL: fully_qualified_name で識別子を検証
    SQL->>Warehouse: SELECT ... WHERE is_comp = 'すべての有効回答' AND question_type = ?
    Warehouse-->>SQL: 行
    SQL->>SQL: question ごとにグルーピング
    SQL-->>API: List[Dict]
    API-->>Client: 200 OK（AllQuestionsResponse）