Analytics queryable capability is configurable in shopify.app.toml for metaobject definitions

Apps can now set capabilities.analytics_queryable on metaobject definitions in shopify.app.toml. This makes compatible fields on those definitions queryable in Shopify analytics and ShopifyQL. It applies to apps that declare metaobject definitions in their app configuration. No action is required, because the capability stays off unless you add the key.

What changed

Metaobject definitions declared under [metaobjects.app.<name>] in shopify.app.toml now accept capabilities.analytics_queryable. When you set it to true, any field on the definition with an analytics-compatible type, such as single_line_text_field, number_integer, date, or product_reference, becomes available as a dimension and filter in analytics reports and ShopifyQL. This works wherever a product, product variant, customer, or order metafield references the metaobject. Fields with other types are ignored.

Previously, an app could only set this capability through the GraphQL Admin API, and only on definitions it didn't manage in TOML. Declarative definitions are read-only through the API, so there was no way to make them queryable.

Who's affected

This applies to apps that declare metaobject definitions in shopify.app.toml. Existing definitions don't change. If a definition doesn't include the key, the capability stays off.

It doesn't apply to these:

• Metaobject definitions that you create with the GraphQL Admin API. For those, set analyticsQueryable with the metaobjectDefinitionCreate or metaobjectDefinitionUpdate mutation in API version 2027-01 or later.
• Metaobject definitions that merchants own. Merchants turn analytics on or off for those in the Shopify admin.

What to do

No action is required. To make a declared metaobject definition queryable in analytics:

1. Add capabilities.analytics_queryable = true to the definition in shopify.app.toml, and make sure at least one of its fields has an analytics-compatible type.
2. Deploy your app configuration to a development store.
3. Confirm that the definition's capabilities.analyticsQueryable.enabled field is true in GraphQL Admin API version 2027-01 or later, and that its fields appear in analytics reports for the product, variant, customer, or order metafield that references it.

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

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

This example makes the country field of the designer metaobject queryable. Replace the definition and fields with your own. If none of a definition's fields has a compatible type, the release fails validation, so add or change a field before you deploy.

Related docs

• Make your metaobjects queryable in analytics
• Metaobject TOML reference
• metaobjectDefinitionCreate mutation