---
title: >-
  Analytics queryable capability is configurable in shopify.app.toml for
  metaobject definitions - Shopify developer changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: >-
    https://shopify.dev/changelog/posts/analytics-queryable-capability-is-configurable-in-shopify-app-toml-for-metaobject-definitions
  md: >-
    https://shopify.dev/changelog/posts/analytics-queryable-capability-is-configurable-in-shopify-app-toml-for-metaobject-definitions.md
metadata:
  effectiveApiVersion: ''
  affectedApi: []
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: New
    handle: new
  indicatesActionRequired: false
  createdAt: '2026-10-19T16:26:15-04:00'
  postedAt: '2026-10-23T12:00:00-04:00'
  updatedAt: '2026-10-27T14:33:38-04:00'
  effectiveAt: '2026-10-23T12:00:00-04:00'
---

October 23, 2026

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

DateOctober 23, 2026

FlagsNew

SurfacesAPI

Apps can now set [`capabilities.analytics_queryable`](https://shopify.dev/docs/apps/build/metaobjects/use-metaobject-capabilities#make-your-metaobjects-queryable-in-analytics) 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](https://shopify.dev/docs/api/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.

```toml
[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](https://shopify.dev/docs/apps/build/metaobjects/use-metaobject-capabilities#make-your-metaobjects-queryable-in-analytics)
* [Metaobject TOML reference](https://shopify.dev/docs/apps/build/metaobjects/manage-metaobject-definitions#toml-reference)
* [`metaobjectDefinitionCreate` mutation](https://shopify.dev/docs/api/admin-graphql/2027-01/mutations/metaobjectDefinitionCreate)