BI as Codeで仕様書メンテを半自動化した話

2025年12月16日 09:06

こんにちは、コミューン株式会社データチームの田辺(@Be13ebe)です。この取り組みは同チーム商(@Smuch)さんと一緒に進めました。
この記事はCommune Developers Advent Calendar 2025の16日目の記事です。

この記事では、BIツールThoughtspotで作成したダッシュボードの設定ファイルをもとに、仕様書を半自動生成・更新するようにした取り組みを紹介します。
中長期的に運用していく機能における仕様書効率化の一例としてご覧いただけますと幸いです。

背景: AI時代のボトルネックは開発から周辺業務へ

近年、日常業務でもAIにコードを書いてもらう場面が増えた方もいるのではないでしょうか。
私のようなデータ職種でもAIの恩恵によりSQLやダッシュボード実装の時間を短縮できるようになりつつあり、機能開発のスピードはますます加速しているように思います。

いっぽうで、開発の周辺業務(例えば泥臭いメンテナンスや資料作成、コミュニケーション)は同様に短縮できているでしょうか？
これらのコストは、以前と変わらないか、むしろ機能が増えた分だけ増加しているのではないでしょうか。

今まで開発コストがボトルネックだった時代から、開発の周辺業務がボトルネックになる時代に移りつつあると考えています。

機能を開発してリリースするまでと、リリースしてから問い合わせ・メンテナンスを安定して継続させる資料整備がセットで高速化できれば、品質を担保しながら素早く機能を提供できるようになるはず！という思いがあります。

そこで今回は、BI as Codeで管理されたダッシュボードの設定情報を社内向けの仕様書作成に利用することで、ドキュメント作成・メンテナンスのコストを下げることを試みました。

BI as Codeとは？

LightdashやEvidenceなど、BIツールの設定情報などをコードとして管理する「BI as Code」という考え方が注目されるようになってきました。
BI as Codeではダッシュボードを構成する要素(グラフやフィルタの表示や配置, データソースのスキーマやグラフでの集計ロジック)をMarkdown・JSON・YAMLなどのコードで管理できます。弊社が利用しているThoughtspotも、ダッシュボードやモデル情報をYAMLで管理できます。

このあたりの解説や応用例は以下のような詳しい記事があるので割愛します。

取り組み：分析画面の仕様書半自動化

コミューンでは今年Commune管理画面内の分析画面をリニューアルしました。

リニューアルにより既存機能からさらにグラフ・タブの数が増え、伴って仕様書のボリュームも増えました。

- タブ数：約10個
- グラフ数：数十個
- フィルター数：十数個
- 指標定義：100前後

加えて分析画面はスクラップビルドではなく中長期で顧客へ提供するため、将来の変更に追従して仕様書もメンテナンスし続ける必要があります。
初期リリースの時点から仕様書が膨大なうえ、かつ継続的にメンテナンスしていくとなると、以下のような課題が起きます。

仕様が変わるたびに仕様書を更新する作業が発生する(地味に工数かかる)
更新漏れが発生し、実装と仕様書が乖離する
- → 乖離のある箇所だけでなく仕様書全体が「この仕様書、最新ですか？」と信頼されなくなり直接チームへ質問されるようになる。
- → 結果、チームの問い合わせ対応時間が増える。

分析画面の修正・追加開発を進めながら、仕様書も一緒に変化させていくには自動化が必要でした。

TMLから仕様書を自動生成する

0.ThoughtSpotのTMLとは

ThoughtSpotでは、TMLというYAMLファイルでダッシュボードやモデルの各種設定を管理しています。

ダッシュボードの場合、TMLには例えば以下の情報が含まれています。

タブ：タブ名, タブの並び順
フィルター：フィルタ名、デフォルト値、適用対象・外のグラフ
グラフ設定：グラフ名、グラフの可視化タイプ、色・フォント設定
グラフなどの表示位置：表示位置、グラフ・テキストボックスのサイズ
モデル：グラフが参照しているデータモデル, 集計ロジック

# TMLの例（イメージ）
liveboard:
  name: 分析ダッシュボード
  visualizations:#グラフ情報
  - id: Viz_1
    answer:
      name: 登録ユーザー数 #グラフタイトル
      tables: #参照テーブル情報
	      ...
      chart: #グラフ情報
        type: KPI
        chart_columns:
        - column_id: Fct Date Jst
        - column_id: 登録ユーザー数
	        ...
  - id: Viz_2
	  ...
  filters:#フィルタ情報
  - column:
    - dummy__table1::Fct Date Jst
    - dummy__table2::Created Date Jst
    ...
    display_name: 集計期間
		...

  layout:#タブ, グラフ配置
    tabs:
    - name: ホーム
      description: ""
      tiles:
      - visualization_id: Viz_1
        x: 0
        "y": 2
        height: 4
        width: 4
      - visualization_id: Viz_2
        ...

1. BigQueryにマスターテーブルを作成

ThoughtSpotではダッシュボード設定がYAMLファイルで階層的に記述されているので、必要情報を抜き出すpythonスクリプトを作れば、扱いやすいテーブルに変換することができます。
以下のダッシュボードマスタテーブルをTMLから作り、BigQueryに格納しました。

#作成したテーブル
- tab_master：ダッシュボード名、タブ名、タブID、タブの並び順
- visualization_master：グラフ名、グラフID、所属タブ、表示位置
- filter_master：フィルター名、対象カラム、デフォルト値、適用グラフ
- column_master：モデルごとのカラム名、データ型、所属データセット

作成したテーブルは定期更新するよう設定します。
TMLに加わった変更は自動でBigquery反映できるように設定しておけば、仕様書への漏れをかなり減らせる期待ができます。

2.テンプレートに流し込んで仕様書を生成

ここまで出来てしまえば、後は必要なケースに合わせてテンプレートに値を流し込むだけです。
ここではフィルターの仕様書生成を例に説明しますが、基本的には文字列の置換処理なので手段はスプレッドシートでもSQLでもpythonでも構いません。

まず、仕様書に載せたい説明文のテンプレートを用意します。

「{filter_display_name}」フィルタで指定した値が「{tab_name}」タブ「{visualization_name}」に反映されます。デフォルトでは「{defalut_value}」の設定になっています。

次にBigQueryのテーブルから必要な情報を抽出し、regexp_replaceで文字列を指定カラムの値に変換していきます。(とても愚直)

3.Bigqueryから必要データを抽出

with
keywords as (
	select
	  tab_name,
	  visualization_name,
	  filter_display_name,
	  default_value,
	from
		filter_master
	left join
		...
  where
    filter_master.liveboard_name = "target_liveboard"
),

replace_template as (
	select
	  tab_name,
	  visualization_name,
	  filter_display_name,
	  default_value,
	  -- テンプレート文を置換してカラムの値を埋め込む
		regexp_replace(regexp_replace(regexp_replace(regexp_replace(
						"「{filter_display_name}」フィルタで指定した値が「{tab_name}」タブ「{visualization_name}」に反映されます。デフォルトでは「{defalut_value}」の設定になっています。",
						r"\\{filter_display_name\\}",filter_display_name),
						r"\\{tab_name\\}",tab_name),
						r"\\{visualization_name\\}",visualization_name),
						r"\\{defalut_value\\}",default_value
		) as description,
	from
		keywords
)

select * from replace_template

あとはクエリを実行、csvダウンロード、スプレッドシートなどよしなな共有資料へ体裁を整えて反映すれば完成です。

4.抽出データを表に整えて完成

TML->python scriptで整形->テンプレートで文章化して作成したフィルター仕様書

このような形で、フィルター仕様書を一括生成できます。

5. 残っている課題

いっぽうでいくつか課題も残っています。

YAMLの仕様理解：YAMLファイルからのテーブル作成では、細かい部分で欲しいデータ形式をYAMLから取り出しづらい場面があり、データ変換で地道なトライアンドエラーが発生しました。
- PKを持っていてほしい情報にPKがなかったり、
- フィルタ設定値が非常に細かいため、複数の値を集約して見やすい1つの値にする処理を入れたり..
運用設計：顧客向け資料の場合は人間がレビューを挟むタイミングなど運用面の整備も必要になります。今回の試みは社内向け仕様書にとどまっておるため、今後運用していくさいに課題と向き合い整備する予定です。

まとめ

今回はダッシュボードの設定YAMLファイルから仕様書を作成する方法を紹介しました。
特にBI as Codeからの恩恵を感じたのは2点です。

細かい仕様一覧がまとめて生成できる！
Bigqueryで定期更新したことで、仕様書も自動更新される！(仕様書が実装とズレなくなる)

今後はYAMLからの仕様生成の範囲を広げる、顧客向けの定義書まで自動化するなどを目指していきたいと考えています。
実装速度が上がる時代だからこそ、ドキュメンテーションも自動化して追いつく必要があります。
仕様書のメンテナンスに悩んでいる方の参考になれば幸いです。

謝辞

本取り組みにおけるTMLからテーブルへの変換スクリプト実装・定期実行設定は同チームの商さんが担当しました。改めて感謝申し上げます。

We are hiring!

コミューンデータチームでは一緒に働く仲間を探しています。
お申し込みお待ちしています！

最後まで読んでいただきありがとうございました！