分析パス

分析パスは、「営業成績」や「損益計算書」のように、頻繁に分析するテーブルにつけるわかりやすい名前です。一度登録すれば、以降はユーザーも接続済みのAIアシスタントも、毎回どのプロジェクトのどのテーブルかを繰り返さなくても、その名前でテーブルについて質問できます。

1つをワークスペースのデフォルトにすると、「先四半期にこれが増えたのはなぜですか？」のような単純な質問でもそのまま機能します。アシスタントは「これ」が何を指すかをすでに把握しているからです。

使用する理由

分析パスがないと、質問のたびにデータの場所、つまりプロジェクトとテーブルの両方を正確に書く必要があります。これはすぐに面倒になり、間違いも起こりがちです。分析パスがあれば、実際にデータを考えるときの言葉でデータについて話せます。

名前で質問できます。「プロジェクト Enterprise Profitability のテーブル ops_summary_v3 を要約してください」ではなく、「営業成績を要約してください」と尋ねられます。
デフォルトを設定できます。 最もよく使うテーブルをデフォルトにすれば、名前を完全に省略できます。「先月から何が変わりましたか？」で、正しいデータに自動的に行き着きます。
全員の認識をそろえられます。 チーム全員が「損益計算書」と言えば、全員が同じテーブルに到達します。推測も、古いコピーもありません。

分析パスを登録する

ワークスペースの管理者であれば、フォームや設定画面は不要です。接続済みのAIアシスタントに、普通の言葉でパスを登録するよう依頼するだけです。

「Enterprise Profitabilityプロジェクトのops_summaryテーブルを指す、営業成績という名前の分析パスを登録してください。」

アシスタントがパスを確認し、すぐに使用できるようになります。登録できる数に制限はなく、定期的に分析するテーブルごとに1つ登録できます。

デフォルトのパスを設定する

管理者は、1つのパスをデフォルトにして、テーブルを指定しない質問が自動的にそのパスに向かうようにできます。

「営業成績をデフォルトの分析パスにしてください。」

以降は、「今四半期の変動が大きかった項目は何ですか？」や「合計が減ったのはなぜですか？」といった質問が、他に何も指定しなくてもそのテーブルに対して実行されます。デフォルトはワークスペース全体で1つだけなので、全員の対象を指定しない質問は同じテーブルに解決されます。新しいデフォルトを設定すると、単にその座が移動します。デフォルトは常に1つだけで、どれであるかはアシスタントが知らせます。

AIアシスタントに役立つパスにする

名前とテーブルで、アシスタントはデータがどこにあるかを把握できます。しかし、データが何を意味するか、つまりどのフィルターを常に適用するか、会計年度がどのように決まるか、チームの用語が何を指すかまではわかりません。それがないと、アシスタントは推測することになり、自信を持った誤答は、遅い回答よりも悪い結果になります。このセクションでは、その知識を記述する2つの場所と、どちらも重要である理由を説明します。

このガイドでのAIアシスタントとは、PlaidCloud MCP経由で接続されたあらゆるLLM（Claude、Microsoft Copilot、ChatGPTなど）と、PlaidCloudの組み込みAIを指します。

プロンプトガイダンスを追加する

各分析パスにはプロンプトガイダンスがあります。これは、アシスタントにパスの使い方を伝える、ユーザーが書く自由形式のテキストです。1行に1つの指示を書きます。

追加するには、ツールメニューを開いて分析パスを選択し、パスを選択して編集を選択します（新しく作成するには新規を選択します）。プロンプトガイダンスフィールドはテーブルの次、ワークスペースのデフォルトに設定の直前にあります。分析パスを管理する権限で接続されたアシスタントも、これを設定できます。MCPとAPIの呼び出し元には、このフィールドはdescriptionとして表示されます。例：「営業成績パスのdescriptionを…に設定してください」

アシスタントは、プロンプトガイダンスを2通りの方法で使用します。

パスを選ぶため。 質問でパスが指定されていない場合、アシスタントは質問を各パスの名前とプロンプトガイダンスと比較し、最も合致するものを選びます。
標準のガイダンスとして。 パスを選んだ後、アシスタントはそのパスに対するすべてのクエリにプロンプトガイダンスを適用します。含めるフィルターや、変換する用語などです。MCP経由で接続されたアシスタントでは、ビジネス上の数値そのものはガイダンスではなく、プロジェクトのメトリック定義から取得されます。

プロンプトガイダンスはパスとともに保存され、分析パスを閲覧できるワークスペースの全員に表示されます。MCP経由で動作するアシスタントとPlaidCloudの組み込みAIに渡されます。ワークフローのLLMステップ内のAIアシスタンスには渡されません。

書く内容

このテーブルを使う初日の新人アナリストに伝えておくべきことを書いてください。指示ごとに1行を使います。

書く内容	例
パスが答える質問と、答えない質問。	「事業部門別の月次営業成績。収益、コスト、EBITDAに関する質問に使用します。従業員数や予測には使用しません。予測パスを使用してください。」
ビジネス用語が指すメトリック。 MCP経由で接続されたアシスタント向けです。	「『収益』は純収益メトリックです。`billed_amount`は請求額であり、収益ではありません。」
常に適用されるフィルター。	「予算について尋ねられない限り、常に`scenario = 'Budget'`を除外します。会社間取引の行は`entity_type = 'IC'`です。合計から除外してください。」
符号の規則、カレンダー、粒度。	「コストは負の値で保存されています。会計年度は7月に始まるため、FY26は2025年7月から2026年6月です。事業部門ごとに月ごとに1行です。」
データに対応付けたビジネス用語。	「『中西部』は`region IN ('IL','IN','OH','MI')`を意味します。『主力製品』は`product_tier = 'A'`を意味します。」

短く、具体的に書いてください。段落よりも、1行に1つの指示のほうが適しています。上限は1,000文字です。先頭と末尾の空白は削除されます。

書かない内容

アシスタントがすでに見ているもの。 列の型、キー、行数は、テーブルとともに返されます。これらを繰り返すと、1,000文字の上限を消費します。
1つの列が何を意味するか。 それは列のメモに書いてください。テーブルがどこで使用されても、メモは列とともに残ります。プロンプトガイダンスは、パス全体の使い方を示すためのものです。
機密情報。 プロンプトガイダンスは、テーブルのプロジェクトにアクセスできるユーザーだけでなく、ワークスペース全体に表示されます。パスワードやキー、個人データ、ワークスペースのメンバー全員に見せられない数値やコメントは含めないでください。

良いプロンプトガイダンスと弱いプロンプトガイダンス

以下の2つの例は同じパスに対するもので、同じ質問をしています。「昨年の中西部のEBITDAはいくらでしたか？」

	弱いガイダンス	良いガイダンス
テキスト	「営業データ。」	「事業部門別の月次営業成績。 EBITDA = `ebitda_adj`。`ebitda`は無視します。 `scenario = 'Budget'`と会社間取引の行（`entity_type = 'IC'`）を除外します。会計年度は7月に始まります。中西部 = IL、IN、OH、MI。」
アシスタントの動作	単なる`ebitda`列を選び、予算と会社間取引の行を含め、「昨年」を暦年として解釈します。	`ebitda_adj`を使用し、予算と会社間取引の行を除外し、直近で完了した会計年度を使用し、中西部の4州で絞り込みます。
回答	もっともらしいが誤っており、経理チームの数値とは異なる数値。	経理チームが報告する数値。

弱いガイダンスは誤りではありません。ただ、すべての判断をアシスタントの推測に任せているだけです。

列のメモを追加する

プロンプトガイダンスはパス全体を対象とします。列のメモは1つの列を説明するもので、アシスタントが列に実際に何が入っているかを知る手段になります。列名から用途が明確でない場合、メモがあるかどうかが、正しい列ともっともらしい誤った列との分かれ目になります。

パスのテーブルのメモは、列の一覧とともにAIアシスタントに返されます。table_describeにinclude=['columns']を指定した場合、メモがある各列にmemoとして含まれます。メモのない列は従来どおり返されます。同じメモは、ワークフローのLLMステップ内のAIアシスタンスにも、そのステップが使用するテーブルについて渡されます。

メモが必要な場合

メモを追加する対象	メモの例
コードと略語	`seg_cd`：「顧客セグメントコード。E = エンタープライズ、M = ミッドマーケット、S = 中小企業。」
似た名前の指標	`ebitda_adj`：「一時的な項目を除いたEBITDA。レポートにはこちらを使用します。`ebitda`は調整前です。」
フラグ	`is_ic`：「行が会社間取引の場合は1。連結合計からは除外します。」
単位または通貨	`amt_local`：「エンティティの現地通貨での金額（千単位）。」
導出値または配賦値	`alloc_cost`：「人員数に基づいてこのユニットに配賦された共通コスト。直接発生したものではありません。」

invoice_dateやcustomer_nameのように、名前だけで内容がわかる列は省略してください。名前を繰り返すだけのメモには意味がありません。

メモの追加方法

パスのテーブルをテーブルエクスプローラーで開きます。
ツールバーで列のプロパティをオンにします。
列の一覧で列を選択します。
メモにテキストを入力します。

テーブルに設定したメモは、そのテーブルが使われるすべての場所、つまりそのテーブルを指すすべての分析パスに適用されます。

プロンプトガイダンスとメモの使い分け

それぞれの事実は、1か所にだけ記述してください。

	プロンプトガイダンス	列のメモ
対象	パス全体の使い方	1つの列の意味
典型的な内容	答える質問、標準のフィルター、会計カレンダー、ビジネス用語	コード、単位、フラグ、似た名前のどれを使うか
例	「合計から会社間取引の行を除外します。」	`is_ic`：「行が会社間取引の場合は1。」

この例では、メモがis_icの意味を示し、プロンプトガイダンスがそれをどう扱うかを示しています。

使用方法

パスを登録したら、あとは質問するだけです。

名前で質問する：「営業成績の最初の数行を表示してください。」
デフォルトで質問する：「前四半期と比べて何が変わりましたか？」（テーブルを指定していないため、ワークスペースのデフォルトのパスが使用されます）。
自由に切り替える：「今度は予測について同じことをしてください。」アシスタントは、パスからパスへと追従します。

これは配賦に関する質問と自然に組み合わせられます。配賦のトレースを参照してください。「営業成績が変動したのはなぜですか？」から、その背後にある勘定科目とドライバーへと直接進めます。

MCP経由での使用

MCP経由で接続されたアシスタントがツールに分析パスを渡す場合、パスの名前（大文字と小文字は区別されません）またはIDのどちらかを使用できます。存在しないIDで更新されたパスは拒否されます。新しいパスを作成するには、IDを省略してください。

query_data_readは、table、json_paths、dimension_value、column_values、aggregateで、プロジェクトとテーブルの代わりにanalysis_pathを受け付けます。

一部の列だけをプレビューする。 query_data_read(action='table')にcolumns=[...]を渡すと、指定した列だけが返されます。行アクセスのルールは完全に適用されます。version_idとは組み合わせられません。

フィルター済みの合計を1回の呼び出しで取得する。 column_valuesに対して、メジャーと、対象とする列でのフィルターを指定します。

query_data_read(
  action='column_values',
  project_id=<project>,
  table_id=<table>,
  dimension_column_name=<filter column>,
  value_column_name=<measure>,
  filters={<filter column>: <value>}
)

その値に対する1行が返されます。列名のスペルが誤っている場合、エラーには最大5件の近い候補が示されるため、アシスタントは修正して再試行できます。

合計または内訳を1回の呼び出しで取得する。 action='aggregate'を使用すると、行を読み取る代わりに、サーバー上で1つ以上の列でグループ化し、メジャーの合計、平均、件数を求められます。

query_data_read(
  action='aggregate',
  project_id=<project>,
  table_id=<table>,
  group_by=['Product'],
  measures=[{'column': 'Revenue', 'agg': 'sum'}, {'column': 'Volume'}],
  filters={'Fiscal Year': 2027},
  order_by='Revenue',
  limit=10
)

measuresのaggには、sum（デフォルト）、avg、min、max、countを指定できます。countは'*'も受け付けます。filtersの値にはリストを指定でき、複数の値のいずれかに一致させられます。limitのデフォルトは50で、最大は500です。order_byにはメジャーまたはグループ列を指定します。メジャーは大きい順に並べ替えられます。応答にはrows、total_groups、truncatedが含まれ、これはlimitで返された数より多くのグループが存在する場合にtrueになります。行アクセスのルールは、合計が計算される前に適用されます。

設定できるユーザー

分析パスの設定（登録とデフォルトの選択）は管理者の操作です。これにより、共有される名前が全員にとって整理された信頼できるものに保たれます。作成された後は、ワークスペースの全メンバーが質問の中でそれらを使用でき、各メンバーには自身の権限で許可されたデータだけが表示されます。