分析用にデータを受け取ったが、列の名前だけでは何の値か分からない。金額が円なのかドルなのか、どのシステムから出したデータなのかも書いていない。項目ごとに聞き直していて、なかなか集計に入れない。
この記事では、データを受け取る人と渡す人が、項目の意味を共有するためのテーブル定義書の書き方をまとめます。
この記事でわかること
- テーブル定義書に書く4つの項目と、Excelの記入例
- 書き方の手順と、データの中身が変わったときの直し方
- 定義書があると、項目ごとの質問のやり取りと推察が減ること
結論：テーブル定義書は「項目名・データ型・意味・取得方法」の4つを書く
テーブル定義書には、項目ごとに「項目名・データ型・意味・取得方法」の4つを書きます。
この4つがあれば、データを受け取った人が、項目ごとに質問や推察をしなくても集計に入れるからです。単位は意味の中に、どのシステムから取ったかは取得方法に書きます。
テーブル定義書とは：データの項目の意味を、受け取る人と共有する一覧
テーブル定義書は、テーブルの項目ごとに、データ型や意味を書いた一覧です。
テーブルは、データベースに入っている表のことです。Excelでいえば、1枚のシートに並んだ表にあたります。項目は、その表の列のことです。
データだけを受け取ると、項目の意味は列の名前から推察するしかありません。
自分も、お客様から受け取ったデータを分析していて、項目の意味が分からなかったことがあります。単位が円なのかドルなのか、どのシステムから取ってきたデータなのかも不明でした。
似た名前の資料に、KPI定義書があります。KPI定義書は、売上などの指標をどう計算するかを書いたものです。テーブル定義書は、その計算に使う元のデータについて、項目ごとの意味を書きます。
システム開発で作るテーブル定義書には、主キー・外部キー・インデックスなど、データベースの設計の情報も書きます。この記事では、項目の意味を共有するための書き方に絞り、設計の話には踏み込みません。
テンプレートと記入例：Excelで、1行に1つの項目を書く
テーブル定義書は、Excelで1行に1つの項目を並べ、4つの欄を埋めれば使えます。
自分は、テーブル定義書をExcelで作ることが多いです。項目ごとに、データ型・意味・取得方法を書けるからです。作るのは、新しいテーブルを作ってデータベースに入れるときです。
| 欄 | 書く内容 |
|---|---|
| 項目名 | データの列の名前 |
| データ型 | 数値・文字列・日付などの値の種類 |
| 意味 | 何の値か。単位(円かドルかなど)もここに書く |
| 取得方法 | どのシステムから取ったか、どう計算・抽出したか |
| 空欄の有無(任意) | 空欄が入ることがあるか |
基本は、上の表の最初の4つです。空欄が入るかどうかは、書いておいた方がよいものの、必須というほどではありません。実際にデータに入っている値の例は、基本的に書かなくて構いません。
データ型は、合計できる列かどうかの手がかりになります。金額が文字列として入っていると、そのままでは正しく合計できないことがあります。
以下は説明のための架空の例です。受注データ(テーブル名: orders)の定義書を、表の幅の都合で2つに分けて載せます。Excelでは、1枚のシートに横に並べます。
| 項目名 | データ型 | 意味 |
|---|---|---|
| order_id | 文字列 | 受注番号。1件の受注に1つ |
| order_date | 日付 | 受注した日 |
| customer_id | 文字列 | 顧客番号 |
| amount | 数値 | 受注金額(税抜・円) |
| 項目名 | 取得方法 |
|---|---|
| order_id | 販売管理システムの受注データから抽出 |
| order_date | 販売管理システムの受注データから抽出 |
| customer_id | 販売管理システムの受注データから抽出 |
| amount | 受注明細の金額(税抜)を、受注ごとに合計 |
この例では、amountの意味に「税抜・円」まで書いてあるので、受け取った人は単位を聞かずに集計できます。
テーブルが複数あるときは、1つのテーブルを1枚のシートに書き、シートの名前をテーブル名にすると探しやすくなります。
書き方の手順：項目名を書き出し、3つの欄を埋め、単位と元のシステムを見直す
テーブル定義書は、まず項目名を書き出して残りの3つの欄を埋めます。最後に、単位と元のシステムを見直します。
1. 項目名を、列の並びどおりに書き出す
データの1行目にある列の名前を、左から順に、Excelの項目名の欄へ上から並べます。列の並びと定義書の並びが同じだと、受け取った人が見比べやすくなります。
2. データ型・意味・取得方法を埋める
項目ごとに、データ型・意味・取得方法を書きます。意味には単位まで書き、「金額」ではなく「受注金額(税抜・円)」のように書きます。
システムの値をそのまま入れた項目は、取得方法にシステム名と元のデータの名前を書きます。計算した項目は、何をどう計算したかを書きます。
3. 受け取る人のつもりで、単位と元のシステムを見直す
書き終えたら、データを受け取る人のつもりで読み直します。意味の欄の単位と、取得方法の欄の元のシステムが、読んで分かるように書いてあるかを確かめます。
実際に定義書をもらっていても、質問したことはあります。聞いたのは、単位が円かドルかと、どのシステムから抽出したデータかです。
現場目線の注意点：定義書がないデータは、聞いた答えを同じ欄に書き残す
受け取ったデータに定義書がないときは、項目ごとに、データを渡した人へ聞くことになります。聞いた答えは、メールや会話だけに残さず、テンプレートの欄に書き込みます。
そうしておくと、次に同じデータを受け取ったとき、同じ質問をせずに済みます。分析をほかの人に引き継ぐときも、そのまま渡せます。
更新：データの中身が変わったら、変わった箇所だけ定義書を直す
データの中身と定義書が食い違うと、受け取った人は定義書を信じて、違う意味のまま集計します。
自分は、データの中身が変わったときは、そのたびに定義書を更新しています。直すのは、変わった箇所だけです。
中身が変わるのは、たとえば列が増えたときです。計算のしかたや取ってくるシステムが変わったときも同じです。
業務への着地：定義書があると、受け取った人がすぐ集計に入れる
テーブル定義書があると、データを受け取った人は、項目の意味を聞き直さずに集計に入れます。
自分は、お客様からデータをもらって分析するときは、必ず「定義書はありますか」と聞いています。定義書がないと、項目ごとの質問のやり取りや推察が増えて、手間がかかるからです。
推察には、外れるおそれもあります。円とドルを取り違えたまま集計すると、出てくる数字そのものが違います。
渡す人にとっても、同じ質問に何度も答えずに済みます。
まとめ
テーブル定義書は、項目ごとに次の4つを書きます。
- 項目名
- データ型
- 意味(単位もここに書く)
- 取得方法(どのシステムから取ったか、どう計算・抽出したか)
書き終えたら、受け取る人のつもりで、単位と元のシステムを見直します。データの中身が変わったら、変わった箇所だけ直します。
次に読む記事
定義書の項目名やデータ型を見ながら、自分でデータを取り出すなら、SQLの基本から。
生成AIにSQLを書いてもらうときも、最初に渡すのはテーブル定義です。そのまま実行しない確かめ方は、こちら。
