Query by metafield value

It's possible to query Shopify resources by their custom field values. This is useful if you want to, for example, find products with specific metafield values or metaobjects with specific field values.

Not all metafield types support query filtering. The following types can be used in queries (see complete list with details):

• Single line text or Single line text (list)
• Product reference or Product reference (list)
• True or false
• Collection reference or Collection reference (list)
• Page reference or Page reference (list)
• Metaobject reference or Metaobject reference (list)
• Company reference or Company reference (list)

Anchor to Querying products by metafield valueQuerying products by metafield value

Products, collections, and other core Shopify resources can be filtered by their metafield values using the GraphQL Admin API's query parameter. The syntax for metafields on core resources (such as products) is metafields.{namespace}.{key}:{query_value}.

Anchor to Querying metaobjects by field valueQuerying metaobjects by field value

Use the fields.{key}:{value} syntax to query metaobjects based on their field values, including text fields, reference fields, and taxonomy fields.

Anchor to Querying metaobjects by taxonomy reference field valueQuerying metaobjects by taxonomy reference field value

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

Anchor to Querying metaobjects using a simple single line text fieldQuerying metaobjects using a simple single line text field

Filter metaobjects by exact text field matches:

Anchor to Single-value metafield queriesSingle-value metafield queries

Build on the basic query syntax with these advanced examples showing how to query different metafield types, combine multiple conditions, and handle special cases like multi-value fields.

Anchor to Querying products by boolean metafieldQuerying products by boolean metafield

Find all products that are marked as eco-friendly:

Anchor to Querying products by numeric metafieldQuerying products by numeric metafield

Find products with a specific warranty period:

Anchor to Querying products by collection reference metafieldQuerying products by collection reference metafield

Find products that reference a specific collection:

Anchor to Multi-value metafield queriesMulti-value metafield queries

When querying list fields, the search matches if ANY value in the list equals the search term. This applies to all list types including text lists, reference lists, and multi-select fields.

Anchor to Querying products with multi-value text list metafieldsQuerying products with multi-value text list metafields

Find products that have a specific tag in a list of tags:

Anchor to Querying products with multi-value product reference listsQuerying products with multi-value product reference lists

Find products that reference a specific related product:

Anchor to Querying metaobjects with multi-value fieldsQuerying metaobjects with multi-value fields

Find metaobjects that contain a specific value in a list field:

Anchor to Combining multiple metafield queriesCombining multiple metafield queries

Build complex queries by combining multiple metafield conditions using AND/OR operators. This allows you to filter products based on multiple criteria simultaneously, such as finding products that meet all specified conditions or any of them.

Anchor to Query with multiple metafield conditionsQuery with multiple metafield conditions

Find products that match multiple metafield criteria:

Anchor to Query with OR conditionsQuery with OR conditions

Find products that match any of the specified conditions:

Anchor to Troubleshooting common query issuesTroubleshooting common query issues

If your metafield queries aren't working as expected, check these common issues and their solutions. Most problems stem from missing configuration, incorrect syntax, or misunderstanding how different metafield types handle query values.

Anchor to Issue: Query returns all products/metaobjects instead of filtered resultsIssue: Query returns all products/metaobjects instead of filtered results

Problem: Your query isn't filtering results as expected, returning all items instead of just those matching your metafield criteria.

Solution: Ensure the metafield has filtering enabled.

Anchor to Issue: "Invalid query" or syntax errorsIssue: "Invalid query" or syntax errors

Problem: Your query string may have incorrect syntax.

Common mistakes and fixes:

1. Missing quotes around values:

   • ❌ Wrong: metafields.custom.color:blue
   • ✅ Correct: metafields.custom.color:\"blue\"

2. Incorrect namespace/key separator:

   • ❌ Wrong: metafields.custom:material:\"cotton\"
   • ✅ Correct: metafields.custom.material:\"cotton\"

3. Wrong syntax for metaobjects:

   • ❌ Wrong: metafields.color:\"blue\"
   • ✅ Correct: fields.color:\"blue\"

Anchor to Issue: Multi-value metafield queries not workingIssue: Multi-value metafield queries not working

Problem: Queries against list fields return unexpected results.

Solution: Remember that multi-value queries match if ANY value in the list matches:

Anchor to Issue: Boolean metafield queries not workingIssue: Boolean metafield queries not working

Problem: Boolean values aren't matching correctly.

Solution: Try using lowercase true or false without quotes:

Anchor to Issue: Reference field queries failingIssue: Reference field queries failing

Problem: Can't query by product/collection/metaobject references.

Solution: Try using the full GID (Global ID) format:

Anchor to Issue: Case sensitivity problemsIssue: Case sensitivity problems

Problem: Queries don't match when case differs.

Solution: Metafield queries are case-sensitive. Ensure exact matching:

Anchor to Issue: Special characters in query valuesIssue: Special characters in query values

Problem: Values with quotes or special characters break the query.

Solution: Escape special characters properly:

Anchor to Best Practices for Metafield QueriesBest Practices for Metafield Queries

1. Always enable filtering first. Before attempting queries, ensure the metafield definition has adminFilterable enabled.

2. Test with simple queries. Start with basic single-field queries before combining multiple conditions.

3. Use GraphiQL for testing. Test your queries in the GraphiQL explorer before implementing in code.

4. Paginate large result sets. Use cursor-based pagination for better performance:

5. Monitor query performance. Complex metafield queries can be slower than standard field queries. Consider caching results when appropriate.

Anchor to Related ResourcesRelated Resources

• Enabling metafield filtering
• Metafield definitions
• GraphQL query documentation