Skip to main content

Query metaobjects

Query metaobjects by their field values to find entries that match specific criteria. Use this to build dynamic searches, filter content, or find metaobject entries based on their data.

Anchor to PrerequisitesPrerequisites

Before querying by field value, you need a metaobject definition with entries created.

Anchor to Query syntaxQuery syntax

Use the fields.{key}:{value} syntax to query metaobjects based on their field values:

metaobjects(type: "your_type", query: "fields.field_name:\"value\"")

Anchor to Query examplesQuery examples

The following examples demonstrate how to query metaobjects by different field types.

Anchor to By text fieldBy text field

Filter metaobjects by exact text field matches.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query Metaobjects {
metaobjects(first: 20, type: "custom--product-feature",
query: "fields.feature_name:\"waterproof\"") {
edges {
node {
id
displayName
type
name: field(key: "feature_name") { value }
updatedAt
createdAt
}
}
}
}

Anchor to By taxonomy referenceBy taxonomy reference

Find metaobjects classified with specific taxonomy values like colors or materials.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query Metaobjects {
metaobjects(first: 20, type: "shopify--color-pattern",
query: "fields.taxonomy_reference:\"gid://shopify/TaxonomyValue/2\"") {
edges {
node {
id
displayName
type
name: field(key: "color_taxonomy_reference") { value }
updatedAt
createdAt
}
}
}
}
Note

This example uses the GID structure for the taxonomy node for the color blue. You can find GIDs for taxonomy nodes in the open source Taxonomy Explorer.

Anchor to By list fieldsBy list fields

Find metaobjects that contain a specific value in a list field. The query matches if ANY value in the list matches the search term.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query MetaobjectsByListValue {
metaobjects(first: 20, type: "custom--product_feature",
query: "fields.supported_devices:\"iPhone 15\"") {
edges {
node {
id
displayName
field(key: "supported_devices") {
value
}
}
}
}
}

Anchor to Best practicesBest practices

  • Test queries in GraphiQL before implementing in code.
  • Use pagination for large result sets with cursor-based pagination.
  • Be case-sensitive - metaobject field queries are case-sensitive.
  • Quote values - always wrap query values in escaped quotes: \"value\"

Anchor to Next stepsNext steps

Was this page helpful?