ナレッジの作成（最初のひと月）

ochakai をセットアップした直後は、ナレッジベースは空の状態です。ここから初期のテーブルメタデータを取り込み、エージェントが自律的に参照できる有用なドメイン知識へと育てていく手順を解説します。

本ガイドは ochakai v0.31.1 に対応しています。詳細は公式リポジトリの Onboarding ガイドも併せてご参照ください。

0. 準備: スコープの決定と「よくある質問」の書き出し

まずはスモールスタートをおすすめします。最初から社内すべてのデータを網羅しようとせず、最も利用頻度の高いデータセット 1〜2 個、テーブル 5〜10 個程度に絞って始めるのが理想的です。未整理のドラフトが大量に並ぶよりも、重要なテーブルに絞って手厚くドメイン知識を補記する方が、エージェントの回答精度は劇的に向上します。

範囲を決めたら、ビジネス現場やチーム内で実際に頻出する質問（ビジネスの問い）を 10〜20 個ほど書き出してみます。

「先月の確定売上はいくらだったか」
「リピート購入率は前月と比べてどう変化したか」
「獲得チャネル別の粗利内訳を知りたい」
…

この質問リストは、後ほど §2 で優先して記述すべきナレッジ（Golden Query や Insight）を決定する際と、§3 でエージェントの検索精度を検証する際の評価セットとして活用します。社内 Slack 等の過去ログや、BI ツール・データウェアハウスの実行履歴を参考にすると効果的です。

1. テーブル一覧の取り込み

データウェアハウスからスキーマ定義を取得し、ochakai seed と ochakai import を通してナレッジベースに投入します。ochakai 自体がデータウェアハウスの認証情報を持って直接接続することはありません。

bq query --max_rows=100000 --format=json --nouse_legacy_sql \
  'SELECT table_schema, table_name, column_name, data_type, is_nullable
     FROM `your-project.your_dataset.INFORMATION_SCHEMA.COLUMNS`
    ORDER BY ordinal_position' \
  | ochakai seed --project your-project - | ochakai import -

注意: bq query コマンドは既定で先頭 100 行のみを出力するため、必ず --max_rows=100000 オプションを指定してすべてのカラム情報が出力されるようにしてください。

シェルを使わずに取り込むこともできます。Web UI のホームにある「BigQuery から取り込む」に project.dataset を入れると、本人の権限でスキーマを読み、同じ下書きを作ります。すでに誰かが書いたテーブルには触れません。使えるのは ochakai ui か、運用者が OCHAKAI_OAUTH_CLIENT_ID を設定したチームの Web UI です。エージェントを有効にしていなくても使えます。

取り込まれたテーブル定義は、すべて draft（下書き） として登録されます。まずはこれらを土台として、次節で解釈のためのドメイン知識を追加していきます。

BigQuery 以外のデータウェアハウス（Snowflake, Redshift, PostgreSQL 等）からの取り込み

ochakai seed は INFORMATION_SCHEMA.COLUMNS 互換の JSON を受け取ります。カラム定義（スキーマ名、テーブル名、列名、型など）を渡すことで、各種 DWH から同様に取り込み可能です。

例えば Snowflake の場合は以下のようにクエリします（Snowflake では列の説明は comment 列です）:

SELECT table_schema, table_name, column_name, data_type, is_nullable,
       comment AS description
  FROM your_db.INFORMATION_SCHEMA.COLUMNS
 WHERE table_schema NOT IN ('INFORMATION_SCHEMA')
 ORDER BY table_schema, table_name, ordinal_position

PostgreSQL や Redshift の場合は、psql から JSON 出力してパイプで渡すことができます:

psql -At -d your_db -c "
  SELECT json_agg(t) FROM (
    SELECT table_schema, table_name, column_name, data_type, is_nullable
      FROM information_schema.columns
     WHERE table_schema NOT IN ('pg_catalog','information_schema')
     ORDER BY table_schema, table_name, ordinal_position
  ) t" \
  | ochakai seed - | ochakai import -

※BigQuery 以外のデータソースを取り込む場合は、--project 引数を省略し、--prefix のみを使用してください。

2. 型の順にナレッジを記述していく

ナレッジは以下の優先順位で記述していくとスムーズです。

#	ナレッジタイプ	役割と記述内容	初期作成の目安
1	`BigQuery Table` / `Dataset`	テーブルの概要と利用時の注意点（Caveats）	取り込み済みの主要テーブルに注意事項を追記
2	`Glossary Term`	ビジネス用語の定義（例: 「有効会員」「解約」の定義）	解釈のブレが生じやすい用語を 3〜5 件
3	`Policy`	全社的な計算ルールや会計方針（収益認識ルール、会計年度等）	主要なルールを 2〜3 件
4	`Metric`	メトリクスの計算式（dbt やセマンティックレイヤーがあれば連携）	主要な KPI
5	`Attested Computation`	検証済みの代表クエリ（Golden Query）と質問例のペア	§0 で洗い出した頻出質問に対応する 10〜20 本
6	`Insight`	数値の解釈基準（通常レンジ、季節変動要因、集計タイミング）	主要指標について 3〜5 件
7	`Skill`	高度な集計手順やデータ抽出スクリプトの実行方法	必要に応じて後から追加

この順番で記述していくのは、後ろの型が前の型を参照するためです（例: Golden Query は sources でテーブルを参照し、Insight は Metric を参照します）。

即効性が高いのは 5（Golden Query）と 6（Insight）です。Text-to-SQL の一般的な実験では、テーブル定義のみを渡した場合の正答率は低くとどまります。一方、検証済みの代表クエリを検索コンテキストに加えると、正答率は 70〜80% 台まで向上します。また Insight は、「8 月は季節要因で減少する」といったクエリだけでは分からない文脈を伝える強力な型です。

ドキュメントの形式（OKF: Open Knowledge Format）

ochakai のナレッジは、Frontmatter（YAML）付きの標準的な Markdown ファイルです。Git でもそのまま管理できるシンプルな構造になっています。以下は Golden Query（Attested Computation）の実例です。

---
type: Attested Computation
title: 月次の確定計上売上
description: 完了注文ベースの月次売上集計クエリ
status: draft
runtime: bigquery
question: 今年度の月次売上推移を教えて
tags: [sales, revenue]
---

# Computation

```sql
SELECT
  DATE_TRUNC(o.created_at, MONTH) AS month,
  SUM(o.total_price)              AS revenue
FROM `myproject.shop.orders` AS o
WHERE o.status = 'completed'
  AND o.created_at >= DATE_TRUNC(CURRENT_DATE(), YEAR)
GROUP BY month
ORDER BY month
```

# Caveats

- **完了注文のみ対象:** キャンセルや未決済を除くため `status = 'completed'` を指定。
- **税込み金額:** 返金処理（refund）は別テーブルで管理されているため、返品率の高い月は確定値と若干乖離する点に留意。
- **タイムゾーン:** UTC 基準で集計。日本時間（JST）締めと最大 9 時間のズレが生じる。

SQL そのものだけでなく、# Caveats（注意点）に書かれた前提条件こそが、エージェントが正確な分析結果を導くための鍵となります。

次に、数値の解釈を助ける Insight の例です。

---
type: Insight
title: 月次売上推移の解釈基準
description: 通常の変動幅、お盆の影響、集計バッチのタイミングについて
status: draft
tags: [sales, revenue, interpretation]
sources:
  - id: fy2026-close
    resource: https://wiki.example/finance/monthly-close
    title: 月次決算スケジュール (FY2026)
generated: { by: analysis_agent/2.1, at: 2026-08-20T02:10:00Z }
stale_after: 2027-04-01T00:00:00Z
---

数値そのものは[月次の確定計上売上](/queries/monthly-revenue.md)で算出されます。
売上数値を評価する際は、以下の背景事情を確認してください。

## 通常の変動レンジ（前年同月比 ±6%）

過去 3 年間の実績から、前年同月比 ±6% 以内は平常の事業活動の範囲内です。

## 8 月の季節的要因

夏季休暇（お盆期間）に伴い法人取引の発注が一時停止するため、8 月は前月比で 12〜18% 減少します。前月比較ではなく前年同月比で評価してください。

## 早朝集計の注意点

前日分の確定データ連携は毎朝 06:00 JST に完了します。それ以前に取得した数値は未確定分が含まれるため、日中以降の集計を確認してください。

runtime と question は Attested Computation の項目で、Insight は持ちません。一方、Insight は sources で参照先テーブルを指定できます。stale_after に見直し期日を指定しておくと、後から期限切れナレッジを抽出できます。

必須項目は type のみです。フォーマットは Open Knowledge Format v0.2 に準拠しています。未知のカスタムキーを追加しても保持されるため、チーム固有の属性を自由に付与できます。

ナレッジのドラフト作成はエージェントに任せることもできます。Claude Code などのエージェントに以下のように指示することで、たたき台を効率的に作成できます。

「このテーブルについて、クエリを書く際に気をつけるべき前提条件やフィルタ、タイムゾーンの注意点を # Caveats にまとめて ochakai に下書き保存して。」

3. エージェントの検索精度をテストする

ナレッジを記述したら、エージェントが実際の自然言語の質問から該当ドキュメントを的確に見つけ出せるかを検証します。§0 で書き出した質問リストを使って実際に検索してみます。

while read -r q; do
  printf '\n=== %s\n' "$q"
  ochakai search "$q" --limit 3
done < questions.txt

検索結果は以下の 3 つのパターンに分かれます。

意図したナレッジが上位に返る: 設定成功です。エージェントもこのナレッジを活用して正確な回答を行えます。
何も返らない、または近いだけの別物が返る: セマンティック検索を有効にしたデプロイでは、最も近いものが必ず返るため「何も返らない」はほぼ起きません。書き足す前に、ナレッジが無いのか、別の名前で存在するのかを分けます。データウェアハウスの語（revenue）で引き直して返るなら、チームの語（売上）をそのドキュメントの synonyms に足せば済みます。同じ中身のドキュメントを 2 つ書くと、検証の手間が倍になります。検証済みのドキュメントに足した場合は、編集で検証が失効するので、もう一度 verify します。引き直しても返らないときだけ、ナレッジを書き足します。どちらの問いも、ochakai stats に語が一致しなかった検索として頻度順に並びます。
別の無関係なナレッジが返る: 用語のブレや表記揺れが原因であることが多いです。タイトルだけでなくドキュメント本文内に、実際の質問で使われるキーワードや別名を追記することで改善できます。

直したら質問リストを全部実行し直し、前回の結果と比べます。書き足したナレッジが、別の質問の正解を上位 3 件から押し出す場合もあります。

while read -r q; do
  printf '=== %s\n' "$q"
  ochakai search "$q" --limit 3 --json | jq -r '.hits[].id'
done < questions.txt > run-new.txt
[ -e run-prev.txt ] && diff run-prev.txt run-new.txt
mv run-new.txt run-prev.txt

直した質問が通り、前に通っていた質問が落ちていないことを確かめてから検証します。落ちていたら、足したナレッジの語や長さを見直します。

4. 運用サイクルへの移行

初期ナレッジの登録と検証が完了したら、エージェントとの日常運用を開始します（「エージェント接続ガイド」）。

ochakai list usage --status draft    # 過去 90 日間で実際に参照された順にドラフトを表示

エージェントが実務で活用し始めると、参照頻度の高いナレッジが順次特定されていきます。実用されているナレッジから優先して人間がレビューし、verified へと昇格させていくことで、最小限の手間で実用的な知識ベースが完成します。詳しい運用手順は「ナレッジ運用サイクルガイド」をご覧ください。

まとめ

最初のひと月で主要なテーブルの取り込みと 20〜30 件の検証済みナレッジ（Golden Query や Insight）が蓄積されれば、データエージェントの精度は実用レベルに達します。あとは日々の分析業務の中でエージェントが発見した新しい知見を適宜レビューし、知識ベースを継続的にアップデートしていきましょう。