メトリック定義

メトリック定義とは、計算方法が合意され、書き留められたビジネス上の数値です。たとえば Net Revenue、Headcount (FTE)、Units Shipped などです。その数値の元になるテーブル、行の合算方法、対象となる行、および内訳として指定できる列を定めます。

メトリック定義がない場合、AI アシスタントに 「先四半期の EMEA の純売上高はいくらでしたか?」 と尋ねると、アシスタントが使用するテーブル、列、フィルターを自分で判断するため、同じ質問をしても人によって異なる数値が返されることがあります。メトリック定義は、その判断をアシスタントから取り除きます。プロジェクトのアーキテクトが定義を一度書けば、保存した時点から、アシスタントは書かれたとおりに数値を計算します。

アーキテクトの方は、メトリックを定義するから始めてください。アナリストの方は、メトリックについて質問するから始めてください。

メトリック定義は、保存された結果ではなくレシピです。要求されるたびに、質問した人の行アクセスのもとで再計算されます。EMEA の行しか見えない人には、EMEA の数値が返されます。同じ定義から人によって異なる合計が得られることがありますが、それは見える行が異なるためで、計算自体は同じです。

定義に含まれる内容

項目	内容	例
名前	人がその数値を呼ぶときの名称。最大 200 文字。	Net Revenue
類義語	人がその数値に使う別の言葉。アシスタントが質問を認識できるようにします。最大 25 個。	revenue、sales
説明（API では `memo`）	その数値の意味と使用する場面。アシスタントと人の両方のためのものです。最大 1,000 文字。	返品と値引き後の売上高。すべての売上高に関する質問に使用します。
ソーステーブル	行の取得元のテーブル。	`sales_fact`
結合	一致する列でソースに結合されるルックアップテーブル。各ルックアップテーブルは、キーごとに 1 行のみ（たとえば地域コードごとに 1 行）にする必要があります。そうでないと、一致する行が二重にカウントされます。	`region_lookup`（ソースの `region_code` をルックアップの `code` に対応付け）
メジャー	行の合算方法。列の `sum`、`count`、`count_distinct`、`min`、`max`、`avg`、または 2 つ目の列（`weight`）で重み付けした列の `weighted_avg`。これは、両方が設定されている行について値と重みの積を合計し、それらの重みの合計で割った値です。重みの合計がゼロの場合は空になります。	`net_amount` の `sum`、`units` で重み付けした `unit_price` の `weighted_avg`
フィルター	常に対象となる行。各フィルターは、列、演算子（`eq`、`ne`、`in`、`not_in`、`lt`、`le`、`gt`、`ge`、`between`、`is_null`、`not_null`）、およびその値で構成されます。	`status` `eq` Posted
内訳列（API では `grain`）	質問するときに、人がグループ化やフィルターに使用できる列。フィルターは固定ですが、内訳列は質問者が選べます。	`region_lookup.region`、`product_line`、`fiscal_year`
シナリオ（任意）	実績行と予算行を区別する列と、それぞれの値。メトリックの対象は実績行です。予算行は差異の計算にのみ読み取られます。	`scenario`、実績は Actual、予算は Budget
ディメンション（任意、API では `dimensions`）	ディメンションに関連付けられた内訳列。質問内の言葉がそのディメンションのメンバーとエイリアスと照合され、列の値に変換されます。メトリックについて質問するを参照してください。ディメンションはプロジェクト内に存在している必要があります。	Region ディメンションに関連付けられた `region_lookup.region`
時間列（任意、API では `time`）	日付列、または会計年度列と期間列。質問で特定の会計期間を指定し、時間の経過に沿って比較できるようにします。	`fiscal_year` と `fiscal_period`

ルックアップテーブルの列は <table>.<column> と書きます。アシスタントがこの形式で記述します。定義内のすべてのテーブルと列は、プロジェクト内に存在している必要があります。存在しないものを指定した定義は、保存時に拒否されます。シナリオを持つメトリックでは、シナリオ列でフィルターしたり、内訳列として提示したりすることはできません。シナリオは読み取る行を決めるため、scenario eq Actual のようなフィルターは、フィルターではなくシナリオに記述します。

メトリックは、他のメトリックを使って、比率、合計、差、倍数として構築することもできます。他のメトリックから派生させるを参照してください。

プロジェクト内の 2 つのメトリックが同じ名前や類義語を持つことを妨げるものはありません。区別できるようにしておかないと、アシスタントはどちらを指すのか推測するか、確認する必要があります。

誰が何をできるか

プロジェクトのアーキテクトは、定義の作成、編集、廃止を行えます。公開プロジェクトでは、すべてのメンバーに名目上のみアーキテクトロールが付与されますが、これは有効ではありません。公開プロジェクトでは誰もメトリックを定義できないため、メトリックは独自のアクセスリストを持つプロジェクトに置いてください。
プロジェクトを読み取れる人は、定義の表示と実行ができます。
ロックされたプロジェクトでは、すべての変更が拒否されます。 定義、編集、廃止は、プロジェクトのロックが解除されるまで待機します。

メトリックを定義する

プロジェクトのアーキテクトの場合は、接続した AI アシスタントに自然な言葉で依頼します。

「Sales プロジェクトで、Net Revenue という名前のメトリックを定義してください。類義語は revenue と sales です。sales_fact の net_amount の合計で、region_code で region_lookup に結合し、ルックアップの region、product_line、fiscal_year で内訳を指定できるようにします。実績行は scenario が Actual、予算行は scenario が Budget です。」

アシスタントが保存し、指定したテーブルや列が存在しない場合は通知します。メトリックは保存した時点で有効になります。編集のたびに定義の新しいバージョンが作成され、変更した人が記録され、読み取り側はすぐに新しいバージョンを利用します。何も変更しない保存は拒否されます。最後に保存されたバージョンが、そのメトリックの現在のバージョンです。

開発者向けに、同じ定義を REST API で行う場合は次のとおりです。

POST /rest/v1/analyze/metric/definition
{
  "project_id": "<project>",
  "name": "Net Revenue",
  "synonyms": ["revenue", "sales"],
  "memo": "Revenue after returns and discounts. Use for all revenue questions.",
  "definition": {
    "source": "sales_fact",
    "joins": [{"table_id": "region_lookup", "on": [["region_code", "code"]]}],
    "measure": {"agg": "sum", "column": "net_amount"},
    "filters": [],
    "grain": ["region_lookup.region", "product_line", "fiscal_year"],
    "scenario": {"column": "scenario", "actual": "Actual", "budget": "Budget"},
    "time": {"year_column": "fiscal_year", "period_column": "fiscal_period"}
  }
}

on の各ペアは [source column, lookup column] です。time は、periods_per_year を任意で指定できる {"year_column", "period_column"} か、fiscal_year_start と fiscal_year_label を任意で指定できる日付列用の {"column"} のいずれかです。時間の経過に沿って比較するを参照してください。

保存時に確認される内容

保存のたびに次のチェックが実行され、いずれかに失敗した定義は、問題を示すメッセージとともに拒否されます。

すべてのテーブルと列が存在すること（プロジェクト内）。
すべてのルックアップテーブルがキーごとに 1 行であること（その時点のデータで確認）。同じキーに対して 2 行あるルックアップテーブルは、一致するソース行を二重にカウントしてしまうため、保存は拒否され、そのテーブル名が示されます。キー値のないルックアップ行は、ソース行と一致することがないため、このチェックでは無視されます。
派生メトリックの入力が存在すること。また、廃止されておらず、それ自体が派生メトリックでもないこと。

各バージョンには、保存した人と日時が記録されます。メトリックを編集すると新しいバージョンが保存され、読み取り側はすぐにそれを利用します。

他のメトリックから派生させる

派生メトリックは、すでに存在するメトリックに対する算術演算です。たとえば Net Revenue per FTE は、Net Revenue を Headcount (FTE) で割ったものです。定義、質問、廃止は他のメトリックと同様に行います。異なるのは定義で、テーブルではなく、元になるメトリックを指定します。

演算	計算内容	入力
`ratio`	1 つ目の入力を 2 つ目の入力で割る	メトリック 2 つ
`add`	1 つ目の入力に 2 つ目の入力を足す	メトリック 2 つ
`subtract`	1 つ目の入力から 2 つ目の入力を引く	メトリック 2 つ
`scale`	入力に固定の `factor` を掛ける	メトリック 1 つと数値

入力は、同じプロジェクトのベースメトリック、つまり上記のテーブルから定義されたメトリックです。派生メトリックを別の派生メトリックから構築することはできず、同じ入力を 2 回使用することもできません。

アシスタントに次のように依頼します。

「Sales プロジェクトで、Net Revenue per FTE という名前のメトリックを、Net Revenue と Headcount (FTE) の比率として定義してください。」

REST API では、definition で入力をその ID によって指定します。ID は metric_find または定義の一覧で確認できます。順序が重要です。最初の ID は ratio の分子であり、subtract では引かれる側のメトリックです。

{
  "kind": "derived",
  "op": "ratio",
  "inputs": ["<Net Revenue metric_id>", "<Headcount (FTE) metric_id>"]
}

scale は 1 つの入力と factor を取ります。{"kind": "derived", "op": "scale", "inputs": ["<Monthly Run Rate metric_id>"], "factor": 12} は、月次の数値を年換算します。

計算方法。 各入力は、指定した内訳で、質問者の行アクセスのもとで個別に計算され、その結果が内訳値ごとに組み合わされます。組み合わせる前に各入力を合計することで、2 つのテーブルの比率が正しく保たれます。先に行を結合すると、反対側で出会った行の数だけ行が重複してカウントされてしまいます。ある内訳値に対して一方の入力に行がない場合、その内訳値の派生値は空になります。分母がゼロの比率も空になります。どちらもゼロとしては報告されません。

内訳列は宣言ではなく算出されます。 派生メトリックは、すべての入力が許可している列でのみ内訳を指定できます。その一覧は定義の横に表示されます。派生メトリックを地域別に質問したい場合は、各入力に region_lookup.region を、同じ表記で内訳列として指定してください。内訳列を共有しない入力から作った派生メトリックは、単一の合計としてのみ回答します。それ以外の列でグループ化またはフィルターする質問は、他のメトリックと同様に拒否されます。派生メトリックの横の一覧が空の場合は、入力の 1 つが使用できなくなっている（廃止されているか、存在しない）ことを意味します。

保存時に入力が確認されます。 派生メトリックは、各入力が存在し、廃止されておらず、それ自体が派生メトリックでない場合にのみ保存できます。読み取り側もアーキテクトも、常に各入力と派生メトリックの現在のバージョンを利用します。入力はバージョンに固定されません。入力の新しいバージョンが保存されると、派生メトリックの数値もそれに応じて変わります。

派生メトリックが使用している間、入力は使用中のままです。 その入力は廃止できず、派生メトリックに変更することもできません。拒否メッセージには、それを使用しているメトリックが示されます。入力を廃止するには、先に派生メトリックを廃止するか、その入力を使用しないバージョンを保存します。

メトリックについて質問する

プロジェクトを読み取れる人なら誰でも、PlaidCloud 組み込みの AI アシスタント、または MCP で接続したアシスタントに質問できます。

「FY26 の地域別の純売上高はいくらでしたか?」

アシスタントは、名前または類義語のいずれかによってメトリックを認識し（検索では大文字と小文字が区別されず、名前の一部にも一致するため、revenue で Net Revenue が見つかります）、質問から内訳とフィルターを取り出して、定義を実行します。質問でグループ化やフィルターができるのは、メトリックの内訳列のみです。それ以外を求める質問は、推測で回答されるのではなく拒否されます。保存後にテーブルから列がなくなったメトリックも同様です。その場合は、拒否メッセージにメトリックとそのバージョンが示され、アーキテクトが定義を修正する必要があります。

質問内の言葉は、ディメンションを通じて列の値になります。 アーキテクトが内訳列をディメンションに関連付けている場合、アシスタントは質問内の言葉を、そのディメンションのメンバー名とエイリアスと、大文字と小文字を区別せずに照合します。1 つのメンバーに一致する言葉は、そのメンバーの値になります。リーフはそれ自身の値になり、EMEA のような親は配下のすべてのリーフに展開されるため、「EMEA の純売上高」は EMEA のすべての地域でフィルターされます。どのメンバーにも一致しない言葉、または複数のメンバーに一致する言葉（Seaboard は 2 つのメンバーのエイリアスである場合があります）で、入力したとおりの表記に完全に一致するものがない場合は、アシスタントがユーザーに確認するための候補一覧として返されます。アシスタントが勝手に 1 つを選ぶことはありません。ディメンション内で言葉を照合するには、PlaidCloud の他の場所でディメンションを読み取る場合と同様に、ディメンションの読み取り権限が必要です。

アシスタントが利用する結果には、メトリックとそのバージョンが示され、行アクセスが適用されたかどうかも示されます。回答にどのメトリックを使用したかが示されていない場合は、確認してください。PlaidCloud 組み込みの AI アシスタントでは、数値は ✓ 付きの専用カードに表示されます。メトリックからの数値を参照してください。PlaidCloud が AI の回答を評価し、注意事項を付ける方法の全般については、信頼できる回答を参照してください。

行アクセスは、メトリックが読み取るすべてのテーブルに適用されます。 ソースもルックアップも同様です。ルックアップ行が自分には非表示でも、それがラベル付けするソース行が表示される場合、そのソース行はカウントされます。たとえば、地域 APAC のルックアップ行は見えないが、その売上は見える場合、その売上は合計に含まれ、地域別の内訳では空白の地域の下に表示されます。地域でフィルターした場合や、メトリック自体がルックアップ列でフィルターする場合は、通常は除外されます。

行アクセスはルックアップにも影響します。内訳列が管理されている場合、アクセスが許可されている値のみが提示されます。見ることができる配下のメンバーが 1 つもないメンバーは、値としても候補としても提示されず、親は見ることができるリーフにのみ展開されます。すべての行を読み取るアーキテクトには、すべてのメンバーが表示されます。

アーキテクトは、プロジェクト内の他の場所と同様に、すべての行を読み取ります。

比較、ランキング、構成比

メトリックに関する質問では、1 つの比較、1 つのランキング、および合計に対する構成比も求められます。いずれも、質問者の行アクセスのもとで、メトリック自身の数値に対する固定の計算であり、アシスタントが算出するものではありません。

求めるもの	返される内容	API での指定
予算に対する差異	内訳値ごとに、実績値、予算値、差（`value`）、予算の大きさに対する差の割合（`pct`）。予算が負の場合は差の符号を維持します。	`compare: "variance"`
合計に対する構成比	各行の数値を、内訳のすべての行の合計（`share`）、または指定した `within` 列を共有する行の合計で割った値。	`share: {"within": ["region"]}`、全体の合計の場合は `{}`
上位または下位 N 件	数値が高い方から N 件、または `order: "asc"` を指定して低い方から N 件を、`rank` とともに返します。`within` 列を指定した場合はグループごとです。同点の行は同じ順位を共有し、すべて保持されるため、N 件より多くなることがあります。コストのメトリックでは、予算を最も超過しているものは差異の上位 N 件であり、売上高のメトリックでは下位 N 件です。	`top: {"n": 10, "within": [], "order": "desc"}`

「Finance プロジェクトで、予算を最も超過している 5 つのコストセンターはどれですか?」

「各地域は総支出の何割を占めていて、最も大きいのはどの地域ですか?」

差異にはシナリオを持つメトリックが必要です。シナリオのないメトリックや派生メトリックでは拒否されます。比較の前に、各側は個別に合計されます。予算行がない、または実績行がない内訳値は、ゼロではなく空の差を示します（例外は、単一の合計として求められた count メトリックで、行のない側はゼロとしてカウントされます）。予算がゼロの場合の割合も空になります。

ランキングと構成比は、メトリックの数値に対して行われます。差異または時間の経過に沿った比較が求められた場合は、その差に対して行われます。したがって、「超過支出の大部分を占めるコストセンターはどれですか」 という質問は、構成比とランキングを伴う差異になります。pct はパーセンテージなので、12 は 12% を意味し、share は小数です。構成比は、上位 N 件が一部の行だけを残す前に、内訳のすべての行に対して算出されるため、返された行の構成比の合計が 1 になるとは限りません。空の数値は、どちらの順序を指定してもランキングの最後になり、構成比も空になります。合計がゼロの場合の構成比も同様です。

構成比は、自分に見える範囲に対するものです。行アクセスが EMEA に限定されている人は、EMEA のコストセンターを EMEA の合計に対する構成比で受け取り、結果には行アクセスが適用されたことが示されます。構成比またはランキングの within 列は、質問で指定した内訳列に含まれている必要があります。また、結果自身の列と同じ名前の列（value、および、それを生成する演算子が求められた場合の actual、budget、current、prior、pct、share、rank、year、period、cumulative）でグループ化する質問は拒否されます。2 つの比較、または 2 つのランキングを含む質問も拒否されます。

時間の経過に沿って比較する

定義に時間列（API では time）があるメトリックでは、特定の会計期間を指定し、その前の期間と比較し、期間ごとに累計することができます。時間列は、各行が会計カレンダー上のどこに位置するかを、次の 2 つの方法のいずれかで示します。

日付列と、会計年度が始まる暦月を表す fiscal_year_start（1 は 1 月でデフォルト）。期間は会計年度の各月で、開始月から番号が付けられます。10 月に始まる年度では、期間 1 が 10 月、期間 7 が 4 月です。四半期は 3 つの期間です。1 月以外に始まる会計年度は、デフォルトでは、それが終わる暦年の名前で呼ばれます（fiscal_year_label は ending）。始まる年の名前で呼ぶには、fiscal_year_label を starting に設定します。10 月開始の場合、2025 年 10 月から 2026 年 9 月までの月は、デフォルトでは FY2026 であり、starting では FY2025 です。行は日付範囲で読み取られるため、大きなテーブルでも質問が高速に処理されます。
会計年度列と期間列。どちらも整数で、会計年度（26 ではなく 2026）と、その中の期間を 1 から番号付けしたものを保持し、periods_per_year を指定します。デフォルトは 12 で、13 期間のカレンダーでは 13、週の場合は 52、四半期の場合は 4 です。四半期は、期間が 4 つに分かれる場合にのみ存在します。53 週の年があるカレンダーでは 53 を設定できますが、四半期は使用できなくなります。どちらかの列に 2024-01 や FY26 のような整数でない値が含まれている場合、保存は拒否され、拒否メッセージに列と値が示されます。07 のようにテキストとして保存された数字は受け付けられます。また、元帳の期間 0 や 13 のように年の範囲外の期間も受け付けられます。期間に関する質問では、それらの行は除外されます。

質問では、対象とする期間（会計年度、またはその中の 1 つの四半期か 1 つの期間）を指定します。年初来は、それを年の初めまでさかのぼって含めます。したがって、4 月までの年初来 は、その年の最初の月から 4 月までを含みます。

「FY2026 第 1 四半期の地域別の売上はいくらで、その前の四半期と比べてどうでしたか?」

「4 月までの年初来の売上を、前年の同じ月と比較してください。」

「FY2026 の月別売上を累計で表示してください。」

求めるもの	返される内容	API での指定
1 つの期間	その期間のみのメトリック。通常の内訳、構成比、ランキングを伴います。予算に対する差異では、その期間について両方のシナリオが読み取られます。	`period: {"year": 2026}`、`{"year": 2026, "quarter": 1}`、`{"year": 2026, "period": 7}`
前年比	内訳値ごとに、その期間の数値（`current`）、1 年前の同じ期間の数値（`prior`）、差（`value`）、`pct`。回答には前の期間が示されます。	`period` を伴う `compare: "yoy"`
前四半期比	同じ内容を、その前の四半期と比較します。第 1 四半期は前年の第 4 四半期と比較されます。	`compare: "qoq"`、`period` には `quarter` を指定する必要があります
前期間比	同じ内容を、その前の期間と比較します。最初の期間は前年の最後の期間と比較されます。12 期間のカレンダーでは前月比となり、名称の由来はここにあります。	`compare: "mom"`、`period` には `period` を指定する必要があります
年初来	年の初めから指定した四半期または期間の終わりまで。単独で、または `yoy` と組み合わせて前年の同じ月と比較します。`qoq` または `mom` とは併用できません。	`period` 内の `"to_date": true`
累計	指定した期間に含まれる会計年度と期間ごとに 1 行。その期間自身の数値（`value`）と、そこまでの累計（`cumulative`）を返します。期間を指定しない場合は、年をまたいで最初の行から最後の行まで続きます。比較、構成比、ランキングは指定できません。	`cumulative: true`

pct は、前の数値の大きさに対する差の割合で、差異と同様に、前の数値が負の場合は差の符号を維持します。2 つの期間はそれぞれ個別に合計され、2 つの合計は内訳値で対応付けられます。隣接する行から読み取られるものはありません。したがって、前年に行がない月は、行のある最も近い月ではなく空として比較されます。2 つの期間の一方にのみ行がある内訳値では、もう一方、差、pct がゼロではなく空として表示されます。

累計は、sum と count のメトリック用です。平均、重複を除いた件数、最小値、最大値は時間の経過に沿って加算できないため、拒否されます。行のない期間は累計に行を持たず、累計はその期間を越えて続きます。

期間を指定する質問、時間の経過に沿って比較する質問、累計を求める質問では、時間列でフィルターやグループ化はできません。これらは、読み取る行と配置を決めるためです。これらのいずれも行わない質問では、他の内訳列と同様に、時間列でフィルターやグループ化ができます。また、年の範囲を超える期間（12 期間のカレンダーでの期間 13）、四半期のないカレンダーでの四半期、派生メトリックでの時間の比較や累計、および比較に必要な期間の種類を示していない質問も拒否されます。派生メトリックは、すべての入力が同じ会計カレンダー上の時間列を持っている場合、1 つの期間について質問できます。その場合も、それらの列でフィルターやグループ化はできません。時間の比較は質問の唯一の比較であるため、予算に対する差異と組み合わせることはできませんが、構成比とランキングは差に対して引き続き適用できます。

メトリックを廃止する

メトリックを廃止すると、そのメトリックは恒久的に使用されなくなります。プロジェクトを読み取る人には表示されなくなり、アーキテクトには履歴とともに廃止済みとして表示され、編集も実行もできなくなります。アーキテクトは、アシスタントに依頼するか、POST /rest/v1/analyze/metric/retire を使用して廃止します。派生メトリックの元になっているメトリックは、その派生メトリックを廃止するか、この入力を使用しなくなったバージョンを保存するまで、廃止できません。廃止したメトリックを置き換えるには、新しいメトリックを定義します。

MCP と REST API 経由

アクション	MCP ツール	REST
プロジェクトのメトリックを、完全な定義とともに一覧表示します。`q` は、名前または類義語にそれを含むものに絞り込みます	`metric_find`	`GET /rest/v1/analyze/metric/definitions?project_id=&q=`
質問内の言葉を内訳列の値に解決します	`column` と `words` を指定した `metric_values`	`GET /rest/v1/analyze/metric/values?project_id=&metric_id=&column=&words=`
1 つのメトリックを読み取ります		`GET /rest/v1/analyze/metric/definition?project_id=&metric_id=`
定義または編集します	`metric_upsert`	`POST` / `PUT /rest/v1/analyze/metric/definition`
廃止します	`action: retire` を指定した `metric_review`	`POST /rest/v1/analyze/metric/retire`
実行します	`group_by`、`filters`、および任意の `period`、`compare`、`share`、`top`、`cumulative` を指定した `metric_run`	同じフィールドを指定した `POST /rest/v1/analyze/metric/run`
以前のバージョン（アーキテクトのみ）		`GET /rest/v1/analyze/metric/flashback-versions`

metric_upsert は {name, memo, synonyms, definition} の spec を取り、保存せずに定義を確認するための dry_run を受け付けます。ベースメトリックの definition は {source, joins, measure, filters, grain, dimensions, scenario, time} です。dimensions は {<breakdown column>: <dimension id>}、measure は {agg, column} または {agg: "weighted_avg", column, weight}、scenario は {column, actual, budget}、time は {column, fiscal_year_start, fiscal_year_label} または {year_column, period_column, periods_per_year} です。派生メトリックの definition は {kind, op, inputs, factor} です。算出された内訳列は、定義の横に grain として返されます。