Type: Developer Guide / Fix · Stage: Scale · Topic: Metaobjects / Shopify Analytics / ShopifyQL
On this page
Quick answer
Shopify can report on eligible metaobject fields when a product, variant, customer, or order references that metaobject through a supported metafield. The definition must be enabled for analytics, and the report follows the reference to the metaobject field. On October 20, 2026, Shopify announced that the GraphQL Admin API 2027-01 schema exposes the analyticsQueryable capability for metaobject definitions. As of this article’s date, 2027-01 is a release candidate; do not assume that field exists on a production app pinned to 2026-10.
Why a metaobject can exist but not appear in a report
Consider a Designer metaobject with a country text field. Merchandising links a product to a Designer through product.metafields.custom.designer. The store wants sales grouped by the designer’s country. The data may exist in Shopify Admin and still be unavailable in a report if the definition is not analytics-enabled, its fields are ineligible, the product does not reference an entry, or the reference uses an unsupported type.
This is different from adminFilterable, which controls supported Admin API and admin-list filters. Analytics uses a separate analyticsQueryable capability. Turning on one does not substitute for the other.
Trace the complete data path
- Confirm the metaobject definition exists, and inspect its field types. At least one analytics-compatible field is required; text, numbers, and dates are common examples.
- Confirm a product, variant, customer, or order has a metaobject reference or list of metaobject references pointing to an entry of that definition.
- Check that the field you want to report on is populated in the referenced entry. A definition by itself supplies no values.
- Open Settings → Metafields and metaobjects, select the definition, and check the merchant-facing Filter or group data in Analytics setting where available.
- For an app that manages definitions, use GraphQL Admin API 2027-01 or later to inspect
eligibleandenabled. App-created definitions can remain disabled until explicitly enabled.
Read the capability using the 2027-01 API
This query uses the metaobject’s type, not an entry handle. It requires access to metaobject definitions:
query DesignerAnalyticsCapability {
metaobjectDefinitionByType(type: "designer") {
id
type
fieldDefinitions {
key
type { name }
}
capabilities {
analyticsQueryable {
eligible
enabled
}
}
}
}
If eligible is false, investigate field types before enabling anything. If eligible but disabled, an authorized app can update the existing definition. Replace the example ID with the real definition GID:
mutation EnableDesignerAnalytics {
metaobjectDefinitionUpdate(
id: "gid://shopify/MetaobjectDefinition/123"
definition: {
capabilities: { analyticsQueryable: { enabled: true } }
}
) {
metaobjectDefinition {
id
capabilities {
analyticsQueryable { eligible enabled }
}
}
userErrors { field message code }
}
}
Read userErrors, including CAPABILITY_NOT_ELIGIBLE. Never silently declare success because a GraphQL mutation returned HTTP 200. When maintaining stage and production stores, compare the capability in both environments instead of copying a definition’s fields and assuming the configuration followed.
Query the reference, not the metaobject table
For a product metafield custom.designer referencing a Designer with country, Shopify documents this ShopifyQL pattern:
FROM sales
SHOW total_sales
GROUP BY product.metafields.custom.designer.country
The path starts with the resource holding the reference. ShopifyQL does not start from an arbitrary metaobject entry and find every record pointing to it. A mixed-reference metafield is not supported for these metaobject field queries. For a list reference, use supported list semantics such as CONTAINS when filtering. Do not confuse this capability with a general-purpose relational join or a replacement for a PIM.
Common misunderstanding
“Every metaobject field is automatically a report dimension.” Eligibility, the definition setting, the reference type, and populated values all matter. “The new GraphQL field should work on 2026-10.” Shopify announced it for 2027-01; earlier API versions do not expose it. “We need to duplicate the data into a text metafield.” A valid metaobject reference may already provide the report dimension you need.
How to test this
- On a development store, create two Designer entries with different
countryvalues and attach them to test products using a metaobject-reference metafield. - Check the merchant analytics setting. On a test client using API 2027-01, read
eligibleandenabledbefore and after any capability change. - Run the ShopifyQL query and compare the groups with known product-reference assignments and eligible sales data.
- Remove a reference from a test product and confirm that the report no longer attributes that product to the previous Designer.
- Test an ineligible definition and a mixed-reference metafield to document unsupported cases. Do not deploy the 2027-01-specific GraphQL field to a 2026-10-only production client.
Sources and further reading
- Shopify changelog: Metaobject analytics queryable capability (October 20, 2026)
- Shopify: Analytics app development and metaobject field queries
- Shopify Help Center: ShopifyQL syntax and metaobject references
- GraphQL Admin API 2027-01: metaobjectDefinitionByType
Documentation checked October 22, 2026. API version 2027-01 is a release candidate at this time.

