metrics

メトリクス

メトリクスとは、完全修飾名で示されるセマンティックモデルの尺度です。 crm_deals.amount。アプリのメトリクスページには、データソースから構築されたキューブのすべての尺度が一覧表示されます。各メトリクスのページでは、スコープ（セグメントまたはいくつかの条件）で件数を数え、ディメンション別に内訳を表示できます。ダッシュボードカードに保存されるのと同じ3つの設定です。このスキルは読み取り専用です。ここから書き込みは行いません。

1つのメトリクスに関する質問ではない、その場限りの分析的な質問（複数の尺度を一度に扱う、カスタムグループ化、キューブをまたいだ上位N件など）には、セマンティックモデルスキルが適しています。ユーザーが名前の付いたメトリクスを前提に考えている場合や、カードに表示される数値を知りたい場合は、このスキルを使用してください。

カタログ

api_read { "resource": "cubes", "method": "meta", "params": { "fields": "name,title,description,type", "pageSize": 100 } }
api_read { "resource": "cubes", "method": "meta", "params": { "filter": "name == \"crm_deals\"" } }

アプリに表示されるのはソースキューブのみの尺度です。次のものは除外します。

• type: "view" — テーブルのビュー（model_…）は、尺度を新しい名前で再エクスポートします。それぞれの尺度のaliasMemberは元の尺度を指します。
• 生成されたキューブ（meta.abConnectionId: "revos"で識別）— セグメントのスナップショット（segment_…）とテーブル自身の列（model_stream_…）です。fieldsでmetaを指定することはできませんが、候補キューブを確認する際に読み込むレコード全体に含まれています。

カタログに表示される尺度ごとの情報は次のとおりです。

列	metaから取得
メトリクス	title（ツールチップとしてdescription）、参照先としてname
キューブ	キューブのtitle
集計	aggType：count、countDistinct、sum、avg、min、max、number、…
形式	formatがcurrency／percent。それ以外は型に応じて、Number、Text、Boolean、Date

カードで件数を数えられるのはtype: "number"の尺度のみです。ユーザーがテキスト、ブール値、または時間の尺度を選んだ場合は、その旨を伝えてください。

ユーザーが意味に基づいてメトリクス（「成約率」「ARR」など）を尋ねた場合は、タイトルと説明を検索してください。一致するものがなければ、その旨を伝えて最も近い候補を提示するか、キューブスキルで追加することを提案してください。別の尺度で黙って代用してはいけません。

メトリクスの使用箇所

• テーブル：ビューmodel_<table id, '-' → '_'>は、その尺度を再エクスポートします（aliasMember == "<measure>"）。IDから名前を特定するには、api_read { "resource": "tables", "params": { "fields": "id,name" } }を使用します。
• セグメント：尺度（またはそのビューのエイリアス）は、セグメントのfilter内のmemberです。
• ダッシュボード：api_read { "resource": "dashboard-cards", "params": { "filter": "measure == \"<measure>\"" } }。

メトリクスの値

api_read { "resource": "cubes", "method": "query", "body": { "query": … } }を使い、アプリがクエリを構築する方法と正確に同じ方法で構築します。そうしないと、ユーザーの画面に表示される数値と異なります。

{
  "measures": ["<measure>"],
  "filters": [ <the scope's conditions, as Cube filters> ],
  "joinHints": [ <each join path, split on "."> ]
}

空の場合はfilters／joinHintsを省略してください。

スコープ

• すべての行 — フィルターなし。
• 条件 — セグメントのフィルター構文（segmentsスキルのreferences/filter-syntax.mdを参照）で記述し、その対応表に従って変換します。EQUAL → equals、EMPTY → notSet、CHECKED → equals "true"、… トップレベルのAND項目はそれぞれ別のfiltersエントリにします。ORは{ "or": [ … ] }、ANDグループは{ "and": [ … ] }にします。memberがない条件や、演算子が値を必要とするのにvalueがない条件はスキップします。アプリも同様に処理します。文字列に対するEQUALの前に、キューブクエリで保存値を確認してください。
• 動的セグメント — セグメントを読み込み、そのfilterを同じ方法で変換し、cubes[1..].joinPathを先にjoinHintsに指定します。
• 静的セグメント — 条件の代わりに、次のフィルターを1つ指定します。 { "member": "segment_<segment id, '-' → '_'>.id", "operator": "set" }。 meta内にそのsegment_…キューブが必要です。

セグメントがメトリクスに適用できるのは、そのルートキューブがメトリクスのキューブと同じ場合のみです（segment.cubes[0].joinPath）。企業のセグメントを案件のメトリクスのスコープにはできません。その旨を伝え、代わりに企業フィールドに対する条件を提案してください。

他のキューブへの結合

別のキューブに対する条件や内訳では、指標のキューブからの結合パスをたどって読み取ります：crm_deals.crm_companies。各経路を meta の joins（どちらか一方に定義されています）と照合してください。経路が2つある場合、どちらを選ぶかで数値が変わります。ユーザーがどちらを意味しているのか確認してください。各パスは結合ヒントとして送信します。例：["crm_deals", "crm_companies"]。指標自体のキューブには必要ありません。

アプリが受け付けない次の2つの条件は、あなたも受け付けないでください。

• メジャーに対する条件（crm_deals.count > 3）。合計値に対しては行ごとの条件にならず、対象範囲を定めるものではありません。
• 指標の行に複数存在するキューブに対する条件（パス上の hasMany ／ one_to_many）：各行が関連する行ごとに1回ずつチェックされます。

内訳

同じクエリにディメンションを加えます。

• 時間ディメンション以外の場合："dimensions": ["<dim>"]、 "order": { "<measure>": "desc", "<dim>": "asc" } — 大きいグループから表示します。
• 時間ディメンションの場合："timeDimensions": [{ "dimension": "<dim>", "granularity": "month" }]、 "order": { "<dim>": "desc" } — 新しい月から表示します。

内訳の合計が総計と一致するのは、メジャーが count または sum で、かつ内訳が行に複数存在する結合を経由しない場合だけです。それ以外では、割合や「その他」の区分を表示しないでください。また、行が複数のグループに分かれる内訳では、複数のグループに関連付けられたレコードは各グループでカウントされると伝えてください。カードには上位5件と「その他」が表示されます。指標ページには50件が表示されます。

結果の読み取り

• 行がない場合：count、count distinct、sum は 0 です。平均やその他のメジャーには値がありません。「0」ではなく「値なし」と伝えてください。
• メジャーの format（通貨、パーセント）に従って書式を整えてください。
• 数値が何を対象に集計したものか、必ず伝えてください：「EMEA セグメントの案件における、オープン中のパイプライン €1.2M」。
• 結果の metadata.lastRefreshTime はデータの鮮度を示します。古い場合、または slowQuery が設定されている場合は、そのことに触れてください。

単一の値は1行で、内訳は小さな表で、役立つ場合はチャートで表示してください。