記事のサマリー(TL;DR)
- アプリはshopify.app.tomlの
[metaobjects.app.<name>]で宣言するメタオブジェクト定義に、capabilities.analytics_queryableを設定できるようになりました。 trueに設定すると、single_line_text_field、number_integer、date、product_referenceなどanalytics互換の型を持つフィールドが、analyticsレポートやShopifyQLでディメンション・フィルタとして利用可能になります。- キーを追加しない限り機能はオフのままのため、既存の定義に対する対応は不要です。
詳細
何が変わったか
shopify.app.tomlの[metaobjects.app.<name>]で宣言されたメタオブジェクト定義で、capabilities.analytics_queryableが利用できるようになりました。これをtrueに設定すると、その定義上のフィールドのうちanalytics互換の型(single_line_text_field、number_integer、date、product_referenceなど)を持つものが、analyticsレポートおよびShopifyQLにおいてディメンションおよびフィルタとして利用可能になります。この仕組みは、商品、商品バリアント、顧客、注文のメタフィールドがそのメタオブジェクトを参照している場合に機能します。対応していない型のフィールドは無視されます。
これまでは、アプリがこの機能を設定できるのはGraphQL Admin API経由のみで、かつTOMLで管理していない定義に対してのみでした。宣言的な(TOMLで管理する)定義はAPIを通じて読み取り専用であったため、クエリ可能にする方法がありませんでした。
対象となるアプリ・定義
今回の変更は、shopify.app.tomlでメタオブジェクト定義を宣言しているアプリに適用されます。既存の定義は変更されません。定義にこのキーが含まれていない場合、機能はオフのままです。
以下には適用されません。
- GraphQL Admin APIで作成したメタオブジェクト定義。これらについては、API version 2027-01以降の
metaobjectDefinitionCreateまたはmetaobjectDefinitionUpdateミューテーションでanalyticsQueryableを設定します。 - マーチャントが所有するメタオブジェクト定義。これらについてはマーチャントがShopify管理画面でanalyticsのオン・オフを切り替えます。
必要な対応
特別な対応は不要です。宣言済みのメタオブジェクト定義をanalyticsでクエリ可能にするには、以下の手順を行います。
- shopify.app.toml内の定義に
capabilities.analytics_queryable = trueを追加し、少なくとも1つのフィールドがanalytics互換の型を持つようにします。 - アプリ設定を開発ストアにデプロイします。
- GraphQL Admin API version 2027-01以降で、定義の
capabilities.analyticsQueryable.enabledフィールドがtrueになっていることを確認し、その定義を参照する商品・バリアント・顧客・注文メタフィールドのanalyticsレポートにフィールドが表示されることを確認します。
設定例は以下の通りです。
[metaobjects.app.designer]
name = "Designer"
capabilities.analytics_queryable = true
[metaobjects.app.designer.fields.country]
name = "Country"
type = "single_line_text_field"
この例では、designerメタオブジェクトのcountryフィールドをクエリ可能にしています。実際の設定時は、定義とフィールドを自身のものに置き換える必要があります。
なお、定義内のいずれのフィールドも互換性のある型を持たない場合、リリースはバリデーションに失敗するため、デプロイ前にフィールドを追加または変更する必要があります。
関連ドキュメント
- Make your metaobjects queryable in analytics
- Metaobject TOML reference
- metaobjectDefinitionCreate mutation