TOMLでメタオブジェクトのAnalytics連携を設定

11月 01, 2026

ANALYTICS

TOMLでメタオブジェクトのAnalytics連携を宣言的に設定

shopify.app.tomlに1行追加するだけで、独自データをShopify Analyticsの分析軸に

このアップデートはshopify.app.tomlでメタオブジェクト定義を宣言しているアプリ開発者が対象です。2026年10月23日より、TOMLファイルにcapabilities.analytics_queryable = trueを追加するだけで、対応フィールドをShopify AnalyticsとShopifyQLの分析軸・フィルターとして利用できます。デフォルトはオフのため、既存アプリへの影響はありません。

1何が変わったか — Before / After 図解

2具体的な設定例

以下はTOMLの記述例です（公式サンプルを再構成）。

[metaobjects.app.designer]
name = "Designer"
capabilities.analytics_queryable = true

[metaobjects.app.designer.fields.country]
name = "Country"
type = "single_line_text_field"

この例では designer メタオブジェクトの country フィールド（single_line_text_field型）がShopify Analyticsのディメンション・フィルターとして利用可能になります。

3Analytics対応フィールド型 vs 非対応型

✅ 対応型（クエリ可能になる）

single_line_text_field
number_integer
date
product_reference
その他 analytics-compatible な型

❌ 非対応型（無視される）

上記以外の型
非対応型のみの定義でdeployすると
バリデーションエラー
対応型が1つもない場合は
リリース失敗

4業務に活かせる具体ユースケース

課題: ブランドや素材などの独自属性をメタオブジェクトで管理しているが、Shopify Analyticsでの売上分析に活かせていない
打ち手: 商品メタフィールドで参照しているメタオブジェクト定義にcapabilities.analytics_queryable = trueを追加し、ブランド名・素材名フィールドをAnalyticsのディメンションとして有効化
効果: 「ブランド別売上」「素材別コンバージョン率」などをShopify Analytics標準レポートやShopifyQLで直接集計できるようになり、BIツール連携の工数を削減
技術メモ: フィールド型がsingle_line_text_fieldであることを確認。デプロイ後にGraphQL Admin API 2027-01以降でcapabilities.analyticsQueryable.enabled = trueを検証

課題: 複数のアプリを横断してメタオブジェクト定義を管理しており、Analytics連携の設定漏れが発生しやすい
打ち手: TOML宣言にcapabilities.analytics_queryableを組み込み、IaCとしてGitで定義・レビュー・バージョン管理。CIパイプラインでdeploy前に対応フィールド型の存在チェックを自動化
効果: 設定の一元管理と属人化の排除。コードレビューでAnalytics設定の意図が明示され、意図しない設定変更を防止
技術メモ: TOML宣言定義はGraphQL APIから読み取り専用のため、API経由での事後変更は不可。変更はすべてTOML → deployのフローで行う

課題: 顧客セグメントをメタオブジェクトで管理し、注文・顧客データとの掛け合わせ分析をShopifyQL上でアドホックに行いたい
打ち手: 顧客メタフィールドで参照するメタオブジェクト定義（セグメント名・ランク等）に対してcapabilities.analytics_queryable = trueを設定し、ShopifyQLのFROM/WHERE句で活用
効果: SQLライクな構文で「ゴールドランク顧客の平均LTV」などをリアルタイムに集計。外部DWHへのエクスポートなしにShopify内で分析完結
技術メモ: 顧客メタフィールドが当該メタオブジェクトを参照している必要あり。マーチャント所有のメタオブジェクト定義は対象外（Shopify管理画面からオン/オフ）

5技術者目線の重要ポイント

項目	詳細
対象APIバージョン	GraphQL Admin API 2027-01以降で`capabilities.analyticsQueryable.enabled`フィールドを確認可能
既存定義への影響	キーを追加しない限りcapabilityはオフのまま。既存アプリへの自動影響は一切なし
API管理定義との使い分け	GraphQL APIで作成した定義は`metaobjectDefinitionCreate`/`metaobjectDefinitionUpdate`の`analyticsQueryable`引数で設定（API 2027-01以降）。TOMLとAPIの管理方式は混在不可
バリデーションエラー	対応フィールド型が1つも存在しない定義に`analytics_queryable = true`を設定してdeployするとリリース失敗。事前にフィールド型を確認・追加すること
マーチャント所有定義	マーチャントが所有するメタオブジェクト定義はこの設定対象外。Shopify管理画面からのみオン/オフ可能
参照条件	商品・商品バリアント・顧客・注文のメタフィールドが当該メタオブジェクトを参照している場合にのみAnalyticsで活用可能